<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
               "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
  <sect1 id="tutorial-pages">
  <title>Creating Web Pages</title>
  
  <authorblurb>
    <para>by <ulink url="mailto:joel@aufrecht.org">Joel Aufrecht</ulink></para>
  </authorblurb>
  
  <sect2>
    <title>Install some API</title>
    <para>As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files:</para>
    <screen>
    <action>cp /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/myfirstpackage/tcl/</action></screen>
    <para>To make this file take effect, go to the <ulink url="/acs-admin/apm">APM</ulink> and choose "Reload changed" for "MyFirstPackage".</para>
  </sect2>
  <sect2>
    <title>Page Map</title>
    <para>Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.</para>
      <figure>
        <title>Page Map</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/tutorial-page-map.png" format="PNG" align="center"/>
          </imageobject>
        </mediaobject>
      </figure>
  </sect2>
  <sect2>
    <title>Build the "Index" page</title>
      <para>Each user-visible page in your package has, typically,
      three parts.  The  <computeroutput>tcl</computeroutput> file
      holds the procedural logic for the page, including TCL and
      database-independent SQL code, and does things like
      check permissions, invoke the database queries, and modify
      variables, and the <computeroutput>adp</computeroutput> page
      holds html.  The <computeroutput>-postgres.xql</computeroutput>
      and <computeroutput>-oracle.xql</computeroutput> files contains
      database-specific SQL.  The default page in any directory is
      <computeroutput>index</computeroutput>, so we'll build that
      first, starting with the tcl file:</para>
      <screen>[$OPENACS_SERVICE_NAME postgresql]$<userinput> cd /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/myfirstpackages/www</userinput>
[$OPENACS_SERVICE_NAME www]$ <userinput>emacs index.tcl</userinput></screen>
      <para>Paste this into the file.</para>      
      <programlisting><xi:include href="../../files/tutorial/index.tcl" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
    <para>Now <computeroutput>index.adp</computeroutput>:</para>
      <programlisting><xi:include href="../../files/tutorial/index.adp" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
      <para>The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.</para>
      <screen>[$OPENACS_SERVICE_NAME www]$<userinput> mkdir /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/myfirstpackage/lib</userinput>
[$OPENACS_SERVICE_NAME www]$<userinput> cd /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/myfirstpackage/lib</userinput>
[$OPENACS_SERVICE_NAME lib]$ <userinput>emacs note-list.tcl</userinput></screen>
      <programlisting><xi:include href="../../files/tutorial/note-list.tcl" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
<screen>[$OPENACS_SERVICE_NAME lib]$ <userinput>emacs note-list.adp</userinput></screen>
<programlisting><xi:include href="../../files/tutorial/note-list.adp" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
<para>You can test your work by <ulink url="/myfirstpackage/">viewing the page</ulink>.</para>
      <para>Create the add/edit page.  If note_id is passed in,
      it display that note, and can change to edit mode if appropriate.  Otherwise, it presents a form for adding notes.</para>
    <screen>[$OPENACS_SERVICE_NAME lib]$<userinput> cd /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/myfirstpackage/www</userinput>
[$OPENACS_SERVICE_NAME www]$ <userinput>emacs note-edit.tcl</userinput></screen>
      <programlisting><xi:include href="../../files/tutorial/note-edit.tcl" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
<screen>[$OPENACS_SERVICE_NAME www]$ <userinput>emacs note-edit.adp</userinput></screen>
      <programlisting><xi:include href="../../files/tutorial/note-edit.adp" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
     <para>And the delete page.  Since it has no UI, there is only a
     tcl page, and no adp page.</para>
<screen>[$OPENACS_SERVICE_NAME www]$ <userinput>emacs note-delete.tcl</userinput></screen>
      <programlisting><xi:include href="../../files/tutorial/note-delete.tcl" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
    </sect2>
  </sect1>

