3. Structuring Your Data Using Properties

By default, each page in a Jot wiki has a main/text property that contains the page content, as well as a number of properties that contain meta data, such as name and createTime. In addition to these default properties, a page can have any number of custom properties. Each property has a name and a value of a particular type, such as text or date.

Defining custom properties enables you to structure the data in your wiki pages so that you can display, set, and reference wiki content using JotLib functions and expressions.

Defining Custom Properties with Forms

To add custom properties to a page, you first create a separate Jot page that declares a form. This form page defines properties that get saved to a page when you edit that page using the form.

Creating Forms

A form is just a page that contains a <jot:form> or <jot:declareForm> tag and one or more <jot:field> tags. Each field tag specifies the name of a property and the type of data it contains, such as text or date. (If no type is specified, the field defaults to a text field.)

When you create a page to define a form, give the page a name that identifies it as a form, such as XYZForm. In the form tag, set the form name to the same name as the page. In some cases, you'll need to reference the form by its page name, and in others you need to reference the name of the form itself, so using the same name for both will eliminate any confusion over which name you should use.

For example, to define a simple event form that contains text fields for the event title and location and a date field for the event date, create a page called EventForm:

<jot:form name="EventForm">
     | Title: | <jot:field name="title" /> |
     | Location: | <jot:field name="location" /> |
     | Date: | <jot:field name="event_date" type="date" /> |
</jot:form>

In addition to specifying the data type, the field type also determines how the property will be displayed and what type of control will be used to modify it when the page is viewed in edit mode. For example, a text field displays a simple text entry field, while a date field provides a graphical calendar control:

Applying Forms

To add custom properties to a page, you edit that page using a Jot form. This is some times called applying the form to a page.

Think of the form as a mask or stamp that imprints its properties on the page being edited. The same form can be applied to any number of wiki pages, and a particular page can have different forms applied to it at different times. However a page can have only one form as its default form at a time.

The properties added by a particular form become part of the page—they do not go away when a different form is applied. The currently-applied form acts as a mask that controls which properties are visible, but all of the page properties can still be accessed through JotScript or JavaScript code.

There are a number of ways to apply a form. You can explicitly apply a form for a given page edit by appending a form query string parameter to the page URL. For example to view a page with the default form, append ?form=/System/Forms/DefaultForm to the URL:

Adding the edit query string parameter displays the page in edit mode with the specified form:

To apply a form so that it is used by default when the page is displayed, you can use the ApplyForm system form to edit the page, for example:

ApplyForm sets the sys/form property of the page, which is where each page's default form name is stored.

You can also apply forms programmatically through the CreatePage and saveForm functions.

Note: To see what form is currently applied to a page, you can append xml=pretty the page's query string. The form is specified at the end of the page content in the sys/form property.

Accessing Page Properties

To access a property defined by a particular form, you need to include the name of the form when you reference the property. For example, to access the current page's event_date property defined by the EventForm with an XPath expression, you would specify the property as ${page/EventForm/event_date}. In Javascript, you use dot notation in place of the path notation. For example, you could reference the event_date property as myPage.EventForm.event_date.

Referencing Pages

To access properties of a the current page in JotScript, you use the global page variable, as shown above. To access properties of a page other than the current page, you can use the nodeinfo function to define a variable that references the page you are interested in. For example, to use nodeinfo to reference properties of an event page called Event7 you could define a variable called MyPage:

<jot:nodeinfo name="MyPage" node="Event7" />

To access properties associated with the node, you can then reference it using the MyPage variable:

${MyPage/name} - MyPage's name
${MyPage/EventForm/event_date} - MyPage's event_date property, defined by the \EventForm.

In Javascript, you can get a reference to any page in your Jotspot through the pages object using bracket notation. Javascript bracket notation makes it possible to access properties of an object by name, so to get a reference to a Jot page, you can simply specify its name in quotes. For example, to get a reference to the Event7 page:

var myPage = jot.pages["Event7"];

Once you have a reference to page, you can use dot notation to access specific properties. For example, to access the event_date property defined by the EventForm:

jot.out.write(myPage.EventForm.event_date+" - MyPage's event_date property.");