View · Search · Index

Weblog

Filtered by category Coding Standards, 1 - 10 of 18 Postings (all, summary)

Web Forms

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 22 Mar 2019, at 11:21 PM

Use ad_form to create HTML forms. If you work on a page that does not, convert it to use ad_form.

You can grep the toolkit under /packages and see many examples. 

Ad_form can handle many of your possible interactions with the system, such as normal tasks as add and edit data, validate entry form data, etc.

Additional information here:

Rubick on ad_form

Use the following in the tcl part of a page to limit access to page requests via post.. to reduce vulnerability to url hack and insertion attacks from web:

if { [ad_conn method] ne "POST" } {
  ad_script_abort
 }

Grouping elements into sections using ad_form

 

The {-section} list allows to group the subsequent elements (until the next section declaration) into a section. {-section} accepts 4 properties:

 

{-section
	section_id
	{legendtext $legendstring}
	{legend {name value name value ... name value}}
	{fieldset {name value name value ... name value}}
}

where:

  • section_id: a string to identify the section (mandatory)
  • legendtext (optional) a string for the legend of the fieldset (section)
  • legend (optional) a list of name value pairs attributes for the LEGEND tag
  • fieldset (optional) a list of name value pairs attributes for the FIELDSET tag

Example

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

ad_form \
	-name "your_zen_level" \
	-method post -html {enctype multipart/form-data class margin-form} \
	-fieldset {{title "T1" class "C1"} "This really works!!"} \ 	-form {      # Start section 1     {-section "sec1" {legendtext "Section Title I"} {legend {class myClass id myId}}}
    {zen_comment:text(comment)\
                 {label "template::widget::comment"}\
                 {value "Please enter your comments."}\
                 {html {rows 7 cols 50}}}
    {zen_file:text(file),optional\
                 {label "template::widget::file"}}

    # Start section2
    {-section "sec2" {legendtext "Section Title II"} {fieldset {class myclass}}}
    {zen_multiselect:text(multiselect)\
                 {label "template::widget::multiselect"}\
                 {options {"mark" "emma" "avni" "carl" "don"}}}

    # Unset the section. subsequent elements will not be in any section.
    {-section ""}
    {zen_text:text(text),optional,nospell\
                 {label "template::widget::text"}\
                 {help_text {"Your identification tag number"}}}
    {zen_textarea:text(textarea),optional,nospell\
                 {label "template::widget::textarea"}\
                 {help_text {"Please describe your desired state of being"}}\
                 {html {rows 7 cols 50}}}
}

 

Code Formatting

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 14 Feb 2018, at 09:07 AM

  • Use 4 space indentation 
  • Code lines must not exceed 80 characters in length. Never use a single line that has more than 80 chars.
  • Source files should be coded in UTF-8 using Unix-style newlines

These general rules are applicable to Tcl & SQL.

Also, the 80 character limit is important because the OpenACS API browser (at /api-doc/) presents documentation defined in ad_proc's doc_string declaration in html format; whereas ad_proc's body of code is presented wrapped in PRE tags. Longer code lines result in API documentation pages (and their paragraphs) stretching outside of typical browser window width.

If you are using Emacs editor, you usually are on the safe side with regards to Tcl, as the tcl-mode indents just as we want it. ADP pages are formatted correctly when editor is in html-mode.

Formatting SQL Statements

  • A proper format for select statements is
    select ....
    from ....
    where clause
        and clause
        and clause
  • A proper format for insert statements (and note the indentation and overflow of attributes)
    insert into table_name
      (c1, c2, c3 ...
       cx, cy, cz)
    values
      (v1, v2, v3 ...
       vx, vy, vz)
  • A proper format for update statements:
    update table
    set c1=v1,
         c2=v2,
         ...
    where ...

Editor modes

There is an OpenACS mode for emacs OpenACS mode for Emacs which has features to help meet formatting standards.

One can add the following stanza to the end of a .tcl file, when using Emacs, to avoid, that spaces are changed again into tabs.

#
# Local variables:
#    mode: tcl
#    tcl-indent-level: 4
#    indent-tabs-mode: nil
# End:

 

Security Considerations

Allowing user input to include images, see patch in this discussion thread: http://openacs.org/forums/message-view?message_id=182057

Commit Messages

Created by Gustaf Neumann, last modified by Gustaf Neumann 29 Dec 2017, at 10:11 AM

  • Write your commit message in the imperative present tense: Use "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. It should start with a verb like "Fix", "Add" or "Change".
  • Commit message should contain a title and an optional body.
  • The title of the commit message should be a capitalized, short (50 chars or less) summary, not ending with a period.
  • The title can be followed by the body, an explanatory text, if necessary. Title and body are separated by an empty line. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
  • The body should be wrapped to 72 characters.  The body can contain multiple paragraphs, containing plain text or bullet points. The bullet points should be typed as a hyphen or asterisk with blank lines in between. Use a hanging indent for longer bullet points
  • Make white-space changes separately

See also:

Coding Standards - Index

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 06 Aug 2017, at 02:11 PM

A coding style is always important to maintain quality of the code and in this case, the OpenACS project. Here you'll find a set of links that will guide through our most common standards.

The definitive guide on coding standards can be found at OpenACS Style Guide .

Many stuff has been gathered from many post or guides other openacs community members have done, such as:

    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 http://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.

    How to contribute code that passes accessibility tests

    Created by Rocael Hernández Rizzardini, last modified by Benjamin Brink 30 Jun 2017, at 06:10 AM

    About this document

    • Status: DRAFT
    • Updated: 11-jun-2009

    Accessibility Policy

    The policy for .LRN is published at .LRN website: Accessibility Policy

    Corresponding policy for OpenACS is currently being written and will be published soon.

    The conformance level to be satisfied is explained in the "Accessibility Conformance Level" section of the .LRN Accessibility Policy.

    The "Accessibility page" refered by the .LRN Accessibility Policy states the conformance level and its domain of aplication for each version of the software.

    Web Content Accessibility Guidelines

    Note: Although automatic tools, such as TAW and "Cynthia says", may be useful to help the developer/author in addressing accessibility issues by providing informative reports, they can not certify the accessibility level of a page since many things need a manual review. Also, those tools won't be able to check a page protected by user and password (they would report on the login page, the one they can actually reach).

    WCAG version 2.0

    WCAG version 1.0

    • The guidelines: explain how to make Web content accessible to people with disabilities.
    • Checklist of checkpoints to satify for each level of conformance. Each checkpoint is followed by one or more links to techniques in the following documents:
      • "Core Techniques for Web Content Accessibility Guidelines 1.0" ([WCAG10-CORE-TECHNIQUES]), which discusses the accessibility themes and general techniques that apply across technologies.
      • "HTML Techniques for Web Content Accessibility Guidelines 1.0" ([WCAG10-HTML-TECHNIQUES]), which provides examples and strategies for authoring accessible Hypertext Markup Language (HTML) content.
      • "CSS Techniques for Web Content Accessibility Guidelines 1.0" ([WCAG10-CSS-TECHNIQUES]), which provides examples and strategies to help authors write Cascading Style Sheets (CSS) as part of accessible content design.
    • Techniques: gateway to the aforementioned specific ones.

    Contributing Code

    Once the requirements are met, to contribute your code follow these instructions (one of the two):

    1. How to contribute to OpenACS
    2. Contributing code for .LRN: submit your proposal to the .LRN leadership team by:
      • posting at the .LRN Q&A forum
      • joining the weekly meeting on IRC (tuesday at 18:00 CET/CEST)

    Resources

    on-site resources

    External resources

    If you need more information on how to address accessibility, post your questions at the forums

    .LRN Zen Project: Standards

    Created by Avni Khatri, last modified by Gustaf Neumann 22 Jun 2017, at 09:44 AM

    Administration

    • Goal: WAI-AA compliance

    Steps to Cleanup (Zenify) a Package Page

    1. View Page in a browser and view source of page
    2. Check Doctype
    3. Check Title (optional)
    4. Check for H1-Hn and make sure they are in order. If not, make them so.
    5. Close all HTML tags
    6. Make sure there is no inline CSS
    7. Add an ALT attribute for IMG tags
    8. Add a TITLE attribute for A tags as necessary
    9. Check all user visible text and make sure it is using message keys instead of text
    10. If page has a form, make sure it is using formbuilder
    11. If page has data in tabular format, make sure it is using listbuilder
    12. Run accessibility tests

    Doctype

    1. First target: Validated HTML 4.01 Strict
    2. Code:
      <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
    3. Background: Choosing a DOCTYPE . Why not XHTML? See http://www.hixie.ch/advocacy/xhtml

    Basic Page Requirements

    1. Title: should be in title tag, breadcrumbs, and h1 at top of page.
      1. To accomplish that, ADP pages using the <master> tag should pass the following properties.

        <property name="title">Page Title</property>
        <property name="context">{ { breadcrumb_url link_title } .. last_breadcrumb_element, title unless there is a good reason for it to be something else}</property>

        You don't need to manually build the context bar UNLESS you want to include a URL that is not part of the site map. In other words, the context for 99% of pages should just be a one element list containing the page title or other text you want as the last element of the context bar.  (DAVEB)

        Title and context variables are set in the Tcl file so the property call looks like this
        <property name="title">@title;literal@</property>
        <property name="context">@context;literal@</property>
    2. Use message keys instead of text. http://openacs.org/doc/i18n-convert.html 

    Applying new CSS and HTML clean-up 

    • Close HTML tags (LI, P, etc.)
    • ID attributes must start with a letter
    • Styles should be in CSS (no inline styles)
    • Provide an ALT attribute for IMG tags (chekpoint 1.1 - priority 1 - A). The ALT text should be localized. When the image is used for layout only, set an empty string for ALT (ALT="").
    • Clearly identify the target of each link (A tag) by providing an TITLE attribute (checkpoint 13.1 - priority 2 - AA). The text should be meaningful and localized. More Info: https://www.nngroup.com/articles/title-attribute/
    • For data tables, identify row and column headers (checkpoint 5.1 - priority 1 - A). The best is to use list template when it's possible. Otherwise, make sure:
      • your table has a summary tag
      • you use <caption><thead> <tfooot><tbody> where appropriate.
      • you give column and row headers a scope: <thead> <th id=""> <tbody> <td headers="">
      • If you headers are really long you give them abbr.      
        <table class="list-table" cellpadding="3" cellspacing="1" summary="Data for folders">
         <thead>
          <tr class="list-header">
           <th class="list-table" id="folders_name">Name</th>
           <th class="list-table" id="folders_type">Type</th>
           <th class="list-table" id="folders_size">Size</th>
          </tr>
         </thead>
         <tbody>
          <tr class="odd">
           <td class="list-table" headers="folders_name"><a href="#">Course 2 Files</a></td>
           <td class="list-table" headers="folders_type">folder</td>
           <td class="list-table" headers="folders_size">2 items</td>
          </tr>
          <tr class="even">
           <td class="list-table" headers="folders_name"><a href="#">Course 1 Files</a></td>
           <td class="list-table" headers="folders_type">folder</td>
           <td class="list-table" headers="folders_size">2 items</td>
          </tr>
         </tbody>
        </table>
        

    Form Builder and Template

    1. All forms will use the default form template (standard.adp) now. 
      1. Therefore, there is no longer a need to have  the "style" attribute in the formtemplate tag.  (i.e. <formtemplate id=zen style=inline>). We can get rid of this attribute on all forms that currently use it.
      2. Instead, there are different CSS classes that can be applied to all forms to get the same effect of inline.adp, plainest.adp, and other form templates while actually using the zen-ified standard.adp.  The form class to be used is passed in the "html" parameter of the ad_form proc.                                                                     
        • Example:
          • ad_form -name "zen" -method post -html {class vertical-form}..... -form {....}
          • This will render: <form name="zen" method="post" class="vertical-form">
    2. List of form classes available and example URLs.
      • Note: Example forms are checked into the 5.3 branch. Example files are listed below.
      • margin-form : This is the default form class if none is passed to the ad_form proc
        • /packages/theme-zen/doc/forms/index*
      • vertical-form
        • /packages/theme-zen/doc/forms/form-vertical*
      • inline-form : Replaces inline.adp
        • /packages/theme-zen/doc/forms/form-inline*
    3. Example:
      • Change:
        • <formtemplate id=zen style=inline>
      • To:
        • <formtemplate id=zen>
        • And modify the tcl ad_form call to pass a class to the form, so it will be like this:
          • ad_form -name "zen" ... -html {... class inline-form}.... -form {...}
    4. If the form you working on started out as <formtemplate id="zen">, then you probably don't need to change the formtemplate or the form class. The defaults will  most likely work fine. Look at the page in a browser and see how it is rendered.  If you have any questions about which formtemplate to use, ask Mark Wylie.
    5. Fieldsets and Fieldset Legends
      1. Legends need to be short, there is no line wrapping for legends
      2. more fieldset and legend info coming soon
    6. If you have to hand code a form, it should look something like this:
    <form class="margin-form">
     <fieldset>
      <legend>Short Legend</legend>
      <div class="form-item-wrapper">
       <div class="form-label">
        <label for="first_name">First Name</label>
         <div class="form-required-mark">(required)</div>
       </div>
       <div class="form-widget">
        <input type="text" name="first_name" id="first_name" size="30" />
       </div>
       <div class="form-help-text">
        <img src="images/icons/info.png" alt="info" width="16" height="16" /> Some info text
       </div>
       <div class="form-error">
        <img src="images/icons/exclamation.png" alt="error" width="16" height="16" /> This field was in error
       </div>
      </div>
      <div class="form-button">
       <input type="submit" name="formbutton:submit" value="submit" />
      </div>
     </fieldset>
    </form>
    

    Using sections in ad_form

    The "section" element property is not longer supported. See Web_Forms for an example of how to use sections in ad-form.

    List Builder and Template

    When creating a list template that contains links, provide a title attribute (with a meaningful and localized text) for each of them (checkpoint 13.1 - priority 2 - AA). Example:

    template::list::create \
        -name messages \
        -html [list summary "Summary title"] \
        -caption "Optional caption" \
        -multirow messages \
        -page_size $page_size \
        -page_query_name messages_select_paginate \
        -pass_properties { moderate_p } \
        -actions $actions \
        -elements {
            subject {
                label "[_ forums.Subject]"
                link_url_col message_url
                link_html {title "[_ forums.goto_thread_subject]" class "myclass"}
            }
        }

    This is also true for actions list. Example:

    lappend actions [_ forums.Post_a_New_Message]\
    	[export_vars -base "${base_url}message-post" { forum_id }]\
    	[_ forums.Post_a_New_Message]
    

    New Parameters

    • caption - optional
    • summary - required for AA. There is a default in place: "Data for %list_name%" 

     W3C Web Content Accessibility Checkpoints

    Zen aims at being Level AA compliant (priority 2 checkpoints):

     

    Tools for Checking Accessibility

    Accessibility Evaluation Toolbar  (Firefox):

    • Disable javascript: alternatives should be provided to js actions
    • Disable styles (CSS): to verify the render for text only browsers
    • Disable images: ALT texts should appear for each image
    • Display title attribute: a meaningful title should be provided for each link
    • Linearize page: tables should linearize well
    • Validate local HTML
    • Validate local CSS
    • Validate local accessibility
    • Validate package and inline (if you're using the new inline class) CSS.

    Colour Contrast Analyser ( Firefox):

    • Use the "Luminosity Contrast Ratio" option.
    • For the default CSS, the page should pass at level 2
    • For the HC (High Contrast) CSS, the page should pass at level 3

    Fangs, the Screen Reader Emulator (Firefox)

    Hera (automatic and manual reports)

    WebXact (if HERA is not working)

    Others tips

    • Use Opera's View/Small Screen mode to test the handheld.css.

    Important Checkpoints

    • WCAG - Checkpoint 3.5: Use header elements to convey document structure
      and use them according to specification.
    • WCAG - Checkpoint 5.3: Do not use tables for layout unless the table makes sense when linearized. Otherwise, if the table does not make sense, provide an alternative equivalent. Documents with two columns or more use tables to give structure. Layers should be used, instead.

     

    Emacs as an OpenACS IDE

    Created by OpenACS community, last modified by Gustaf Neumann 13 Jun 2017, at 10:30 AM

    emacs integrated development environment for OpenACS

    emacs documentation: http://www.gnu.org/software/emacs/manual/html_node/

    Emacs uses major and minor modes that provide a UI context for editing various file types. Here are some useful ones for working with OpenACS:

    CVS Mode Emacs with OpenACS

    I use M-x cvs-examine to update and check in code when I am working with OpenACS. One thing that is a pain with CVS is that cvs diff does not tell you what you are going to get if you update, it only tells you what is changed in your local copy.

    You can use M-x cvs-examine and then type "d e" next to any of the files in your checkout in the *cvs* buffer to open ediff mode and then interactively merge what's in CVS with your local changes. In ediff mode you use n/p to got to the next/previous difference. You can copy changes from the CVS buffer to your local copy using a/b to copy the the buffer marked A to B or B to A. Type ? on the ediff window to get a list of other commands.

    OpenACS Mode for Emacs

    See historical page describing oacs.el http://web.archive.org/web/20040621200046/www.thecodemill.biz/services/oacs/

     

    Download: oacs.el.tar updated 2006-08-15 . The lastest version includes nXML mode support in addition to PSGML support. There are good installation instructions in the INSTALL.txt file. A quick install guide for Debian

    
     


    sudo su -
    cd /usr/share/emacs/site-lisp
    wget http://www.emacswiki.org/elisp/color-occur.el
    wget http://openacs.org/storage/view/xowiki-resources%5C/oacs.el.tar
    tar xf oacs.el.tar
    apt-get install psgml mmm-mode

    # Alternatively compile manually
    wget http://www.lysator.liu.se/~lenst/about_psgml/psgml-1.2.5.tar.gz
    tar xfz psgml-1.2.5.tar.gz
    cd psgml-1.2.5
    ./configure
    make install
    cd ..
    wget http://switch.dl.sourceforge.net/sourceforge/mmm-mode/mmm-mode-0.4.8.tar.gz
    tar xfz mmm-mode-0.4.8.tar.gz
    cd mmm-mode-0.4.8
    ./configure
    make install

    After this login as the user who is doing the development and edit you .emacs file.

     (add-to-list 'load-path "/usr/share/emacs/site-lisp/oacs")
     (require 'oacs)
     (setq user-full-name "<yourname>")
     (setq user-mail-address "<your email>")
     (add-to-list 'auto-mode-alist '("\\.vuh" . tcl-mode))
     (add-to-list 'auto-mode-alist '("\\.adp" . html-mode))
    

    For recent Emacs versions (> 2008), modify oacs-nxml.el in the downloaded tarball:

     line 30: (load "nxml-mode.el")  instead of (load "rng-auto.el")

    See http://lists.gnu.org/archive/html/emacs-devel/2008-01/msg00947.html

    Also, you may need to modify adp.rnc to the correct path to the xhtml.rnc schema on your installation. On OS X, for example, line 5 should read:

    include "/Applications/Emacs.app/Contents/Resources/etc/schema/xhtml.rnc" 

     

    The following was written by Bart the author of oacs.el

    OpenACS lacked a good Integrated Development Environment and as I use Emacs for almost everything it was only natural to fill the void. The Emacs OACS module is an extension to GNU Emacs, the extensible, customizable, self-documenting real-time display editor.

    Development status

    Emacs OACS's development is driven by the needs I encounter in my OpenACS projects. Development takes place in my spare time. At this stage the code is the documentation. I lack the time to write a proper article. However, as Emacs OACS addresses the issues described in articles XQL Document Type Definition and Replacing SQL bind vars in Emacs some background information can be found in those articles.

    Forum thread: Beta Emacs OACS module available

    Useful commands

    Formating TCL

    • M-o ft to re-format Tcl code. See code for details.
    • M-o fh to reformat Html or Adp code.
    • M-o fs to reformat Sql code.
    • M-x oacs-format-separate-tags to separate adjacent tags. E.g. <tr><td>
    • M-x oacs-format-includes to place all include attribubtes on a separate line.
      
       

    Code navigation

    • M-o oo to search for any custom regular expression.
    • M-o on to search the log for Notice oacs-dbg messages. That is a Notice level message created with the macro 'oddbg'.
    • M-o od to search the log for Debug oacs-dbg messages.
    • M-o oe to search the log for Error oacs-dbg messages. Etc for all other ns_log levels.
    • M-o op to browse Tcl libraries for procedure definitions. This is by far my favorite way of navigating a library!
    • M-o fp (find-file-at-point) to NSD error log mode.
    • M-o rl to revert the logfile
    • M-o ml to to open an error log file and monitor the changes to the log. 

     

    Editing docbook xml

     

    editing via Muse mode

    editing via nXML mode

    See http://openacs.org/doc/nxml-mode.html

    psgml mode

    See:

    Developing with emacs

    To make emacs display .vuh files similar to .tcl files, add to .emacs file:

     (add-to-list 'auto-mode-alist '("\\.vuh" . tcl-mode))

     

    To make emacs display .adp files similar to .html files, add to .emacs file:

     (add-to-list 'auto-mode-alist '("\\.adp" . html-mode))

     

    Common command shortcuts

    Minor Modes

     M-x global-font-lock-mode highlights syntax using colors
     M-x transient-mark-mode   shows a highlighted text region
     M-x show-paren-mode       shows matching parentheses (and when the do not)
    

    Move, Search and Replace

     M-x goto-line             go to a specific line in a file
     M-x goto-char             go to a specific character number in a file
     M-C-f                     search forward for matching brace
     M-C-b                     search backward for matching brace
     M-x replace-regexp        search/replace using regular expressions
     M-x query-replace-regexp  query/search/replace using regular expressions
       note \\( and \\) for start and end subgroups
     M-x grep                  grep creates new buffer with results
                               for fast loading/editing search hits
    
    Useful "sleepers" (not found in many shortcut sheets)
    
     fg<cr>                    restart a suspended emacs session from commandline
     C-q <key press>           add a key without emacs interpreting the key binding
    

    You can configure emacs to create 4 spaces when you press the tab key--important for meeting coding standards. Add this to your .emacs file:

    (setq-default tab-width 4 indent-tabs-mode nil)
    

    other useful quicksheets

    ADP Files

    Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 07 Jun 2017, at 10:54 AM

    • Avoid putting in Tcl code on ADP pages if possible

      Although AOLserver/NaviServer ADP supports placing Tcl codes directing into ADP pages, one should use of OpenACS Templating  or http://openacs.org/doc/acs-templating/  wherever possible.

    • Quote in the master, pass "properties" literally from slave adp files

      when variables are used in templates without modifiers (marked with a ";") then the values of the variables are internationalized and html-quoted. The substitutions should be done at the place, where the variables are actually used, which is for "properties" in the master templates. That the places, where the variable values are just passed on, the modifier ";literal" should be used to prevent quoting and internationalization.

      Master:
         <head> 
         <title>@doc.title@</title>
         </head> 
         <body bgcolor="#ffffff"> 
         <h1>@heading@</h1> 
         <slave> 
         </body>
      Slave:
         <master> 
         <property name="doc(title)">@title;literal@</property> 
         <property name="heading">@title;literal@</property> 
         ...
      Passing arguments to ADP includes:
         <include src="name-of-included-adp" ... var="@value;literal@" ...>
      
      or one can pass variables via reference to the include
         <include src="name-of-included-adp" ... &="varName" ...> 
    • Pass always the "context" and "doc(title)" properties to the site master template
      Example:
         <property name="doc(title)">@title;literal@</property>
         <property name="context">@context;literal@</property>
    • Quote HTML attributes

      Quoting HTML attribute values improves the safety against XSS attacks, especially when the attribute values are variables. Double quotes are preferred over single quotes, both are fine.

    Tcl Procs

    Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 07 Jun 2017, at 09:37 AM

    • Use namespace

      Define your procs with with a namespace like mypackage::foo_proc. Here is a discussion about this . Check many examples in the code, example:

      namespace eval auth {} 
      
      ad_proc -public auth::require_login { 
           {-level ok} 
           {-account_status ok} 
        } { 
           doc...  
           @return something 
           @see ad_script_abort 
        } { 
        ... proc body 
      }
      
    • Use procs safely and their safer variations to help keep code robust and avoid security issues.

      Particularly in cases, where user_input is processed, be sure to avoid executing unwanted code. Use the Tcl expand operator {*} instead of eval. Use
          {*}$cmd
      instead of
          eval $cmd
      For legacy code, you might use  util::safe_eval instead of eval in such cases; subst_safe precedes meta characters with backslashes.

    • Use named parameters whenever possible 

      Define named parameters on your procs so parameters will not be mixed up if somebody makes a mistake on passing the order of parameters. Also this makes the proc easier to add additional parameters in the future if needed.

      Use:

         ad_proc proc_name { {-parent_id pid} {-child_id cid} } ...

      and not

         ad_proc proc_name {pid cid} ...

      This way developers will need to call proc stating explicitly which parameter are passed. This is especially useful when some parameters are optional.

      Also, when calling a proc in your tcl script, is recommended to write one parameter per line like this:

         set my_var [proc_name  \ 
                          -parent_id $pid \ 
                          -child_id $cid]

      Rather than:

         set my_var [proc_name -parent_id $pid -child_id cid]

      Again, this helps to make the code more clean and readable.


    • Use ad_proc to define your Tcl procs

      Make use of ad_proc. And make use of the self documentation facility of ad_proc.

      	ad_proc foo {}
      	   Use this area to document
      	} 
      	   # .... your implementation of proc foo
      	}
      
    • This way the API browser will pick up your documentation automatically. Is encouraged to use automatic api-doc documentation that ad_provides, such as: @author, @return, @see

    • Avoid using upvar

      Try to avoid using upvar. If needed pass in a parameter that specifies the upvar name. This way the one using your proc has option to name his/her variable. Ex.

          ad_proc upvaring {-upvar_name:required} {
              upvar $upvar_name local_var
          }
      
    • Use modern Tcl idioms

      Do not use "==" in comparing strings. Using "if {$string == "foo"}" tries to make a numeric comparison first. Instead make use of "if {"foo" eq $string}" or if you need the negation "if {"foo" ne $string}".

      Do not use "if {[lsearch -exact $list $element] > -1}", but use "if {$element in $list}" instead, or "if {$element ni $list}" in case a "not in" test is required.

    • Always "Return" at the end of your proc

      And if you have to return more than one variable, use associative arrays, which can be extended by additional fields without breaking code

      So instead of this:

         ad_proc ... {
            ..... 
            return [list $creation_status $creation_message ...]
         } 
      use key/value pairs or Tcl arrays to group related information:
         ad_proc ... {     
            array set creation_info {
                       creation_status {}
                       creation_message {}
                       element_messages {}
                       account_status {}
                       account_message {}              
            } 
            .....     
            return [array get creation_info] 
         } 
    • ... or even better: use Tcl dicts
         ad_proc proc ... {} {
      	  set creation_info [dict create  \
      	               creation_status {}   \
      	               creation_message {}  \
      	               element_messages {}  \
      	               account_status {}    \
      	               account_message {}   ]
      	  ....     
            return $creation_info 
        }
      
      
    • Read the Tcl Style guide

      This is the Tcl styleguide (PDF), try to apply relevant guidelines. In particular chapter 4,5 and 7

    Next Page
    previous October 2019
    Sun Mon Tue Wed Thu Fri Sat
    29 30 1 2 3 4 5
    (2) 6 7 8 9 10 11 (1) 12
    13 14 15 16 17 18 19
    20 21 22 23 24 25 26
    27 28 29 30 31 1 2

    Popular tags

    17 , 5.9.0 , 5.9.1 , ad_form , ADP , ajax , aolserver , asynchronous , bgdelivery , bootstrap , bugtracker , CentOS , COMET , compatibility , CSP , CSRF , cvs , debian , emacs , engineering-standards , fedora , FreeBSD , guidelines , host-node-map , hstore , includelets , install , installation , installers , install-ns
    No registered users in community xowiki
    in last 30 minutes
    Contributors

    OpenACS.org