digger-blueprints

Client side blueprint handler for digger

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.