From c18389172ff8366ffd116161e2ebdc924123c1a1 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sat, 2 Jan 2016 22:09:37 +0100 Subject: [PATCH] Updated docs on types --- content/docs/api/db/type/contents.lr | 43 +++++++++++++++ content/docs/api/db/type/to-json/contents.lr | 18 +++++++ .../api/db/type/value-from-raw/contents.lr | 52 +++++++++++++++++++ content/docs/api/db/type/widget/contents.lr | 47 +++++++++++++++++ content/docs/api/db/types/contents.lr | 2 +- templates/macros/docs.html | 4 +- 6 files changed, 163 insertions(+), 3 deletions(-) create mode 100644 content/docs/api/db/type/contents.lr create mode 100644 content/docs/api/db/type/to-json/contents.lr create mode 100644 content/docs/api/db/type/value-from-raw/contents.lr create mode 100644 content/docs/api/db/type/widget/contents.lr diff --git a/content/docs/api/db/type/contents.lr b/content/docs/api/db/type/contents.lr new file mode 100644 index 00000000..6d91f44c --- /dev/null +++ b/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/). diff --git a/content/docs/api/db/type/to-json/contents.lr b/content/docs/api/db/type/to-json/contents.lr new file mode 100644 index 00000000..3f800966 --- /dev/null +++ b/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. diff --git a/content/docs/api/db/type/value-from-raw/contents.lr b/content/docs/api/db/type/value-from-raw/contents.lr new file mode 100644 index 00000000..d6359d7a --- /dev/null +++ b/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. diff --git a/content/docs/api/db/type/widget/contents.lr b/content/docs/api/db/type/widget/contents.lr new file mode 100644 index 00000000..1a23feb9 --- /dev/null +++ b/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. diff --git a/content/docs/api/db/types/contents.lr b/content/docs/api/db/types/contents.lr index 6753c552..f6c96999 100644 --- a/content/docs/api/db/types/contents.lr +++ b/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. --- diff --git a/templates/macros/docs.html b/templates/macros/docs.html index 11395064..3b1b6fb9 100644 --- a/templates/macros/docs.html +++ b/templates/macros/docs.html @@ -28,8 +28,8 @@

{% if page.type %}{{ get_doc_icon(page) }} {% endif %}{% if page.module %}{{ page.module }}.{% endif %}{{ page.title }}{% - 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 %} ({{ page.signature }}){% endif %}

{% else %}

{{ page.title }}