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

Structured data is stored in the metadata of a wiki page as a native PHP array.

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.

The PageSData object, provided by lib/wikilens/PageSData.php

This is a higher-level interface to structured data than the functions described below. It is currently the most straightforward way to access the structured data located on a page. Thanks to JohnRiedl for writing the bulk of this class.

The getField* and getFeature* methods are aliases of each other and are provided for convenience and compatibility with existing code.

Constructors

PageSData PageSData (mixed item [, WikiDB dbi ])

Returns a PageSData instance representing the structured data stored in the item item. Accepts a String or WikiDB_Page as item. If item is a String, the second parameter becomes non-optional and must be an operational WikiDB object.

Instance Methods

Array allCategoryFields ()

Returns an Array containing the identifiers of all structured data fields defined for a category this item is a member of. If this item is a member of multiple categories, the particular category used here is arbitrarily selected in a manner that is consistent for each revision of an item.

mixed getField (String fieldid)

mixed getFeature (String fieldid)

Returns a String or Array containing this item's value for the field fieldid. A null value is returned if fieldid is not a valid structured data field identifier for this item.

mixed getFieldCardinality (String fieldid)

mixed getFeatureCardinality (String fieldid)

Returns a String representing the cardinality of the field fieldid. See the documentation for CategoryField.getParam for additional details. The string "BOGUS" is returned if fieldid is not a valid structured data field identifier for this item.

String getFieldName (String fieldid)

String getFeatureName (String fieldid)

Returns a String containing the publicly displayed name for the field fieldid. The string "BOGUS FEATURE" is returned if fieldid is not a valid structured data field identifier for this item.

mixed setField (String fieldid, mixed value)

mixed setFeature (String fieldid, mixed value)

Sets an item's value for the field fieldid to value. This is not immediately committed to the database. Has no return value.

Boolean update (WikiRequest request [ , String text [, Array meta ] ]

Commits this structured data to the database as a new page revision. The first parameter is a WikiRequest object that is used to determine the author of the new page revision. The optional second parameter specifies the new page text of the revision. The optional third parameter specifies the new revision-level metadata that should be saved. If either optional parameter is omitted or given as null, the current page text or metadata is used.

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 (Mixed item [, Array fields ])

Returns an array with two elements

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

Accepts a String, WikiDB_Page, or WikiDB_PageRevision object as item. If item is a String or WikiDB_Page, the latest revision of the page is used.

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).

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.

The 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

ReiniUrban: I would rename field attrib Name to Text. name should be the identifier, text is what is displayed (added at 11:06:56 AM on 08/27/04)