Structdata Action Documentation

Not Included in official Wikka version

This is the documentation page for the Structdata action.
 

Documentation


Short description
Enables to embed structured (or "semantically tagged", somehow like a database) data items in a page. You can then:
This is by essence not a turnkey tool, as you have to define your data items and the requests to be performed upon them.

Two examples are provided :
Parameters
Parameters shall be of either of two (exclusive) types:
nametyperequired?defaultdescription
typestringrequiredThe data item type. Predefined types are ToDo and Card (see explanation in the 'Long description' paragraph below)
datastringrequiredfield1='value1' field2='value2' etc. Optionality and allowed values depend on value of the 'type' parameter
printstringoptionalThe 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)

nametyperequired?defaultdescription
reqstringrequiredThe request id. Predefined generic types are ItemTable, ToDos and Cards (see explanation in the 'Long description' paragraph below)
p1stringoptionalThe request's first parameter.Typically used to filter or sort, but actual semantics are request-specific
p2stringoptionalThe request's second parameter.Typically used to filter or sort, but actual semantics are request-specific
p3stringoptionalThe request's third parameter.Typically used to filter or sort, but actual semantics are request-specific
helpstringoptionalIf this parameter is present, a one line description of the request and its parameters is displayed

Notes:
Long description
Didn't you ever think: "these wikis 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:
  1. embed in any page a "structured data item" which is defined by a type (e.g. a To-Do list entry) and a list of parameters (or fields, in the database terminology). Note that fields are not typed;
  2. validate the list of parameters. You can:
  3. - 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.
  4. control the visual rendering of each data item. You can choose:
  5. - to make it invisible; or
    - to display it as a list, a table or an inline text by using predefined display modes; or
    - to display it as a microformat, where applicable
    - to display it in any custom way you may provide code for.
  6. 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


Example 1: To-Do list structured data item
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-4' date_due='2006-12-2' "}}

Comments:
  1. four fields are mandatory: owner, desc (description of the task), date_open and date_due. Dates shall follow the 'yyyy-mm-dd' format.
  2. date existence check is performed for date_open and date_due.
  3. no specific visual rendering has been defined. print='table' usually gives good results:

date_openownerstatusdate_duedesc
2006-10-3jdoeopen2007/11/13Complete logo design

Predefined requests
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. With the two To-do list items defined above, {{structdata req="ToDos"}} would display the following:

ownerdescriptiondue datepage link
kbillBook flight to Lake Tahoe2006-12-2StructDataActionInfo
jdoeComplete logo design2007/11/13StructDataActionInfo


Example 2: Contact card structured data item
Definition of a contact card
{{structdata type="Card" data="n='DOE;John' email='jdoe@his_organization.org' fax='(123) 654-898' tel='(+41) 123 4567' org='His_org'"}}

Comments:
Sample stylesheet for hCard microformat rendering

.vcard .additional-name { display: none; }
.vcard .tel, .vcard .email { font-size: smaller; }
.vcard .org { display: inline; font-style: italic; margin-left: 0.5em; }
.vcard span.n .org { margin: 0; } 

This stylesheet will render the example card as :

John Doe
His_org
(+41) 123 4567
fax (123) 654-898

  1. one field is mandatory: n, containing the name of the contact, formatted as 'last_name[;given_name[;middle_name]]'
  2. optional fields are:
  3. 2.1. org (organization): use the same value as the 'n' field if the contact is an organization instead of a person
    2.2. email
    2.3. tel and/or fax
    2.4. adr (address), formatted as 'street_adress;[city_name];[postal_code];[region_or_state];[country_name]'
    2.5. title
    2.6. url (personal or organizational web address)
    2.7. note (any further information)
  4. no data validation is performed.
  5. a contact card is rendered by default as an inline text displaying the contact's name and (if any) organization, with a 'mailto' hyperlink to the contact's email address and a tooltip showing his/her phone and fax numbers. Example: John Doe (His_org).
  6. optionally, a contact card can be displayed as a hCard microformat. Just add the print="hCard" parameter. The visual rendering of the hCard can be customized by adding classes to the wikka.css stylesheet (an example is given in the right-hand side box.)

Predefined requests
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. As an example, {{structdata req="Cards"}} yields the following table:

Last nameGiven nameEmailPhoneFaxOrganization
DoeJohnjdoe@his_organization.org(+41) 123 4567(123) 654-898His_org

Finally, parameter p3 controls the way the contact cards are formatted:
- if p3 is absent or p3="table", the cards are displayed in a table as shown above
- if p3="vCard", a download button is displayed, which allows to grab a file containing the contact cards in the vCard format (which can be imported into a Personal Information Manager or a phone). In this example, {{structdata req="Cards" p3="vCard"}} displays a button giving access to a file containing:
BEGIN:VCARD
VERSION:2.1
N:DOE;John
FN:John Doe
ORG:His_org
TEL:(+41) 123 4567
TEL;FAX:(123) 654-898
EMAIL;INTERNET:jdoe@his_organization.org
END:VCARD


Example 3: ItemTable request
This is a predefined request which can be used with any type of data item. What it does is displaying in a single table all the data items of a given type (passed as parameter p1) present on the page. This allows a more compact rendering compared to displaying each data item as an independent table. Usually, data items are entered with the print='false' parameter; otherwise they will be displayed twice.
As an example, {{structdata req="ItemTable" p1="ToDo"}} groups the two data items defined in example 1 in the following table:

date_openownerstatusdate_duedescpriority
2006-10-3jdoeopen2007/11/13Complete logo design2
2006-10-4kbillopen2006-12-2Book flight to Lake Tahoe

If you want to control the column order, you can optionally provide a (comma-separated) column list as the p2 parameter.
Thus, {{structdata req="ItemTable" p1="ToDo" p2="owner,desc,status"}} displays:

ownerdescstatusdate_opendate_duepriority
jdoeComplete logo designopen2006-10-32007/11/132
kbillBook flight to Lake Tahoeopen2006-10-42006-12-2

Finally, you can control the request's scope (the set of pages whose data items will be listed) with the p3 parameter. Possible values are:
- "page" (default value; only items from current page are displayed)
- "user" (all pages owned by current user)
- "all" (all pages to which current user has read-access)

To-do, bugs and limitations


Other considerations


Author
DomBonj


CategoryDocumentation
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki