Changeset 12998

Timestamp:

24 May 2015, 08:23:56 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs.

Location:

main/waeup.kofa/trunk

Files:

• docs/source/userdocs/datacenter/import_stages.rst (modified) (1 diff)
• docs/source/userdocs/students.rst (modified) (3 diffs)
• src/waeup/kofa/browser/templates/source.pt (modified) (1 diff)

main/waeup.kofa/trunk/docs/source/userdocs/datacenter/import_stages.rst

@@ -29 +29 @@
 
 Many importer fields are of type 'Choice', which means only definied
-keywords are allowed. An overview of all sources and
-vocabularies, which feed the choices, can be also accessed from the
-datacenter upload page and shows up in a modal window.
-Sources and vocabularies of the base package can be viewed
-`here <http://kofa-demo.waeup.org/sources>`_.
+keywords (tokens) are allowed, see :ref:`schema fields <kofa_schemas>`.
+An overview of all sources and vocabularies, which feed the
+choices, can be also accessed from the datacenter upload page and
+shows up in a modal window. Sources and vocabularies of the base
+package can be viewed `here <http://kofa-demo.waeup.org/sources>`_.
 
 Data center managers can upload any kind of CSV file from their

main/waeup.kofa/trunk/docs/source/userdocs/students.rst

@@ -41 +41 @@
 Let's talk about the attributes and methods belonging to the `Student` class, the so-called 'external behaviour' of student objects specified in Zope 'interfaces'. The data stored with each student object are subdivided into three parts: base data, personal data and clearance data. Each part has its own interface.
 
+.. _kofa_interfaces:
+
 .. note::
 
-  **Interfaces** are one of the pillars of Zope's Component Architecture (ZCA, see also :ref:`prerequisites`). They document the 'external behaviour' of objects. In Kofa interfaces are used to specify the attributes, methods and schema fields of objects. The first two are well-known Python concepts. A Zope schema field is a bit more complicated. It's a detailed description of a field to be submitted via forms to the server, or which is processed by a batch processor. In both cases the input data are being validated against the schema. In Kofa, schema fields in interfaces are also used to automtically add `FieldProperty` attributes of the same name to most content classes. This is done by a class function called :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>` during startup. These class attributes ensure that corresponding attributes of instances of this class - when being added or changed - always meet the requirements of the schema. Another big advantage of such class attributes is, that attributes with a `FieldProperty` do not need to be set in `__init__` methods.
+  **Interfaces** are one of the pillars of Zope's Component Architecture (ZCA, see also :ref:`prerequisites`). They document the 'external behaviour' of objects. In Kofa interfaces are used to specify the attributes, methods and schema fields of objects. The first two are well-known Python concepts. A Zope schema field is a bit more complicated. It's a detailed description of a field to be submitted via forms to the server, or which is processed by a batch processor. In both cases the input data are being validated against the schema field. In Kofa, schema fields in interfaces are also used to automtically add `FieldProperty` attributes of the same name to most content classes. This is done by a class function called :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>` during startup. These class attributes ensure that corresponding attributes of instances of this class - when being added or changed - always meet the requirements of the schema field. Another big advantage of such class attributes is, that attributes with a `FieldProperty` do not need to be set in `__init__` methods.
 
 All student classes implement `waeup.kofa.students.interfaces.IStudent` which defines a base set of attributes, schema fields and methods all students must provide. This 'behaviour' is fundamental so that we quote and explain the source code here.
@@ -50 +52 @@
    :pyobject: IStudentBase
 
-The first part of the interface lists attributes. Except for the first two (`password` and `temp_password`) they are all read-only property attributes, i.e. attributes with a getter method only. These properties are computed dynamically and can't be set. Most of them return data derived from the ``studycourse`` subobject.
+The **first part** of the interface lists attributes. Except for the first two (`password` and `temp_password`) they are all read-only property attributes, i.e. attributes with a getter method only. These properties are computed dynamically and can't be set. Most of them return data derived from the ``studycourse`` subobject.
 
-The second part of the interface specifies the schema fields, which are instances of schema classes with their `title`, `description`, `default`, `required`, `readonly` and `source` attributes.
+The **second part** of the interface specifies the schema fields
+
+.. _kofa_schemas:
+
+.. note::
+
+  **Schema fields** are instances of schema field classes with `title`, `description`, `default`, `required`, `readonly` attributes. Class names and class attributes are self-explanatory and described in the `Zope Schema`_ documentation.
+
+  A very powerful Zope Schema field is `Choice`. Choice fields 'are constrained to values drawn from a specified set, which can be static or dynamic'. This set can be a simple list of choices (= `values`), or a `vocabulary` or `source` which produce dynamic choices.
+
+  **Vocabularies and sources** are very similar. The latter is a newer concept of producing choices and considered to replace vocabularies. In Kofa we are using both. Common to both is that a set of values is accompanied by a user-friendly title, which is displayed on pages (e.g. in select boxes) instead of a less informative value token or even a cryptic representation of a persistent value object. In most cases we have a token-title pair which perfectly describes the values of a source or a vocabulary. The tokens are being sent in forms or imported by batch processors.
+
+  **Token-title pairs** of most (non-database-dependent) sources and vocabularies of the Kofa base package can be viewed `here <http://kofa-demo.waeup.org/sources>`_.
+
+The **third part** of the interface lists the methods which can be applied to student objects.
 
 
@@ -66 +82 @@
 Student Accommodation
 =====================
+
+
+.. _zope schema: http://docs.zope.org/zope.schema

main/waeup.kofa/trunk/src/waeup/kofa/browser/templates/source.pt

@@ -21 +21 @@
         <thead>
           <tr>
-            <th i18n:translate="">Key</th>
+            <th i18n:translate="">Value</th>
             <th i18n:translate="">Title</th>
           </tr>