Data Setup - User Guide

Data setup files are used to define what data is available when generating content. They use the *.rng file extension and follow the ISO-backed RELAX-NG open standard.

Files are accessed using the file tree on the left side of the window, which is discussed further in the Tag user guide. The Scribe Setup screen is shown below after selecting an empty demo folder.

Using the + menu beneath the file tree you can create a new data setup file. A wizard opens to gather a file name and namespace information as follows.

The namespace URI is used to identify the owner of these data definitions. Typically the URI is based on a website address that the user (or their organization) has ownership of.

Namespace URIs are not used to download resources like web URLs used in browsers. They are only used to uniquely identify a set of data definitions. They cost nothing to create, but you should keep them organized (e.g., do not use the same namespace URI more than once).

All Tag users have a default personal namespace URI and have control over all URIs that start with it. For example:

http://id.nsymbol.com/myAccountName/

The create file wizard above uses the default personal namespace URI to suggest a namespace URI unique to the new file (demo-setup.rng). You can change it to use your own website URI.

The namespace URI can always be changed later using the File options / File settings... menu item.

The Use statistics-related datatypes checkbox is only available in the Scribe app. It extends the list of available datatypes to include T-Score, Z-Score, percentile and several other statistical numerical types. If a statistics-related datatype is used for a data field, the form control used to gather that data will have more specific validation rules (e.g., T-Scores must be between 0-120).

After a data setup file is created, the Data tree is displayed by default. The Show fields / Data tree panel contains all data field definitions that can be used in a report. The root data field is called "data" and all other fields must be children or descendants of the root.

New fields are added using the + menu. If a sub-field is added as shown below, that creates a group which displays as a section in the form.

The eye tool displays a form preview as shown next. The section for groupField is displayed with its own border and a plus/minus tool to show/hide section contents. Note that automatic form generation is currently only available in the Scribe app, but will be add to the Automate app in a future release.

The arrow up/down menu allows you to reorder fields. You can move fields up, down, first and last. The save and reload tools work at the file level to save all changes or reload the file from disk (i.e., to discard all changes).

When a field is selected, the Field properties panel to the right provides more detail about the data being stored. You can enter a Label (which will show in forms) or a Comment (which can be viewed here). The Required flag makes a field mandatory in forms. The Use predefined field flag is discussed more below.

The pencil tool next to the Name allows you to rename the field. The new name must be unique within this data setup file or, more precisely, the name must be unique within the namespace URI defined when creating the data setup file. After renaming a field, all references to that field within the current file will also be automatically updated to use the new name.

Note that in Tag, by convention, each data setup file corresponds to exactly one namespace URI. However, that does not always have to be the case. At the end of the day files do not matter, but namespace URIs do. In fact, data setup instructions can be stored in a database or other medium (not a file) and still work in exactly the same way, but they always have to define a valid and unique namespace URI.

The intent with Tag is to keep all this as simple as possible, and add more complexity only when necessary. If you need more flexibility than is available now, please let us know.

The above screenshot also shows how to select a form control for a data field. The Form control dropdown list provides options for the most common data types. Once a few more fields are added to the example, and the correct form controls are selected, the form preview now looks like this.

Dropdown lists are very useful, as they define a fixed set of values for a data field. In forms, users can fill out the field with two clicks and no chance of typos.

Create dropdown values by adding strings to a list, and reordering them them as needed. The following values could be used for a "direction" field.

In forms, these values populate dropdown lists as follows.

Sometimes the definition of a data field is repeated in more than one place. For example, for gym member data you may need a gender for members and for coaches.

This is easily handled using predefined fields. Selecting the Show fields / Predefined fields toggle will display a list of named predefined fields. You add them (using unique names) and define field properties just like with normal fields in the Data tree. For example, a predefined gender field looks like this.

Note that the label here is ignored in forms. The data fields which reuse this predefined field must define their own labels.

Back in the Data tree, the following screenshot shows a demoGender field that uses the predefined "gender" field. All it needs to do is point at the predefined field and add a label, comment or required flag as needed. Note that you can easily jump to the predefined field, and back again, using the arrow tools.