Weblog

Administrators - Req.

Created by OpenACS community, last modified by Benjamin Brink 07 Jul 2017, at 07:11 AM

Site and System Administrators - Documentation Requirements

By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.

OpenACS administrators' documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

• For each requirement below, include links to developer tutorials and other documentation for more detail.

• Describe a structural overview of a working system and how the components work together. "The Layered Cake view" a general network view of system; a table showing system levels versus roles to help with understanding how the subsystems are interconnected.

• Provide a comprehensive description of typical administrative processes for operating an OpenACS system responsibly, including reading logs and command line views that describe status of various active processes.

• Create a list of administrative tools that are useful to administrating OpenACS, including developer support, schema-browser and api browser. Link to AOLserver's config file documentation.

• Resources on high level subjects such as web services, security guidelines

• Describe typical skill sets (and perhaps mapped to standardized job titles) for administrating an OpenACS system (human-resources style). For a subsite admin/moderator attributes might include trustworthy, sociable, familiarity with the applications and subsystems, work/group communication skills et cetera

• Describe how to set up typical site moderation and administration including parameters, permissions, "Hello World" page

• Show directory structure of a typical package, explanation of the various file types in a package (tcl,adp,xql) and how those relate to the previously described subsystems, when they get refreshed etc.

• Ways to build a "Hello World" page

• Show examples of how the OpenACS templating system is used, including portal sections of pages. For example, create a customised auto-refreshing startpage using lars-blogger, a photo gallery, and latest posts from a forum. This should rely heavily on documentation existing elsewhere to keep current. This would essentially be a heavily annotated list of links.

• Show ways of modifying the look and feel across pages of an OpenACS website. Refer to the skins package tutorial.

• Describe a methodology for diagnosing problems, finding error statements and interpreting them --for OpenACS and the underlying processes.

• FAQs: Administration tasks commonly discussed on boards: admin page flow, how to change the looks of a subsite with a new master.adp, options on "user pages" , a quick introduction to the functions and processes. info about the user variables, file locations

Pull in docs from: https://openacs.org/doc/acs-admin.html

Getting admin-level help

Created by OpenACS community, last modified by Benjamin Brink 07 Jul 2017, at 07:06 AM

Keeping track of the commands you run and recording their output has important diagnostic value. I like to create a literal history of my installations in a shell inside of emacs (M-x shell) so that I can save the output if needed. An alternative would be to use the script command.

Check the error logs. We point out the location of error logs for the various pieces of software. Output from those logs will help you, and help us help you. Do not worry if you feel overwhelmed by all the information in the error logs. Over time, you will find that they make more and more sense. At some point, you may actually look forward to errors so that you can run to the log and diagnose the problem.

If something goes wrong, do not panic. There are plenty of ways to get help. Here are some:

• Search the forums at openacs.org - Frequently, people who have struggled through the same issue have already posted and received help with answers immediately available to you.

• The bottom of each page has a link to OpenACS.org, where you can post comments and read other users comments about the contents of the page.

• Post a question on the forums. Make sure you've done a search first. When you do post, be sure to include your setup information (OS, etc) as well as the exact commands that are failing with the accompanying error. If there is a SQL error in the TCL error or in the log, post that too.

• Ask questions at the irc channel on freenode.net (#openacs). They're knowledgeable and quite friendly if you can keep them on topic.

• If you find errors in this document or if you have ideas about making it better, please post them in the forum or BugTracker.

Refactoring Recipes

Created by Michael Aram, last modified by Michael Aram 04 Jul 2017, at 05:31 PM

The intention of this page is to collect small refactoring snippets that one can/should apply to an existing OpenACS installation in order to improve and modernize its code base. Most of the recipes have already been applied to the official core packages.

Modernize Tcl

1. Refactor foreach {var1.. varN} $list {break} to lassign

   See http://wiki.tcl.tk/1530

   Deprecated code example

   foreach {dog cat} $animalslist break

   Recommended code example

   lassign $animalslist dog cat

   Command line for finding/replacing code

   todo

2. Refactor multiple lindex operations to lassign

   Deprecated code example

   set dog [lindex $animalslist 0]
set cat [lindex $animalslist 1]

   Recommended code example

   lassign $animalslist dog cat

   Command line for finding/replacing code

   todo

3. Brace expr expressions

   Deprecated code example

   [expr $money - 1]

   Recommended code example

   [expr {$money - 1}]

   Command line for finding/replacing code

   todo

4. Replace string equal with eq in expressions

   Deprecated code example

   if {[string equal "" $dog]} {error "I want a dog!"}

   Recommended code example

   if {$dog eq ""} {error "I want a dog!"}

   Command line for finding/replacing code

   todo

5. Replace lsearch with in or ni in expressions

   Deprecated code example

   if {[lsearch -exact $animalslist $dog] != -1 } {error "I dont want a dog!"}

   Recommended code example

   if {$dog in $animalslist} {error "I dont want a dog!"}

   Command line for finding/replacing code

   todo

6. Replace eval with {*} if possible

   Deprecated code example

   eval mycommand $args

   Recommended code example

   mycommand {*}$args

   Command line for finding/replacing code

   todo

Best Practices

1. Use bind variables in SQL statements

   Deprecated code example

   db_string check "SELECT * FROM animals WHERE color = $color;"

   Recommended code example

   db_string check "SELECT * FROM animals WHERE color = :color;"

   Command line for finding/replacing code

   todo

2. Use util::http instead of util_http*, ns_httpget, ::http, ::xo::HttpRequest

Substitute Deprecated Procedures

1. Replace empty_string_p with eq ""

   Deprecated code example

   if {[empty_string_p $dog]} {error "I want a dog!"}
if {![empty_string_p $cat]} {error "I dont want a cat!"}

   Recommended code example

   if {$dog eq ""} {error "I want a dog!"}
if {$cat ne ""} {error "I dont want a cat!"}

   Command line for finding/replacing code

   todo

   Rationale

   Byte-compiled comparisons are faster.

2. Replace exists_and_not_null with info exists and ne

   Deprecated code example

   if {[exists_and_not_null cat]} {error "I dont want a cat!"}

   Recommended code example

   if {[info exists cat] && $cat ne "" } {error "I dont want a cat!"}

   Command line for finding/replacing code

   todo

   Rationale

   Byte-compiled comparisons are faster.

3. Replace ad_parameter with parameter::get

   Deprecated code example

   ad_parameter -package_id 123 SystemURL ""

   Recommended code example

   parameter::get -package_id 123 SystemURL -default ""

   Command line for finding/replacing code

   todo

4. Replace ad_require_permission with permission::require_permission

   Deprecated code example

   ad_require_permission $oid "read"

   Recommended code example

   permission::require_permission -object_id $oid -privilege "read"

   Command line for finding/replacing code

   fgrep -rl "ad_require_permission" packages/ | xargs sed -i.sedbak -r 's/ad_require_permission\s+([^\s]*)\s+([^\s]*)/permission::require_permission -object_id \1 -privilege \2/g'

5. Replace util_unlist with lassign

   Deprecated code example

   util_unlist $animalslist dog cat

   Recommended code example

   lassign $animalslist dog cat

   Command line for finding/replacing code

   todo

OpenACS Handbook

Created by OpenACS community, last modified by Benjamin Brink 03 Jul 2017, at 09:29 PM

• for Everyone docs-end-user
• for Administrators docs-admin
• for Beginning Developers docs-dev-tutorial
• for Developers docs-eng

Documentation Credits doc-credits

Documentation Project Documentation_Project

template::head::*

Created by Lee Denison, last modified by Gustaf Neumann 01 Jul 2017, at 01:25 PM

Implementation Details

State of the Code

Template::head is now done and available in OpenACS 5.4. See https://openacs.org/api-doc/procs-file-view?path=packages/acs-templating/tcl/head-procs.tcl

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 JavaScript code, 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 inadvertently 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 deferred 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, e.g. '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 deferred 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 JavaScript 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 style-sheet 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 style-sheet
• @param alternate sets the rel attribute of the link tag defining to 'alternate style-sheet' 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 initialized 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. 

legacy information

Proposal: template::head::*

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 customized master templates.
• Enable packages developers introduce package specific JavaScript 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 data structures, 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.

Modifying the look of an installation

Created by Ryan Gallimore, last modified by Benjamin Brink 30 Jun 2017, at 05:23 PM

Please refer to OACS Theming for newer templating information & tutorial.

Template Files 

Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:

• A templated page uses an ADP/Tcl pair. The first line in the ADP file is usually:

  <master>

  If it appears exactly like this, without any arguments, the template processor uses default-master for that subsite. For pages in /var/lib/aolserver/$OPENACS_SERVICE_NAME/www, this is /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adp and the associated .tcl file.

• The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl)

• The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl).

• Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.

Figure 1. Site Templates

CSS Files

 /packages/acs-subsite/www/resources/site-master.css contains styles for the following elements:

• Header
• User Bar
• Footer
• Navigation
• Widgets (Buttons)
• Text Styles
• Portlets
• acs-developer-support (along with /packages/acs-developer-support/www/resources/acs-developer-support.css)

 /packages/acs-subsite/www/resources/default-master.css defines styles for the following elements:

• Table, TR, TD
• Calendar package
• combo boxes (for date dropdowns)

/packages/acs-templating/www/resources contains many other css stylesheets that are appropriately named. Each package may also often have its own stylesheet.

Selva Theme 

Selva simplifies the work of customizing the look and feel of your OpenACS/dotLRN website. You will find Selva's documentation on each installation of openacs, once the package is installed, you will find its documentation as follows: http://yoursite/doc/theme-selva.

Since Selva is based purely on css you can have a better accessibility on designing your site.

Steps in placing logo using Selva 

• Go to http://yoursite/admin/site-map/
• Search on theme-selva package and Click on its parameter link
• Look for the parameter named " logoUrl" and place the the filename or URL of the Logo that you want to put in.
• Go to http://yoursite/admin/site-map/, look for "Main Site" and click on parameters, then set the DefaultMaster parameter to  /packages/theme-selva/www/selva-master

Note: This instruction assumed that you have already installed the package theme-selva in your openacs installation.

tdom_0.8.3.orig.tar.gz

Created by Stefan Sobernig, last modified by Benjamin Brink 30 Jun 2017, at 05:12 PM

The original file

User interface mockups

Created by Dave Bauer, last modified by Benjamin Brink 30 Jun 2017, at 05:09 PM

Files in XoWiki

Created by Benjamin Brink, last modified by Benjamin Brink 30 Jun 2017, at 05:06 PM

Most Popular Pages

Created by Gustaf Neumann, last modified by Benjamin Brink 30 Jun 2017, at 07:15 AM