Index: openacs-4/packages/layout-manager/www/doc/includelets.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/layout-manager/www/doc/includelets.adp,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/layout-manager/www/doc/includelets.adp 30 Jul 2008 12:02:10 -0000 1.1 @@ -0,0 +1,100 @@ + +How to implement a Layout Manager Includelet +

How to implement a Layout Manager Includelet

+It's an easy, two- or three-step process! +
    +
  1. Write a template which implements the functionality you want to declare as an + includelet (or find a template within a package that already does what you + want). Implement it, if necessary. +
  2. If your Includelet requires parameters other than the package instance it + will be bound to, write an initialization procedure to generate the necessary + values, and store them in the element the Layout Manager will + associate when the includelet is added to a pageset. +
  3. Call the layout manager Tcl API to declare your includelet. +
+If a template already exists that does what you want, and requires no parameters other +than its associated package, only the last step is necessary. For instance, here's the +Tcl API call that creates the Subsites includelet, which just calls the same +subsite-listing template included by the standard acs-subsite index page: +
+layout::includelet::new \
+    -name subsites_includelet \
+    -description "Display Subsites" \
+    -title "Subsites" \
+    -application acs-subsite \
+    -template /packages/acs-subsite/lib/subsites \
+    -required_privilege read
+
+The "name" parameter is the internal name and primary key of the includelet, and must be unique +throughout the system. +

+The "description" parameter should be a human-readable description of what the includelet +does. +

+The "title" parameter provides a default title to use when creating an element from +the includelet. +

+The "application" parameter is the package key that this includelet supports. When an element +is created from this includelet, it will be bound to a single instance of this apm package +type. +

+The "template" parameter is the path to the template which implements the includelet. +

+The "required_privilege" parameter is the privilege a user must have on the application +package an element is bound to in order to see the element. If the user doesn't have +the required privilege on the relevant application package instance, the element won't be +displayed to them. Defaults to "read", the implementer should set it to "admin" when +writing admin includelets. +

Custom Initializer

+It's often necessary to create an initialization procedure for an includelet. The optional +parameter "initalizer" allows one to specify a procedure to be called after an element +is created from an includelet and placed on a layout manager page. For an example, here's +the call which defines the content includelet, which provides a way to generate simple content +with version control (delete, publish, preview, edit): +
+layout::includelet::new \
+    -name content_includelet \
+    -description "Displays the content includelet" \
+    -title "Content Includelet" \
+    -application content-includelet \
+    -template /packages/content-includelet/lib/content-includelet \
+    -initializer content_includelet_utilities::configure_content_id
+
+The initalizer procedure will be called with a single parameter, the id of the element which +is being initalized. This example is slightly simplified from the actual initalizer procedure, +which is generalized a bit for use outside the Layout Manager: +
+ad_proc content_includelet_utilities::configure_content_id {
+    element_id
+} {
+    Create the includelet's item and set the content_id param.
+
+    @param element_id The element to initialize.
+
+} {
+
+    # Get our application's package_id from the element.
+    set package_id [layout::element::get_column_value \
+                       -element_id $element_id \
+                       -column package_id]
+
+    # Create a new content item.
+    set content_id [content::item::new \
+                       -name "Content For $package_id's $parameter" \
+                       -parent_id $package_id \
+                       -context_id $package_id \
+                       -content_type content_includelet_revision \
+                       -storage_type text]
+
+    # Add the content_id parameter to the element.
+    layout::element::parameter::add_values \
+        -element_id $element_id \
+        -parameters [list content_id $content_id]
+}
+
+When an includelet is executed, the local variables package_id and element_id +are always set, along with includelet-supplied parameters defined for the element. In this case, +the local variable content_id will be set when the content-includelet script is +executed. + + Index: openacs-4/packages/layout-manager/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/layout-manager/www/doc/index.adp,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/layout-manager/www/doc/index.adp 30 Jul 2008 12:02:10 -0000 1.1 @@ -0,0 +1,21 @@ + +Layout Manager Documentation +

Layout Manager Documentation

+

Introduction

+The Layout Manager package is a rewrite of .LRN's new-portal package that, as +its name implies, handles page layout and navigation for sets of application includelets. +

Nomenclature has been changed (pagesets rather than portals, etc) to avoid confusion, +and datamodel/script name clashes, with the existing new-portal package. It can be run +in parallel with .LRN/new-portal. +

This package provides no admin UI directly. For information on how to build a subsite +with page layout and navigation managed by the Layout Manager package, see +the documentation for the Layout Subsite Integration package. +

Table of Contents

+ Index: openacs-4/packages/layout-manager/www/doc/new-portal-compare.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/layout-manager/www/doc/new-portal-compare.adp,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/layout-manager/www/doc/new-portal-compare.adp 30 Jul 2008 12:02:10 -0000 1.1 @@ -0,0 +1,39 @@ + +New Portal Comparison +

New Portal Comparison

+New Portal is the original version of the OpenACS portals package written for +.LRN. This package is inadequate for a variety of reasons: +
    +
  • Can't run standalone (is tied to .LRN) +
  • Defining a portlet requires the writing of dozens of lines of boilerplate SQL code +for Oracle and PostgreSQL. +
  • Defining a portlet requires the writing of dozens of lines of custom Tcl code to implement +a fairly complex service contract. Among other things, the portal has to "know" how to +add itself to a new-portal page and to remove itself as well. The new-portal package itself provides very limited management help. +
  • Likewise, in order to add an application which supports portlets, one must implement a .LRN applet or similar functionality. new-portal provides no configuration help. +
  • Portlets are called with parameters passed in an array. It's impossible to wrap an existing +template with a portlet definition and run it unchanged (i.e. share it with existing code) +without providing an intermediate interface template. +
  • There's a lot of magic HTML generated within the new-portal package's Tcl library. +
+By comparison, the Layout Manager package: +
    +
  • Provides a simple Tcl API for defining a new includelet. No SQL or service contract +implementation is required. An includelet may provide an optional initializer +procedure, for instance to create a private calendar for a user if desired, etc. +
  • Parameters are defined directly, by name, when an includelet's template is rendered, +just as is true when they're passed using the template system's <include> tag. +
  • All rendering is done through use of <include> tags, and a simple Tcl API is +provided to allow the addition of custom page templates (which define page layout), themes, +etc. +
  • The Layout Manager is a service, and is not meant to be mounted, so provides no +User Interface for the customization of page layout, etc. However, there is a library of +templates which are designed to be included (see the Layout Subsite Integration package +for an example of how to use these). +
  • Though the Layout Manager itself provides no assistance in the managing of +applications and their associated includelets, the Layout Subsite Integration package +provides a very flexible admin interface that can be used to build a subsite interactively, +with no programming required. Alternatively, the install.xml facility, or a script +accesing the Layout Manager Tcl API directly, can be used for site building. +
  • All rendering operations are heavily cached, so performance should be much better than +new-portal's (queries required for page and navigation tab rendering are all cached). Index: openacs-4/packages/layout-manager/www/doc/page-config.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/layout-manager/www/doc/page-config.adp,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/layout-manager/www/doc/page-config.adp 30 Jul 2008 12:02:10 -0000 1.1 @@ -0,0 +1,18 @@ + +Page Configuration Library +

    Page Configuration Library

    +Though the Layout Manager package is a service, and not meant to be mounted, configuration +of pagesets is something any client of the package will want to implement. Therefore, a set +of templates is provided that can easily be included by templates in a package that's a client +of the Layout Manager, such as the Layout Subsite Integration package that +simplifies the configuration and use of subsite content generated by includelets. +

    Structure

    +The library is structured much like the set of templates that render a page set, i.e. +hierarchically. The pageset-configure template allows one to set pageset specific parameters +(i.e. theme, name) and then includes the page-configure template once for each of the pages that +make up the pageset. The page-configure template in turn allows one to set page-specific +parameters (i.e. page template, theme, name) and includes column-configure for each column +that makes up the page. The column configure page includes an admin version of each +element in the column, which allows one to move the element to another column or page, to +change the theme associated with the element, and its title. +

    To see it in action, mount and explore the Layout Subsite Integration package. Index: openacs-4/packages/layout-manager/www/doc/page-templates.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/layout-manager/www/doc/page-templates.adp,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/layout-manager/www/doc/page-templates.adp 30 Jul 2008 12:02:10 -0000 1.1 @@ -0,0 +1,28 @@ + +Page Templates +

    Page Templates

    +A page template renders a page with a fixed number of columns, optionally declaring custom CSS +to do so. The standard templates included with the Layout Manager package are designed +to work with the standard OpenACS css classes which were implemented in the core release 5.3, +and derived from the earlier Theme Zen package released with .LRN. +

    Declarating a Page Template

    +
    +layout::page_template::new \
+    -name 1_column \
+    -description #layout-manager.simple_1column_layout_description# \
+    -columns 1 \
+    -template /packages/layout-manager/lib/page-templates/simple
+
    +The "name" parameter must be unique across the system and is used internally as the +page template's primary key. +

    +The "description" parameter is the text displayed to the user when they choose a format for a page. +

    +The "columns" parameter declares the number of columns this template expects. The layout manager ensures that the number of columns built for a page is less than or equal to this parameter (it will be less if there are fewer elements than columns placed on a page). +

    +The "template" parameter is the full path to the template which will build the page. It is +possible to write a single script to handle a family of page template declarations, indeed +the provided "simple" template script does just that. It dynamically assigns a CSS file +associated with the declared page template's name, and dynamically chooses an ADP file to +render the page. + Index: openacs-4/packages/layout-manager/www/doc/render.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/layout-manager/www/doc/render.adp,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/layout-manager/www/doc/render.adp 30 Jul 2008 12:02:10 -0000 1.1 @@ -0,0 +1,22 @@ + +Rendering a Pageset +

    Rendering a Pageset

    +Rendering of a page set is done with a simple hierarchical set of templates, which can be +found in the /layout-manager/lib/render directory. Rendering consists of the following +steps: +
      +
    • include the render pageset template, which gets an array of render data for the +given pageset and then +
    • includes the render page template, which gets an array of render data for the current +page within the pageset and then +
    • includes the page template for the given page, which sets the proper CSS for (say) +a thin column on the left and a thick column on the right, and generates the proper HTML for +the number of columns on the page, and then +
    • includes the render element template for each element on the page, which gets an +array of render data for the given element. The includelet referenced by the element +is included, while the theme assigned to the element is declared as the master template. +If the includelet is declared to be .LRN-compatible, parameters are passed in an +array named "cf", otherwise parameters are set directly in the scope of the includelet. +
    +You can safely treat this process as a "black box" when writing an includelet, as +will be obvious when you study some examples. Index: openacs-4/packages/layout-manager/www/doc/themes.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/layout-manager/www/doc/themes.adp,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/layout-manager/www/doc/themes.adp 30 Jul 2008 12:02:10 -0000 1.1 @@ -0,0 +1,40 @@ + +Theme Templates +

    Theme Templates

    +Each layout manager element (a specific instance of a layout manager includelet) is +rendered with an individual master template, called a theme template, which provides +decoration for the element title and content. +

    +Each page set is created with a default theme to use for its elements. Each page +within a page set may override this default, and each element within a page may override the +page's default theme. This gives the page set administrator a great deal of freedom over +look-and-feel. For instance, to recreate the .LRN style where user pages are decorated with +colored boxes, while elements on the admin page are undecorated, assign the standard +theme to the page set, create a page entitled "admin", and assign it the no graphics +theme. +

    +Themes are declared through the Layout Manager Tcl API. +

    Example: +

    +layout::theme::new \
+    -name default \
+    -description "Default OpenACS Theme" \
+    -template /packages/layout-manager/lib/themes/standard
+
    +The "name" parameter is used internally and must be unique through out the system, as it is +used as the primary key for themes. +

    +The "description" parameter is displayed to the user in select widgets used to assign a theme +to a pageset, page or element. +

    +The "template" parameter points to the master template, which typically renders the element title and content, such as is done by the standard theme template: +

    +@template@
+
    +The element content is rendered with the slave template tag. Note that the +standard theme template references the standard portlet classes defined in the default openacs +theme's CSS. These classes are also used by ACS core packages that render content in "boxes", +such as the "application" and "subsite" boxes displayed by the default acs-subsite index page. +Often you can "theme" your site simply by modifying these standard classes, maintaining +a consistent look to "boxes" generated manually by core packages and those generated by the +Layout Manager package. Index: openacs-4/packages/layout-manager/www/doc/themes.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/layout-manager/www/doc/themes.tcl,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/layout-manager/www/doc/themes.tcl 30 Jul 2008 12:02:10 -0000 1.1 @@ -0,0 +1,12 @@ +set template "
    + +
    +
    +

    @title;noquote@

    +
    +
    +     +
    + +
    +
    "