stoat / docs / usage.rst

Basic Usage

The first step to using Stoat is defining the templates you want to use for pages.

Defining Templates

You define the templates Stoat will use in your Django settings. Here's a quick example to get you started:

STOAT_TEMPLATES = {
    'Default': ['default.html', [
        ['Heading',       'char'],
        ['Body',          'ckeditor', { 'required': True }],
        ['Sidebar Body',  'text'],
        ['Sidebar Links', 'inline', { 'import': 'sidebar.admin.SidebarLinkInline' }],
    ]],
    'Product': ['pages/product.html', [
        ['Price',       'int', { 'required': True }],
        ['Description', 'text'],
        ['Image',       'img'],
        ['Salesperson', 'fk', { 'app': 'auth', 'model': 'User' }],
    ]],
}
STOAT_DEFAULT_TEMPLATE = 'Default'

The STOAT_TEMPLATES setting contains a dictionary mapping template names to template definitions.

Each template definition consists of:

  • A path
  • A list of fields
  • A dictionary of configuration options (optional)

The path is a normal Django template path, like you might use with render_to_response.

Each field is a list containing a name and a field type. The field name is how the field will be labels in the admin and referred to in your templates, and the field type is one of the supported types detailed in the next section.

The option dictionary maps options to values. Some options (such as required) can be used with any kind of field, while others are specific to a certain field type. See the Field Options section for more information on universal options, and the Field Types section for options specific to a single type.

There's also a STOAT_DEFAULT_TEMPLATE setting that you need to set to the name of the template that should be considered the default.

Field Types

The following types of fields are available for use.

Note: Stoat actually stores all field data as Text data. The field types only change the form field type used (and validated) in the admin.

bool

A basic Django BooleanField.

char

A basic Django CharField.

ckeditor

A CKEditor field. This requires that django-ckeditor be installed.

Options

  • config: A string defining which of the CKEDITOR_CONFIGS should be used for this field.

decimal

A basic Django DecimalField.

email

A basic Django EmailField.

float

A basic Django FloatField.

fk

A foreign key to a model. When using this field you must provide both of its options.

Options

  • app: A string containing the name of the app the model is from.
  • model: A string containing the name of the model.

img

A FileBrowseField from django-filebrowser, with the 'Image' type.

inline

An inline field allows you to create models that have a ForeignKey pointing at Stoat pages.

Check out the :doc:`Inlines </inlines>`_ documentation for more information.

int

A basic Django IntegerField.

text

A basic Django CharField, but rendered as with a <textarea> widget.

url

A basic Django URLField (with verify_exists set to False).

Field Options

The following options can be used for any field.

required

Ensures that this field is not left blank when editing the page in the admin interface.

help_text

Defines help text for individual fields.

Further Usage

Next you'll want to check out the :doc:`Admin </admin>` documentation to learn how to use the admin interface for adding pages (it's simple), and the :doc:`Templating </templating>` documentation to learn how to create Django templates for use with Stoat.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.