+
+
+What is an ETP Application?
+
+After you've created a package instance of ETP,
+you've got a virtual directory on your website where you can create and edit
+pages, links, or subdirectories. The pages you create have a very plain
+appearance and behavior: the index page displays a list of the other pages,
+and the other pages simply display whatever content you enter for them.
+This behavior is governed by what's known as the "default application".
+The default application is defined by the ETP package at server startup time as follows:
+
etp::define_application default {
+ index_template packages/editthispage/templates/article-index
+ index_content_type content_revision
+ index_object_name "subtopic"
+ index_title_attr_name "Title"
+ index_description_attr_name "Description"
+ index_content_attr_name "Content"
+
+ content_template packages/editthispage/templates/article-content
+ content_content_type content_revision
+ content_object_name "page"
+ content_title_attr_name "Title"
+ content_description_attr_name "Description"
+ content_content_attr_name "Content"
+
+ allow_subtopics t
+ allow_extlinks t
+ allow_symlinks t
+
+ auto_page_name ""
+}
+
You may customize the default application, or create new
+applications based on it, thereby changing the appearance and content of
+your web pages.
+
Modifying the default application
+It's a good bet that you'll want to alter the appearance of the pages generated by ETP.
+ I highly recommend designing a master template for your site, and ensuring
+that all packages you've installed are using it. (If you don't know what
+a master template is, the ACS Templating Reference will tell you). First, make a copy of the templates you want from ETP:
+cd /web/MYSERVER/www
+mkdir templates
+cp ../packages/editthispage/www/templates/* templates
+
+Now you can change the article-index.adp and article-content.adp to refer to your master template. Next, create a file in the MYSERVER/tcl directory, and add the following code:
+etp::modify_application default {
+ index_template www/templates/article-index
+ content_template www/templates/article-content
+}
+
+After restarting your server, every instance of ETP that's using the "default" application will be rendered using your master template.
+
+Creating new applications
+When you edit a content section in ETP, you'll see a link that says "Choose ETP
+Application". At first this list contains just a few entries: default, faq,
+news, and whatever other example applications were included with the ETP package. You can add your own entries to the list by calling the etp_define_application
+procedure. The real power of defining new applications is that you can create
+templates that reference structured data that is stored for each page in
+the content repository, and ETP gives you the means to edit and organize the structured data. To learn about how that works, please go on to read about Content Types.
+
+
+
+
+
+
+Standard page attributes
+
+The content repository data model (a standard part of OpenACS 4) primarily keeps track of content items, each of which may have multiple content revisions. The content_revision object type refers to a row in the cr_revisions table. Each revision contains the standard attributes of the pages you create with ETP, such as Title, Description, and Content. Additionally, the standard acs_object attributes are stored for each revision, such as the creation date and creating user.
+
+Referring back to the definition of the default ETP application, you'll notice that it specifies that the content_revision
+content type is to be used for the index page and for all content pages.
+ This means that the page templates used by the default application may refer
+to only the standard page attributes stored in the cr_revisions table.
+
+
Extended page attributes: why do we need them?
The standard page
+attributes, while providing all the basic functionality for a collaboratively
+edited website, are rarely sufficient to implement real world designs.Imagine you're creating an online scientific journal. The graphic design
+mockup shows you that each issue of the journal contains a table of contents
+listing all the articles in that issue. However, the table of contents is
+organized into multiple sections: Editorial, Research, Corrections, and so
+on. You also notice that the design assumes that each journal issue has
+a distinguishable publication date, and that each journal article has a distinguishable
+abstract (a quick summary of the writers' findings which can be skimmed or
+searched).
All the standard page attributes (Title, Description, Content, etc.)
+are still useful, but in order to provide the structured data elements implied
+by the journal templates, we need to define some extended page attributes.
+ In particular, we know that journal issues need to have a publication date,
+and journal articles need to have a section and an abstract.
Defining a new content type
+Creating a new content type is done by calling the etp::define_content_type procedure from one of your tcl library files. Here's how you would accomplish the journal example discussed above:
+
+etp::define_content_type journal_issue "Journal Issue" "Journal Issues" {
+ { publication_date "Publication Date" "Publication Dates" string "size=60" "" }
+}
+
+etp::define_content_type journal_article "Journal Article" "Journal Articles" {
+ { section Section Sections string "" "" }
+ { abstract Abstract Abstracts string "rows=24 cols=80" "" }
+}
+
+
+The first 3 parameters to define_content_type
+are the internal name of the content type, the name to display, and the plural
+form of that name. The fourth parameter is a list of records describing
+each extended page attribute. Each record is a list containing the following
+values (in sequence):
+ - attribute_name
+
- pretty_name
+
- pretty_plural
+
- datatype (must be one of the entries in acs_datatypes:
+ string, boolean, number, integer, date, etc.)
+
- html (a string containing html attributes for the input
+ control. useful attributes are "size=X" to specify
+ the size of standard input controls, and "rows=X cols=X"
+ to specify the size of a textarea. Textareas will be
+ used only if the datatype is string and html specifies
+ rows or cols.)
+
- default_value (can either be a string denoting a single default
+ value, or the name of a callback function you've
+ defined in the etp namespace which is used to
+ provide values for select lists).
+
+
+Once you've defined a content type, you may refer to it when calling the etp::define_application procedure to set up a new application. To continue with our journal example, you'd want to do this as follows:
+
+etp::define_application journal {
+ index_template www/templates/journal-issue
+ index_object_name "Journal Issue"
+ index_content_type journal_issue
+
+ content_template www/templates/journal-article
+ content_object_name "Article"
+ content_content_type journal_article
+}
+
+
+Creating the templates that make use of your custom content types is the subject of the next page.
+ After that's been done, the authors of the journal will be able to create
+a new issue of the journal simply by creating a new instance of the ETP package (a process that's automated within the ETP
+interface by the "create subtopic" command) and ensuring that the new content
+section is using the journal application. This setup can be automated, since
+it's possible to specify the application to use for any subtopic created
+within a particular directory.
+
+I'm assuming you've already installed OpenACS 4, loaded
+the data model, and you can see the "Congratulations!" page in your web browser.
+ First, install the ETP package by navigating to the package manager (found at acs-admin/apm), and selecting "Load a new package from a URL or local directory". You may install the latest ETP distribution by entering http://etp.museatech.net/download/editthispage-1.0.apm.
+
+The Package Manager will retrieve the package code, place it in your server's
+packages/editthispage directory, and perform the necessary database
+setup. When that's done, you'll need to restart your server to load all
+of the package's tcl code.
+Now you may test the package by visiting the Site Map (found at admin/site-map),
+creating a new directory, selecting "new application", and choosing Edit
+This Page. Within that directory, anyone who has "write" permission will
+see a link that takes them to the ETP interface from which they may edit the content of the page.
+
However, you're not really having fun until you can modify your home
+page through your web browser. By entering the following commands, you'll
+set up your site so that Edit This Page can also serve pages at the top level
+of the URL hierarchy, including your home page. Doing this will not prevent
+access to the top-level admin pages; the acs-subsite package remains mounted
+at the top level.
cd /web/MYSERVER/www
+mkdir index-backup
+mv index* index-backup
+ln -s ../packages/edittthispage/www/index.vuh .
+
+
+
+
+
+
+
+To use ETP, or in fact to effectively use OpenACS 4, it's essential that you become familiar with the ArsDigita Templating System. ETP's
+support for rapid application development includes procedures for creating
+the data sources that will be used by your page templates. You can copy
+code from the examples in the packages/editthispage/templates directory to get started, but here's an overview of what you need to know.
+
+Providing the "Edit this page" link
+As demonstrated in packages/editthispage/www/master.tcl, you should call the procedure etp::get_etp_link
+from your own master template, in order to determine whether or not to present
+the user with the "Edit this page" option. The procedure returns the html
+link only within an instance of the ETP package, and then only if the user has write access. Otherwise an empty string is returned.
+
+Retrieving page attributes for the template to display
+Every ETP template will make use of the etp::get_page_attributes procedure. It creates an array variable called pa in the caller's stack frame,
+containing all the attributes necessary to render the current page.
+These attributes include the standard elements from the cr_revisions
+table such as title, description, and content. If the page is using
+a custom content type, any extended page
+attributes that correspond to it will be included.
+
+ The complete list of standard attributes in the pa array is as follows:
+
+ - item_id
+
- name
+
- revision_id
+
- title
+
- context_bar
+
- description
+
- publish_date
+
- content
+
- extended attributes, if any, defined by etp::make_content_type
+
+The procedure is designed to be efficient under heavy load. The database
+is accessed once to retrieve the attributes, and a second time to generate
+the page's context bar. The resulting array is then cached in the server's
+memory until someone edits it.
+Once the pa array variable has been created as a template
+data source, the template itself may reference the values it contains using
+the standard syntax for "onerow" data sources; for example, @pa.content@.
+
+
Retrieving the list of pages in a content section
+ETP templates used for the index page will almost always make use of the etp::get_content_items procedure. It creates a variable called content_items
+in the caller's stack frame. This is a multirow result set suitable for
+passing to an index template, containing all the structured data necessary
+to present a list of links to content pages, folders, extlinks, or symlinks.
+ By making use of the procedure's switches you may modify the query results
+it produces:
+
+- -attributes [list] - list of additional page attributes to return (when required for display)
+
- -orderby [list] - list of columns on which to sort.
+
- -where [list] - list of SQL where clauses to restrict the query.
+
+
+ Each row in the result set always contains values for the following page attributes:
+
+ - name
+
- url (use this to generate a link to this item)
+
- title
+
- description
+
- object_type
+
- publish_date
+
- item_id
+
+
+ Additionally, you may name additional attributes that will be
+ returned, either from the standard page attributes stored in
+ cr_revisions, or extended page attributes defined with
+ etp::make_content_type.
+
+ The content_items variable is created with a single db query,
+ and currently is never cached.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+