This page is intended for WikiLens developers who want to use structured data.

Structured data is stored in the content of a wiki page in a pre-defined format that is designed to be human-readable and editable, although the standard method of modifying structured data is through more traditional web-based forms. In a wiki page's contents, the structured data begins with "--- BEGIN STRUCTURED DATA ---" and ends with "--- END STRUCTURED DATA ---".

Structured data is only supported on items that are members of a category as defined by the @Category category. The recognized fields of a page's structured data is specified by the field specification for the category the page belongs to. On the category page (e.g. @Restaurant or @Book), the location of the field specification is denoted by the string "Fields:" followed by the name of a page whose contents constitute a field specification. A field specification is expected in a format similar to structured data and is partially documented in WikiLens/StructuredDataTutorial.

The remainder of this page contains structured data API documentation.

Functions provided by lib/wikilens/Utils.php

Array get_categories ()

Returns all categories as an associative array of WikiDB_Page objects. Keys are category names and values are WikiDB_Page objects.

mixed get_item_field_spec_page (mixed item)

Returns the the WikiDB_Page containing the field specification for the item item, or the Boolean value false if no field specification was found. Accepts a String or WikiDB_Page object as item.

mixed get_category_field_spec_page (mixed category)

Returns the WikiDB_Page containing the field specification for the category category, or the Boolean value false if no field specification was found. Accepts a String or WikiDB_Page object as category.

Array get_fields_by_item (mixed item)

Returns an associative array of CategoryField objects containing all recognized fields for the item item. Keys are field identifiers and values are CategoryField objects. Accepts a String or WikiDB_Page object as item.

Array get_fields_by_category (mixed category)

Returns an associative array of CategoryField objects containing all recognized fields for the category category. Keys are field identifiers and values are CategoryField objects. Accepts a String or WikiDB_Page object as category.

Array extract_fields (mixed spec_page)

Returns an associative array of CategoryField objects containing all fields specified in the page spec_page. Keys are field identifiers and values are CategoryField objects. Accepts a String or WikiDB_Page object as spec_page.

Array extract_structured_data (String content [, Array fields ])

Returns an array with two elements

1. an Array containing a parsed/processed representation of any structured data found in content
2. a String containing everything except the structured data portion of content

An associative array of CategoryField objects (field identifiers as keys, CategoryField objects as values) can be passed as the optional second parameter fields to enforce which fields of the structured data are recognized and returned. Additionally, any default values specified in fields will be returned for fields not present in content.

The structured data array is a simple associative array with field identifiers as keys and field values as values. Values may be strings or arrays, depending on the field specification. If a value is an array, it will be an associative array with its keys equal to its values (thus making lookups fast, while allowing single-variable foreach loops to work on them as expected).

String inject_structured_data (Array data, String content)

Returns the wiki page content content with structured data from data added to it. This is the inverse of extract_structured_data.

WikiDB_PageRevision update_page_structured_data (WikiDB_Page page, mixed fieldlist [, String index ])

Updates structured data in page using inputs from the current HTTP request. The intended use of this function is in response to submission of a form containing widgets produced by CategoryField.makeWidget.

The fields updated are limited to those with field identifiers listed in fieldlist as an Array -- providing a non-array value as fieldlist will cause all fields to be updated.

The optional third parameter index allows for updates to multiple pages be specified by one GET or POST request. See CategoryField.makeWidget and CategoryField.getInput for further details.

Returns the newly-created revision of page if changes were made, or the current revision of page otherwise.

CategoryField Object

The CategoryField object represents a structured data field and contains data about its type, default values, acceptable values, and has the ability to produce HTML containing a widget for changing the value of the field. Some of its methods are listed below.

HtmlElement makeWidget ( [ mixed value [, String index ] )

Returns a widget for this field suitable for inclusion in a form.

If the optional first parameter value is provided, the widget will have default value value. Otherwise, the default value for this field is used.

If the optional second parameter index is provided, the widget will be created with an array as an input name with the index for this object as index. This is intended for placing widgets for multiple items in a single form.

mixed getInput (Request request [, String index ] )

Returns the value for this field given by the HTTP request request. This is an Array if this field is multi-valued, and a String otherwise.

If the optional second parameter index is provided, this returns the value of this field at index index. This is intended to retrieve values of widgets created by CategoryField.makeWidget used with its optional index parameter.

mixed getParam (String attribute)

Returns the attribute of this field described by attribute. The Boolean value false is returned if the attribute is not set. Some attributes of interest are listed below.

• ID - field identifier
• NAME - field name (equal to field identifier if not provided in field specification)
• CARDINALITY - the string "multiple" if this field is multi-valued, and "single" otherwise
• DEFAULT - the default value of this field (this is an Array if this field is multi-valued, and a String otherwise)
• WIDGET - the type of the preferred widget for this field (can take values "textbox", "textarea", "radio", "checkbox", "dropdown", "select", "hidden", and "none")
• OPTIONS - an associative array of available options for this field; empty if this is not a constrained field