Updated docs on types

content/docs/api/db/type/contents.lr

@@ -0,0 +1,43 @@
+title: Type
+---
+module: lektor.types
+---
+signature: env, options
+---
+summary: The base class for all field types.
+---
+type: class
+---
+version_added: 2.0
+---
+body:
+
+The fields in [Records :ref](../record/) use types to specify the behavior of
+the values.  Lektor comes with a wide range of [built-in field types
+:ref](../types/) but it is possible to build your own by subclassing types
+class.  A type is instanciated with two parameters: a reference to the
+[Environment :ref](../../environment/) that it belongs to and a dictionary
+with configuration options from the ini file.
+
+A field type has to implement the [value_from_raw :ref](value-from-raw/)
+method and set the `widget` property as a very basic requirement.
+
+To create a type you need to create a subclass.  The name of the class needs
+to match the type name.  If you want to name your type `mything` then it
+needs to be called `MyThingType`.  Afterwards you can register it with the
+environment in [setup_env :ref](../../plugins/events/setup-env/):
+
+```python
+from lektor.types import Type
+
+class MyThingType(Type):
+    widget = 'singleline-text'
+
+    def value_from_raw(self, raw):
+        return raw.value
+
+def setup_env(self, **extra):
+    self.env.types['mything'] = MyThingType
+```
+
+For more information see [value_from_raw :ref](value-from-raw/).

content/docs/api/db/type/to-json/contents.lr

@@ -0,0 +1,18 @@
+title: to_json
+---
+signature: pad, record=None, alt='_primary'
+---
+summary: Returns the type information as JSON.
+---
+template_var: 
+---
+type: method
+---
+version_added: 2.0
+---
+body:
+
+This method is used to export a type definition to JSON.  Primarily this is
+used to drive some more special widgets for the admin UI.  For the moment this
+is largely undocumented as widgets are not yet customizable.  For more
+information you will need to read the Lektor docs.

content/docs/api/db/type/value-from-raw/contents.lr

@@ -0,0 +1,52 @@
+title: value_from_raw
+---
+signature: raw
+---
+summary: Main method to override to implement the value conversion.
+---
+type: method
+---
+version_added: 2.0
+---
+body:
+
+This method needs to be implemented to perform the type conversion from the
+raw value from the content file into a value that Lektor can process in the
+database layer.  This can be any Python type for as long as it makes sense.
+It must either return a valid value or a special value that indicates a bad
+value.  For more information see the raw value information below and the
+example provided.
+
+## Example
+
+```python
+from lektor.types import Type
+
+class LocationType(Type):
+    widget = 'singleline-text'
+
+    def value_from_raw(self, raw):
+        if raw.value is None:
+            return raw.missing_value('Location was not supplied')
+        try:
+            lng, lat = [float(x.strip()) for x in
+                        raw.value.split(';')]
+        except (TypeError, ValueError):
+            return raw.bad_value('Location was malformed')
+        return (lng, lat)
+
+def setup_env(self, **extra):
+    self.env.types['location'] = LocationType
+```
+
+## Raw Value
+
+The value passed is a `raw` value type.  It has a few properties and methods:
+
+| Attribute            | Description
+| -------------------- | --------------------
+| `name`               | The name of the field
+| `value`              | The raw value as unicode string or `None` if missing
+| `pad`                | A reference to the [pad :ref](../../pad/)
+| `bad_value(rsn)`     | Creates a value that indicates a bad value with a reason.
+| `missing_value(rsn)` | Similar to `bad_value `but indicates an absent value.

content/docs/api/db/type/widget/contents.lr

@@ -0,0 +1,47 @@
+title: widget
+---
+summary: An attribute that identifies the widget to use in the admin panel.
+---
+type: property
+---
+version_added: 2.0
+---
+body:
+
+It's currently not yet possible to create your own widgets for the admin panel
+but you can select one of the built-in widgets for your own type.  Note that
+not all widgets will necessarily will work directly with your type as such.
+For instance the `select` widget and some others will currently require some
+extra values be supplied in the [to_json :ref](../to-json/) method.
+
+## Example
+
+```python
+from lektor.types import Type
+
+class MyThingType(Type):
+    widget = 'singleline-text'
+
+    def value_from_raw(self, raw):
+        return raw.value
+```
+
+## Available Widgets
+
+These widgets are currently available:
+
+* `singleline-text`: single-line text input field
+* `multiline-text`: multi-line text input field
+* `datepicker`: a date input field (currently not yet an actual date picker)
+* `integer`: an integer input field
+* `float`: a floating point value input field
+* `checkbox`: a checkbox
+* `url`: a URL input field
+* `slug`: input field for URL slugs
+* `checkboxes`: an input field with multiple checkboxes *
+* `select`: an input field in the form of a select box *
+
+\* `checkboxes` and `select` require a `choices` list to be supplied which is
+a list of `[value, label]` tuples where value is the stored value and label
+is a dictionary of internationalized values for the UI.  For more information
+you will currently have to refer to the Lektor sourcecode.

content/docs/api/db/types/contents.lr

@@ -1,4 +1,4 @@
-title: Field Types
+title: Builtin Field Types
 ---
 summary: An overview of all the field types supported in Lektor.
 ---

templates/macros/docs.html

@@ -28,8 +28,8 @@
     <h1>{% if page.type %}{{ get_doc_icon(page) }} {% endif %}{%
       if page.module %}<code class="mod">{{ page.module }}.</code>{% endif
       %}<code class="obj">{{ page.title }}</code>{%
-      if page.type == 'method' or page.type == 'function' or page.type == 'filter'
-        or page.type == 'event'
+      if (page.type == 'method' or page.type == 'function' or page.type == 'filter'
+        or page.type == 'event') or page.signature
       %} <span class="sig">(<code>{{ page.signature }}</code>)</span>{% endif %}</h1>
   {% else %}
     <h1>{{ page.title }}</h1>