digger-blueprints

Client side blueprint handler for digger

This is merged into $digger as the 'blueprints' property.

Blueprint Format

The blueprint format in digger is a very simple XML structure.

The elements are:

• blueprint - the top level 'thing'
• field - each blueprint has a list of fields
• option - the list of options for select and radio fields
• tab - each blueprint can have a list of tabs - each tab can have a list of fields

An example of the most basic blueprint with 1 field - 'name':

<blueprint name="mything">
    <field name="name" />
</blueprint>

Blueprint Attributes

The top level blueprint element can have the following properties:

name

The name is how the blueprint will be referenced and can be any string. If there is no tag attribute then the name is used as the tag.

tag

The tag will be assigned to the container created from the blueprint.

Here is a blueprint known as 'My Big Blueprint Title' but that will create a 'thing' container.

<blueprint name="My Big Blueprint Title" tag="thing" />

Here is a blueprint that uses the name for the tag:

<blueprint name="thing" />

This is invalid (because there is no tag - the name cannot have spaces):

<blueprint name="The name cannot have spaces without a tag" />

class

The class attribute of the blueprint will be assigned to the new container:

<blueprint name="Citrus Fruit" tag="fruit" class="citrus">
    <field name="name" />
</blueprint>

leaf

The leaf attribute of the blueprint means that no children can be added to the container:

<blueprint name="stat" leaf="true">
    <field name="value" />
</blueprint>

children

The children attribute controls what other blueprints can be added to this one.

The names are split by comma and only those blueprints are allowed as children.

<blueprint name="statgroup" children="stat">
    <field name="name" />
</blueprint>

Fields

Each blueprint has an array of fields that control what will appear on the form.

Each field has 2 core properties:

• name - what property of the model the field will edit
• type - what type will be rendered

For example - if we wanted to edit the 'comments' property of a container and have a 'textarea' appear for it:

<field name="comments" type="textarea" />

You can nest fieldnames with dots.

<field name="address.street" />
<field name="address.city" />
<field name="address.postcode" />

This example would create an 'address' object with 3 properties inside. The default type is 'text'.

Labels

You can have a different label from the fieldname:

<field name="ahqr" title="App Hours Queue Rate" />

Field Types

There are a number of built-in fieldtypes:

• text
• url
• number
• money
• email
• textarea
• diggerclass
• diggericon
• template
• checkbox
• radio
• select
• diggerurl
• file

Here is an example blueprint with 3 fields of different types:

<blueprint name="mything">
    <field name="name" />
    <field name="price" type="money" />
    <field name="description" type="textarea" />
</blueprint>

Lists

A field can be a list of values - to turn a field into a list add list="true" to the XML:

<blueprint name="mything">
    <field name="name" />
    <field name="notes" type="text" list="true" />
</blueprint>

Tabs

Tabs group other fields or can display a single field.

To have a tab with some fields:

<blueprint name="mything">
    <field name="name" />
    <tab name="address">
        <field name="address.street" />
        <field name="address.city" />
        <field name="address.postcode" />
    </tab>
</blueprint>

To have a tab that is a single field:

<blueprint name="mything">
    <field name="name" />
    <tab name="notes" type="textarea" />
</blueprint>

To have a tab that is a single list:

<blueprint name="mything">
    <field name="name" />
    <tab name="notes" type="text" list="true" />
</blueprint>

Options

The radio and select types need an array of options to fill.

The simplest way is to add them to the field.

You can do this either with a csv string:

<blueprint name="mything">
    <field name="name" />
    <field name="food" type="select" options_csv="cake,fruit,pasta" />
</blueprint>

Or with nested option elements:

<blueprint name="mything">
    <field name="name" />
    <field name="food" type="select">
        <option value="cake" />
        <option value="fruit" />
        <option value="pasta" />
    </field>
</blueprint>

Another way to fill options is to load them from a digger query.

Here is an example of populating a select list with the countries from a warehouse:

<blueprint name="mything">
    <field name="name" />
    <field name="country" type="select" options_warehouse="binocarlos/countries" options_selector="country:sort(name)" />
</blueprint>

Templates

For single page applications you can also include custom field types in the form of a template.

Digger fields use angular and so templates are in angular markup - the model and fieldname properties of the scope are used to write to the container.

Here is a custom radio button as an example template:

<script type="digger/field" name="customradio">
    <div>
        <button class="btn" ng-class="{'btn-primary':!model[fieldname]">No</button>
        <button class="btn" ng-class="{'btn-primary':model[fieldname]">Yes</button>
    </div>
</script> 

And here is a blueprint that uses that template:

<blueprint name="mything">
    <field name="name" />
    <field name="active" type="customradio" />
</blueprint>

Components

Digger components enable you to a GitHub repository as a field type.

Here is an example of using the ace-editor as a field type:

<blueprint name="webpage">
    <field name="name" />
    <field name="html" type="binocarlos/ace-editor" />
</blueprint>

Digger will download the component - build it and inject it into the field.