Revision [15734]
This is an old revision of StructDataActionInfo made by DomBonj on 2006-12-02 18:54:28.
StructData Action Documentation
Not Included in official Wikka versionSee also:
Development: StructDataAction.Documentation
Short description
Enables to embed structured (or "semantically tagged", somehow like a database record) data items in a page. You can then:- use a specific visual rendering to format and display only key informations of each data item
- call predefined requests (a la SQL) to select and process data items across all wiki pages
Two examples are provided :
- a "To Do" list
- a contact card
Parameters
Parameters shall be of either of two (exclusive) types:- either a pair ('type', 'data'), if you want to define a data item
name | type | required? | default | description |
---|---|---|---|---|
type | string | required | The data item type. Predefined types are ToDo and Card (see explanation in 'Long description' paragraph below) | |
data | string | required | field1='value1' field2='value2' etc. Optionnality and allowed values depend on value of the 'type' parameter | |
string | optional | The display mode for the data item. Predefined types are false (no display), basic (inline of the type name), table (one-row table with one column per field) and list (table with one row per field) |
- either 'req' with optionnally 'p1', 'p2' and 'p3', if you want to perform a request
name | type | required? | default | description |
---|---|---|---|---|
req | string | required | The request id. Predefined types are ItemTable, ToDos and Cards (see explanation in 'Long description' paragraph below) | |
p1 | string | optional | The request's first parameter.Typically used to filter or sort, but actual semantics are request-specific | |
p2 | string | optional | The request's second parameter.Typically used to filter or sort, but actual semantics are request-specific | |
p3 | string | optional | The request's third parameter.Typically used to filter or sort, but actual semantics are request-specific | |
help | string | optional | If this parameter is present, a one line description of the request and its parameters is displayed |
Notes:
- if you pass both a 'type' and a 'req' parameter, the 'req' parameter will be ignored
Long description
Didn't you ever think: "these wiki are great, but if only I had a way to tag a chunk of page as containing the data for a contact card, a customer call or a calendar entry, in order to perform some database-style request on these data items?"Well, here is a solution. With the structdata action you can do four things:
- embed in any page a "structured data item" which is defiined by a type (e.g. a To-Do list entry) and a list of parameters (or fields, in the database language). Note that fields are not typed;
- validate the list of parameters. You can:
- check for the presence of a mandatory parameter; and
- perform any data validation desired.
An error message will indicate failure to validate a given data item. Note that this requires you to provide the corresponding code;
- control the visual rendering of each data item. You can choose:
- to make it invisible; or
- to display is as a list, a table or an inline text by using predefined display modes; or
- to display it in any custom way you may provide code for.
- perform any selection, processing and aggregation request you wish (example: display all the 'open' To-Do list entries with priority levels of 1 or 2). Of course, here again you have to provide some code.
Usage:
{{structdata (type="datatype" data="fieldslist" [print="printmode"] | req="reqname" [p1="val1"][p2="val2"][p3="val3"] [help]) }}
Examples:
Definition of two To-Do list items. The second one will not be displayed{{structdata type="ToDo" print="table" data="date_open='2006-10-3' owner='jdoe' status='open' date_due='2007/11/13' desc='Complete logo design'"}}
{{structdata type="ToDo" print="false" data="owner='kbill' status='open' desc='Book flight to Lake Tahoe' priority='2' date_open='2006-10-3' "}}
Comments:
- four fields are mandatory: owner, desc (description of the task), date_open and date_due. Dates shall follow the 'yyyy-mm-dd' format.
- date existence check is performed for date_open and date_due.
- no specific visual rendering has been defined. print='table' usually gives good results.
- a request called ToDos is predefined. It displays all To-Do list items in a table, sorted in reverse order of date_open. If parameter p1 is present, only data items whose owner equals p1 are selected. If parameter p2 is present, only data items whose status is equal to p2 are selected.
{{structdata type="Card" data="n='DOE;John' email='jdoe@himself.org' fax='(+1) 415 696 123' tel='212-898-31321' org='himself'"}}
Comments:
- one field is mandatory: n, containing the name of the contact, formatted as 'last_name[;given_name[;middle_name[;title]]]')
- optional fields are: org (organization), email, tel and fax.
- no data validation is performed.
- a contact card is rendered as an inline text. Example: John Doe (His organization).
- a request called Cards is predefined. It displays all contact cards in a table, sorted by name. If parameter p1 is present, only contacts whose organization equals p1 are selected. If parameter p2 is present, its value is used as the name of the field to sort on.
Other considerations
- One could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a language parser and is currently beyond my resources.
- Another possibility would have been to use an XML format (e.g. in the spirit of microformats) to define the data items. However, it seemed to bring more complexity than actual value.
- Other wikis have developed the notion of structured data items, most notably (to my knowledge) twiki and xwiki
Author
DomBonjCategoryDocumentation