From: richard Date: Mon, 1 Oct 2001 04:58:33 +0000 (+0000) Subject: more doc X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=949b2e7ac272dcf17a1b3a4c4c82d4023b5fceb6;p=roundup.git more doc git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@265 57a73879-2fb5-44c3-a270-3262357dd7e2 --- diff --git a/doc/index.html b/doc/index.html index 7e6cdf7..46dd8c0 100644 --- a/doc/index.html +++ b/doc/index.html @@ -625,79 +625,141 @@ in the instance html directory. These are divided into index, item and newitem views. The newitem view is optional - the item view will be used if the newitem view doesn't exist. -

-Next bit cut straight from the implementation guide +

Displaying Properties

-

8.2. Displaying Properties

- -

Properties appear in the user interface in three contexts: +Properties appear in the user interface in three contexts: in indices, in editors, and as filters. For each type of property, there are several display possibilities. For example, in an index view, a string property may just be printed as a plain string, but in an editor view, that property should be displayed in an editable field. -

The display of a property is handled by functions in -a displayers module. Each function accepts at -least three standard arguments -- the database, class name, -and node id -- and returns a chunk of HTML. +

+The display of a property is handled by functions in +the htmltemplate module. -

Displayer functions are triggered by <display> +

+Displayer functions are triggered by <display> tags in templates. The call attribute of the tag provides a Python expression for calling the displayer function. The three standard arguments are inserted in front of the arguments given. For example, the occurrence of 

    <display call="plain('status', max=30)">
+>    <display call="plain('status')">
-in a template triggers a call to - -
    plain(db, "issue", 13, "status", max=30)
-
- -when displaying item 13 in the "issue" class. The displayer +in a template triggers a call the "plain" function. The displayer functions can accept extra arguments to further specify details about the widgets that should be generated. By defining new displayer functions, the user interface can be highly customized. -

Some of the standard displayer functions include: +

+ + - + -
  • field: display a property like the -plain displayer above, but in a text field -to be edited +
    • + -
  • menu: for a Link property, display -a menu of the available choices +
    • + + + + -
  • link: for a Link or Multilink property, -display the names of the linked nodes, hyperlinked to the -item views on those nodes +
    • + -
  • reldate: display a Date property in terms +
    • + -
  • download: show a Link("file") or Multilink("file") -property using links that allow you to download files +
    • + -
  • checklist: for a Link or Multilink property, -display checkboxes for the available choices to permit filtering - +
    • + -

    8.3. Index Views

    + + + + + + + + + + + + +
    The displayer functions are
    plainDisplay a String property directly. +

    +Display a Date property in a specified time zone with an option +to omit the time from the date stamp. +

    +For a Link or Multilink property, display the key strings of the linked nodes (or the -ids if the linked class has no key property) +ids if the linked class has no key property). +

    +Options:
    +escape (boolean) - HTML-escape the resulting text. +

    fieldDisplay a property like the +plain displayer above, but in a form field +to be edited. Strings, Dates and Intervals use TEXT fields, Links use +SELECT fields and Multilinks use SELECT MULTIPLE fields. +

    +Options:
    +size (number) - width of TEXT fields.
    +height (number) - number of nows in SELECT MULTIPLE tags.
    +showid (boolean) - true includes the id of linked items in the SELECT +MULTIPLE fields. +

    menuFor a Links and Multilinks, display the same field as would be +generated using field. +
    linkFor a Link or Multilink property, display the names of the linked +nodes, hyperlinked to the item views on those nodes. For other properties, +link to this node with the property as the text. +

    +Options:
    +property (property name) - the property to use in the second case. +

    countFor a Multilink property, display +a count of the number of links in the list. +

    +Arguments:
    +property (property name) - the property to use. -

  • count: for a Multilink property, display -a count of the number of links in the list +
    • reldateDisplay a Date property in terms of an interval relative to the current date (e.g. "+ 3w", "- 2d"). +

    +Arguments:
    +property (property name) - the property to use. +

    +Options:
    +pretty (boolean) - display the relative date in an English form. +

    downloadShow a Link("file") or Multilink("file") +property using links that allow you to download files. +

    +Arguments:
    +property (property name) - the property to use. +

    checklistFor a Link or Multilink property, +display checkboxes for the available choices to permit filtering. +

    +Arguments:
    +property (property name) - the property to use. +

    noteDisplay the special notes field, which is a text area for entering a +note to go along with a change. +
    listList the items specified by property using the standard index for +the class. +

    +Arguments:
    +property (property name) - the property to use. +

    historyList the history of the item. +
    submitAdd a submit button for the item. +
    + +

    Index Views

    An index view contains two sections: a filter section and an index section. @@ -705,9 +767,9 @@ The filter section provides some widgets for selecting which items appear in the index. The index section is a table of items. -

    8.3.1. Index View Specifiers

    +

    Index View Specifiers

    -

    An index view specifier looks like this (whitespace +

    An index view specifier (URL fragment) looks like this (whitespace has been added for clarity): 

    8.3.2. Filter Section
+
    Filter Section
    
 
 
    The template for a filter section provides the
 filtering widgets at the top of the index view.
@@ -780,7 +842,12 @@ view specifier requests a filter for a particular property.
     <display call="menu('fixer')">
 </property>
    -

    8.3.3. Index Section

    +

    +The standard index generation code appends a section to the index pages +which allows selection of the filters - from those which are defined in the +filter template. + +

    Index Section

    The template for an index section describes one row of the index table. @@ -805,7 +872,7 @@ to display the values of the item's properties. </property> </tr> -

    8.3.4. Sorting

    +

    Sorting

    String and Date values are sorted in the natural way. Link properties are sorted according to the value of the @@ -814,21 +881,15 @@ otherwise on the key string of the linked nodes; or finally on the node ids. Multilink properties are sorted according to how many links are present. -

    8.4. Item Views

    +

    Item Views

    An item view contains an editor section and a spool section. At the top of an item view, links to superseding and superseded items are always displayed. -

    8.4.1. Item View Specifiers

    - -

    An item view specifier is simply the item's designator: -

    /patch23
-
    -

    8.4.2. Editor Section

    +

    Editor Section

    The editor section is generated from a template containing <display> tags to insert @@ -873,30 +934,51 @@ text area for entering a note to go along with a change.

    When a change is submitted, the system automatically generates a message describing the changed properties. -The message displays all of the property values on the + +

    If a note is given in the "note" field, the note is +appended to the description. The message is then added +to the item's message spool (thus triggering the standard +detector to react by sending out this message to the nosy list). + +

    +The message also displays all of the property values on the item and indicates which ones have changed. An example of such a message might be this: -

    title: Polly Parrot is dead
+
    +Polly's taken a turn for the worse - this is now really important!
+-----
+title: Polly Parrot is dead
 priority: critical
 status: unread -> in-progress
-fixer: (none)
+fixer: terry
 keywords: parrot,plumage,perch,nailed,dead
-
    
-
-
    If a note is given in the "note" field, the note is
-appended to the description.  The message is then added
-to the item's message spool (thus triggering the standard
-detector to react by sending out this message to the nosy list).
+
    -

    8.4.3. Spool Section

    +

    Spool Section

    The spool section lists messages in the item's "messages" property. The index of messages displays the "date", "author", and "summary" properties on the message nodes, and selecting a message takes you to its content. +

    The <property> tag used in the index may also be used here - +it checks to see if the nominated Multilink property has any entries. +This can be used to eliminate sections of the spool section if the +property has no entries. + +

    +<property name="files">
+ <tr class="strong-header">
+  <td><b>Files</b></td>
+ </tr>
+
+ <tr>            
+  <td><display call="list('files')"></td>
+ </tr>
+</property>
+
    +

    Acknowledgements

    @@ -905,7 +987,7 @@ system on their time.

     

    -$Id: index.html,v 1.5 2001-09-30 01:19:22 richard Exp $ +$Id: index.html,v 1.6 2001-10-01 04:58:33 richard Exp $