The EditorTab

  Meta::

     Valid for:  Silva 0.9.3, Zope 2.6.2, Python 2.1.3
     Authors:    kit blake
                 Clemens Klein-Robbenhaar 
     Email:      kitblake+infrae.com
                 robbenhaar+espresto.com
     CVS:        $Revision: 1.2 $ $Date: 2003/11/12 18:20:09 $

Editing a document 

  When you move from the ContentsTab of a container to the EditorTab
  of a content object, the color of the tabs changes from a green to a
  blue shade.

  Adding document elements 

    After a document is created or opened for editing, a screen appears
    with the title and two arrow symbols on the left side. The dark arrow
    is an "edit element" link, and the open arrow is an
    "insert element" link. Clicking the insert symbol brings
    up an "add element" box, in which you can choose what you
    wish to insert. After selecting and clicking the |_insert_| button
    (alt-i), a focus box appears in which text can be entered and saved.

    Text elements

      Documents are structured by text elements. Since text is stored in
      XML - which also has a tree structure - this dendritic
      pattern is carried though to the smallest nodes of a Silva site. 
      Documents can contain the following elements:

      - **title**: created when a document is created. Titles cannot
          be added or removed, only edited.

      - **paragraph**: standard text in paragraph form. Multiple kinds
          of paragraph are available.

      - **heading**: five kinds of heading are available.

      - **list**: ordered or unordered, with various varieties.

      - **definition list**: for terms and definitions.

      - **preformatted**: usually used for displaying code or things
          to type at a command line.

      - **image**: gif, jpg, and png formats shown inside the page. An
          image refers to an image asset which contains the real image
          information.

      - **table**: cells can contain most document elements.

      - **complex list**: for nesting elements within list items, such
          as multi-level lists.

    Dynamic document elements

      - **table of contents (TOC)**: in a TOC the titles of documents
        in the current and underlying folders are displayed as links.

      - **external source**: retrieve structure or functionality from
        an external source, typically created by a site developer in
        the Zope Management Interface. This can be custom code written
        by a site developer (Code Source), or data retrieved from an
        SQL database (SQL source). Other types of sources could also
        be created.

  Deleting and moving elements 

    On the right side of the screen are delete and move symbols. Clicking
    the 'X' deletes the element (there will be "Really
    delete?" alert). With the "move down" and
    "move up" arrows elements will be shifted one step.

  Editing text and image elements

    **Paragraph** -- 
      A paragraph is a block of text. You can simply type in the text,
      or when the text is already available you can cut and paste
      (multiple) blocks of text from other programs. Silva interprets
      an empty line as a signal to make a new paragraph. This means
      you can add multiple paragraphs in one step.

    **Heading** -- 
      There are five types of headings; each one in the list is
      rendered successively smaller than the previous. A heading can
      always be changed to a paragraph (and back).

    **List** --   
      The standard list types (bullet, numbered, etc.) can be created by
      changing the "Type" setting.

    **Definition list** -- 
      The text you are reading right now is part of a definition
      list. A definition term appears on a line by itself, followed by
      the term's definition.

    **Preformatted** -- 
      Text in this element will be presented exactly as entered. Tags
      (such as HTML, XML, TAL, etc.) are not rendered and white space
      is preserved. In the rendered HTML a <pre> tag is used to
      format the text. This is useful to show code examples or command
      line statements.

    **Image** --   
      Placing a new image happens in two steps. In the first step the
      image must be uploaded in a container (local or elsewhere),
      where it appears in the "Assets" area of the
      listing. After the upload return to the document you were
      editing. Step two involves placing a reference to the local
      image in the document. Select the image in the focus box, and
      click |_save_and_exit_| (or alt-e).

  Formatting elements

    **Table** --   
      After choosing "table" as element and clicking the
      |_insert_| button, a Table focus box appears. Columns can be added
      and deleted and their alignment set with the controls at the top,
      but this is easier if there are already rows inserted. Click the
      "insert" symbol, and Silva will present a pull-down
      menu with options for two kinds of table rows.

      - Row: a normal row

      - Row heading: a row with headers, in which the text will be bold

      With the controls at the bottom of the Table focus box the style of
      the table can be set. The types are described in the select menu. 

      It's also possible to nest elements in table cells. Clicking the
      "Nest element" symbol brings you to a nested element
      editor. This works the same way as the normal editor, but has
      less elements available (e.g. it is not possible to insert a
      TOC).  After adding elements you can return to the document by
      clicking the "Edit parent" symbol at the top. Note
      that before clicking the "Nest element" symbol you
      should Save if you entered text in the focus box.

    **Complex list** -- 
    
      Similar to a normal list, text can be entered in list items, but
      also other elements can nested, e.g. another list. Click the
      "Insert item" symbol to add a list item. If the list
      item is just text, enter it in the focus box. Clicking the
      "Nest item" symbol brings you to a Nested element
      editor, which works the same way as the nested element editor of
      tables (see above).

  Dynamic elements

    **Table of Contents (TOC)** --   
    A TOC displays the titles of all documents in the current and
    underlying folders as links. Titles on lower levels are indented.
    Since the TOC is dynamic, new documents appear automatically. The
    depth of the TOC can be configured in the controls row at the bottom
    of the focus box.

    **External Source** --

    Site managers or developers can create external source objects in
    the Zope Management Interface. These can be used to add new types
    of structure or functionality to the document editor. All an
    Author needs to do is select an available external source and fill
    in any parameters required to configure the external source.

    External sources can be SQL sources, which an be used to retrieve
    tabular data from relational databases using SQL, or code sources,
    which can be written in the full toolset that Zope makes available
    to developers. Other types of sources could also be created.

  Inline styling of text

    Several inline styles such as bold, italic, underlined, superscript
    and subscript are available. Text must be 'marked up'
    with special characters.

    - **this will be bold**

    - ++this will be italic++

    - __this will be underlined__

    - ^^this will be superscript^^

    - ~~this will be subscript~~

    If you really need to enter combinations like two plusses or two
    stars used for styling, the \ character can be used to indicate this:

      \**
   
    will show up literally as:

      *&42;

  Making hyperlinks

    Links can be added to the text as well. The simplest way is to use
    the |_get link reference_| button. This will allow you to select the
    object you want to link to in a popup window and automatically inserts
    the right markup in the editor.

    Links can also be entered manually, which is especially useful 
    if you want special behavior or want to link to an external site.

    A link has the following structure::

      ((link text|http://www.x.yz))

    This creates a link with the appropriate text and hyperlink.

    It is also possible to create links to a target in the other page::

      ((link text|http://www.x.yz|target name))

    Leaving the target section is left empty, like this::

      ((link text|http://www.x.yz|))

    is a way to indicate that you want a new window to be opened when
    the user clicks a link.

  Creating index items

    Index items will be picked up by the Indexer object and the
    information can also be used by Docma to create indexes in Word.
    An index will also be turned into an anchor in the HTML that is
    generated for a Document. Index items won't actually show up in
    the public document otherwise. You can see them in the editor
    however, as they will be highlighted in yellow.

    The only text an index item needs is the text under which it
    should appear under the generated index as well as the name of the
    HTML anchor.

    Index items are created like this::

        [[item as shown in index]]

  The difference between style and structure of text

    A fundamental characteristic of Silva is the separation between
    content, presentation, and logic. For an Author, it's important to
    realize that content and presentation are kept independent so that
    the same data can be used in multiple contexts and mediums. Silva
    achieves this by storing the data in XML, a 'clean'
    format which is easy to import into other applications.

    The style of a document is determined by the design of element
    characteristics, such as fonts, letter sizes, and alignment of
    paragraphs, headers, and lists. The structure of a document is
    determined by the usage of these text elements. Well structured
    documents can be used in different contexts, in which a stylesheet
    overlays the proper style for that medium.

    This difference is critical. Local styling of text elements is a bad
    idea. For instance, one Author created an extra heading, a sort of
    italic subhead, which was actually a short paragraph made italic.
    Later he complained because his headings were not showing up in an
    export. He was styling, not structuring the text.

    Also standard page characteristics, such as navigation bars, section
    titles, and audience information are kept separate from the data. An
    Author need only be concerned with the content of documents, deciding
    what text and illustrations should be presented and how they should
    be structured. Surrounding elements are automatically included.

    Silva uses acquisition (inheriting characteristics from higher
    levels) to determine which page elements will be wrapped around the
    content. As with most websites, this occurs via a tree structure,
    where a stylesheet in a container affects documents on that level and
    all underlying containers.

<br /> Copyright &copy; 2002, 2003 Infrae. All rights reserved.<br /> See
also "LICENSE.txt":license.txt
