template::head::*

Proposal: template::head::*

State of the Code

Template::head is now done and available in OpenACS 5.4.

Goals of this proposal, ie. why create template::head::*?

I believe the introduction of these apis would:

• Better position the toolkit to embrace AJAX technologies.
• Make upgrades easier by reducing the need to manually update customised master templates.
• Enable packages developers introduce package specific javascripts and CSS without needing to assess the toolkit wide impact.
• consistent handling for adding code to document head from any tcl script including includes. This means an include that requires a particular css or javascript can add this to the head of the page easily
• for javascript or css, if multiple calls are made for the same resource, it can be loaded only once. In this way code can declare the requirements without needing to know if other code loads the same resource
• Support to add header or footer to the document body

Changes

• Create global datastructures, and associated apis, to programmatically determine the contents of the document head section without the need for template property tags and the maintenance cost that introduces.

Implementation Details

template::head::*

The template::head::* api manipulates the head section of the document that will be returned to the users client.  Packages should use this api to add package specific javascripts, CSS, link tags and meta tags to the HTML document.  The api consists of:

template::head::add_script [-defer] -type <type> [-src <src>] [-charset <charset>] [-script <script>] [-order <order>]

Add a script to the head section of the document to be returned to the users client.  A script library in an external file may only be included once; subsequent calls to add_script will replace the existing entry.  Anonymous script blocks will be added without checking for duplicates; the caller must ensure that anonymous script blocks are not inadvertantly added multiple times.  You must supply either src or script.

• @param type    the type attribute of the script tag, eg. 'text/javascript'
• @param defer   whether execution of the script should be defered until after the page has been loaded
• @param src     the src attribute of the script tag, ie. the source url of the script
• @param charset the charset attribute of the script tag, ie. the character set of the script if it differs from the main document
• @param script  the inline script for the body of the script tag.  This parameter will be ignored if a value has been supplied for src
• @param order default 0 (unordered) order the javascript should be loaded in
  

template::head::add_link -rel <rel> -href <href> [-type <type>] [-media <media>] [-title <title>] [-lang <lang>]

Add a link tag to the head section of the document to be returned to the users client.  A given target document may only be added once for a specific relation; subsequent calls to add_link will replace the existing entry.

• @param rel     the rel attribute of the link tag defining the relationship of the linked document to the current one, eg. 'stylesheet'
• @param href    the href attribute of the link tag, eg. the target document of the link
• @param type    the type attribute of the link tag, eg. 'text/css'
• @param media   the media attribute of the link tag describing which display media this link is relevant to.  This may be a comma separated list of values, eg. 'screen,print,braille'
• @param title   the title attribute of the link tag describing the target of this link
• @param lang    the lang attribute of the link tag specifying the language of its attributes if they differ from the document language

template::head::add_meta [-http_equiv <http_equiv>] [-name <name>] [-scheme <scheme>] [-content <content>] [-lang <lang>]

Add a meta tag to the head section of the document to be returned to the users client.  A meta tag with a given name or http-equiv may only be added once; subsequent calls to add_meta will replace the existing entry.  You must supply either name or http_equiv.

• @param http_equiv the http-equiv attribute of the meta tag, ie. the HTTP header which this metadata is equivalent to eg. 'content-type'
• @param name       the name attribute of the meta tag, ie. the metadata identifier
• @param scheme     the scheme attribute of the meta tag defining which metadata scheme should be used to interpret the metadata, eg. 'DC' for Dublin Core (http://dublincore.org/)      
• @param content    the content attribute of the meta tag, ie the metadata value
• @param lang       the lang attribute of the meta tag specifying the language of its attributes if they differ from the document language 

template::head::add_javascript [-defer] [-src <src>] [-script <script>] [-charset <charset>] [-order <order>]

Add a script of type 'text/javascript' to the head section of the document to be returned to the users client.  This functions is a wrapper around template::head::add_script. You must supply either src or script.

• @param defer   whether execution of the script should be defered until after the page has been loaded
• @param src     the src attribute of the script tag, ie. the source url of the script
• @param script  the inline script for the body of the script tag.  This parameter will be ignored if a value has been supplied for src
• @param charset the charset attribute of the script tag, ie. the character set of the script if it differs from the main document
• @param order optional defaults to 0 (load in order add_javascript is called) set the order a javasript will be loaded
  

@see template::head::add_script

template::head::add_css [-alternate] -href <href> [-media <media>] [-title <title>] [-lang <lang>]

Add a link tag with relation type 'stylesheet' or 'alternate stylesheet', and type 'text/css' to the head section of the document to be returned to the users client.  A given target stylesheet may only be added once; subsequent calls to add_css will replace the existing entry.  This function is a wrapper around template::head::add_link.  

• @param href      the href attribute of the link tag, eg. the target stylesheet
• @param alternate sets the rel attribute of the link tag defining to 'alternate stylesheet' if set, sets it to 'stylesheet' otherwise
• @param media     the media attribute of the link tag describing which display media this link is relevant to.  This may be a comma separated list of values, eg. 'screen,print,braille'
• @param title     the title attribute of the link tag describing the target of this link
  
• @param lang      the lang attribute of the link tag specifying the language of its attributes if they differ from the document language

@see template::head::add_link 

template::add_body_handler [-event <event>] [-script <script>] [-identifier <identifier>]

    Adds javascript code to an event handler in the body tag.  Several
    javascript code blocks may be assigned to each handler by subsequent calls
    to template::add_body_handler.

    If your script may only be added once you may supply an identifier. 
    Subsequent calls to template::add_body_handler with the same identifier
    will replace your script rather than appending to it.

    event may be one of:

• onload
• onunload
• onclick
• ondblclick
• onmousedown
• onmouseup
• onmouseover
• onmousemove
• onmouseout
• onkeypress
• onkeydown
• onkeyup

    @param event      the event during which the supplied script should be
                      executed
    @param script     the javascript code to execute
    @param identifier a name, if supplied, used to ensure this javascript code
                      is only added to the handler once

template::add_body_script [-type <type>] [-defer <defer>] [-src <src>] [-charset <charset>] [-script <script>]

    Add a script to the start of the body section of the document to be returned
    to the users client. You <strong>must</strong> supply either src or script.

    @param type    the type attribute of the script tag, eg. 'text/javascript'
    @param defer   whether execution of the script should be defered until after
                   the page has been loaded
    @param src     the src attribute of the script tag, ie. the source url of the
                   script
    @param charset the charset attribute of the script tag, ie. the character
                   set of the script if it differs from the main document
    @param script  the inline script for the body of the script tag.  This
                   parameter will be ignored if a value has been supplied for
                   src

template::add_header [-direction "outer"] [-src <src>] [-params ""] [-html ""]

    Add a header include to the beginning of the document body.  This function
    is used by site wide services to add functionality to the beginning of a
    page.  Examples include the developer support toolbar, acs-lang translation
    interface and the acs-templating WYSIWYG editor textarea place holder.  If
    you are not implementing a site wide service, you should not be using this
    function to add content to your page.  You must supply either src or html.

    @param direction whether the header should be added as the outer most
                     page content or the inner most
    @param src       the path to the include
    @param params    a list of name, value pairs to pass as parameter to the
                     include
    @param html      literal html to include in the page.  This parameter will
                     be ignored if a values has been supplied for src.

    @see template::add_footer

template::add_footer [-direction "outer"] [-src <src>] [-params <params>] [-html <html>]

    Add a footer include to the end of the document body.  This function
    is used by site wide services to add functionality to the end of a
    page.  Examples include the developer support toolbar, acs-lang translation
    interface and the acs-templating WYSIWYG editor textarea place holder.  If
    you are not implementing a site wide service, you should not be using this
    function to add content to your page.  You must supply either src or html.

    @param direction whether the footer should be added as the outer most
                     page content or the inner most
    @param src       the path to the include
    @param params    a list of name, value pairs to pass as parameter to the
                     include
    @param html      literal html to include in the page.  This parameter will
                     be ignored if a values has been supplied for src.

    @see template::add_header

template::reset_request_vars

Reset all templating variables which must be initialised on every request.

template::reset_request_vars would be called at the beginning of the tcl/adp extension handler (adp_parse_ad_conn_file) to reinitialise the global variables used by this api on each request.