How to work with code elements

  Author: Benno Luthiger (benno.luthiger+id.ethz.ch), 5.2.2003

  (Silva Version 0.9)

  Purpose of code elements

    A basic Silva installation limits an Author's possibility to add
    elements/structure to a document, essentially to a list of 9 elements
    (*Paragraph*, *Heading*, *List*, *Preformatted*, *Complex list*,
    *Table*,  *Image*, *Table of contents*, *Definition list*). However,
    code elements provide a Silva Site Manager a flexible way to extend
    this list. The use of code elements makes it possible to add structure
    or functionality to a document not anticipated by the Silva creators.

  Some examples where code elements can be used

    You can use code elements:

    - If you want to display a document which includes some simple
      navigation elements,  e.g. "go to top" links.

    - If you want to display sitemaps or other extended *table of contents*
      -like lists. Generally speaking, you can use code elements to create
      lists that display various information of and about the documents
      included in the list and if you want sorted them by various criteria.

    - If you want to display forms within a Silva document, e.g. to
      create wizards.

  How to create code elements (for Silva Site Managers)

    Before code elements can be added to a document in Silva, a Site
    Manager has to create some code objects. Code objects are scripts, Zope
    page templates or DTML methods residing in folders named 'code_source'.
    These objects have to contain the code to display the desired new
    functionality.

    The title given to these code objects will be displayed in the list of
    available code objects, therefore, it's a good idea to choose a
    descriptive title which tells the Silva Authors what the element will
    do.

    Code objects are accessible not only for documents residing in the same
    Silva Folder or Silva Publication the 'code_source' folder is in, but
    for all underlying Silva Folders and Publications too. However, a Site
    Manager can mark code objects to be hidden for subsequent levels of the
    document hierarchy so that they're only available for documents
    found on the same level as the 'code_source' folder. A code object is
    hidden if it is member of a list returned by a script named 'hidden'.
    Therefore, to hide a code object, create a Python script named *hidden*
    in the 'code_source' folder and let it return a list of string objects.
    Add the *id* of the code object you want to hide to this list. This
    functionality allows the site developer to  selectively hide some code
    objects from being called by lower level documents.

  How to use code elements (for Silva Authors)

    After the Site Manager has created Silva code objects, code elements
    can be added to a Silva document as simply as paragraphs or other
    elements. In the edit view of a Silva document, click on the 'insert
    element' icon and choose 'Code element' from the list of addable
    elements. After clicking the 'Insert' button the list of available code
    objects is displayed. Choose the element you're interested in and save
    it by clicking the |_Save_| button.

