Template Author's Guide
Guide for writing content-addressed data types using CO2.Storage
Last updated
Guide for writing content-addressed data types using CO2.Storage
Last updated
Templates are central to the data model of CO2.Storage. By content addressing not only the underlying data but its type, we are able to ensure that code will run on the data we feed it as well as rapidly gather data from different sources. Templates are what allows us to do that.
1) To manually author a template using the CO2.Storage UI, go to the Templates page and log in to the site using your wallet.
2) Make sure that you have selected the correct indexing chain in the upper left hand side of the page. This functions as your workspace, and is the data structure that the service uses to index all of the templates and data added.
You should see a page like this, where I've chosen the "sandbox" indexing chain:
3) If you want to modify an existing template, select it from the list by clicking on its name. If you want to start from scratch, click "Create New Template".
4) This will open up an editor where you can view and modify your template. If you create a new template, the editor should look like this:
At the top we have the Template Metadata, which correspond to the name, base, and description fields in the Type Data Model for the template we will create. Of these fields, only name is required.
At the bottom, we have the Schema Editor which is where we will add a new schema. This corresponds to the cid field of the Type Data Model, and is where the meat of the template is defined.
5) Type or paste in your schema. While you are working, your code will be automatically checked and a preview will appear at the right hand side:
6) If you want your schema to contain fields in no particular order, make it an object and structure it like this:
7) If you want your schema to contain fields in a specific order, make it an array and structure it like this:
8) When you are done, hit "Create". Your template will be created and will be ready to be used.
Transform.storage schemas are similar to JSON or IPLD schemas, but have a more extensive set of primitive types.
All primitive types must appear in double quotes and in lower case within your schema.
int or integer: an integer number
decimal or float: floating point decimal
str or string: string, with input as a single line box
txt or text or textarea: string, with input as a large box
bool or boolean: boolean (true or false) value
date or dates: a date
datetime or datetimes: date with a timestamp
daterange: range with start and end dates
datetimerange: range with start and end timestamps
list or array: choice of one or more predetermined elements. There are additional options reserved for this primitive; see Select from Predefined Elements.
documents: allows user to upload a file
images: allows user to upload an image file
bacalhau-url-dataset: a dataset for Bacalhau downloaded from a URL
bacalhau-custom-docker-job-with-url-inputs: a function for Bacalhau with inputs downloaded from a URL
bacalhau-custom-docker-job-with-cid-inputs: a function for Bacalhau with inputs based on a CID
bacalhau-custom-docker-job-without-inputs: a function for Bacalhau
json: allows the user to input JSON data
cid: a content address retrievable through IPFS
ipld-link: a hash link retrievable through IPLD
template or schema: use the CID of a Transform.Storage schema to create a nested structure. See Nested Schemas below.
template-list or schema-list: create a nested structure with more than one entry for a given subschema. See Nested Schemas below.
Add optional fields to an element in your template schema for additional control.
mandatory: set to true / false based on whether this field is required
value: give your field a default value. If the user does nothing, this will become the field value in the asset.
As an example of these options in use, see this template with the schema:
placeholder: give your field a note which appears in the text field, but is not a default value. If the user does nothing, this will not become the field value.
As an example of a placeholder, see this template with the schema:
Using the primitive type list or array allows you to give the user one or multiple predefined options to choose from. To set these options, add a field called options and give it an array (see example).
By default, the type allows only one option to be selected. To allow multiple options, add the optional field "multiple":true
For an example, look at this template with the schema:
Say you have two cars in your garage, and a set of details you need to know about each car that you have already written a template for. By using a nested schema, you can re-use that template without having to hard code the details for each car.
You can copy the schema address of the car template by finding it in your CO2.Storage template browser and copy the upper CID:
The lower CID is the template.
You can then use the schema CID in a field of a new Template with the type template or schema. As an example, see this garage template with the schema:
What if you want a user to be able to add multiple instances of a subschema, but you're not sure how many? Say there is an inventory of cars being managed and any number would be valid. Then you can use the types template-list or schema-list.
This is shown in this example, with the schema code:
The UI now allows a user to add as many instances as they would like, with the (+) and (-) buttons as shown. Any number of car instances greater than or equal to one will give a valid instance of this template type.
