Revision history for StructDataActionInfo


Revision [23371]

Last edited on 2016-05-20 07:38:47 by DomBonj [Replaces old-style internal links with new pipe-split links.]
Additions:
~- use a specific visual rendering (including [[http://www.microformats.org | microformats]]) to format and display only key informations of each data item
~~ - to display it as a [[http://www.microformats.org | microformat]], where applicable
~1) optionally, a contact card can be displayed as a [[http://www.microformats.org/wiki/hcard | 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.)
~ - if p3="vCard", a download button is displayed, which allows to grab a file containing the contact cards in the [[http://en.wikipedia.org/wiki/VCard | 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:
~- Other wikis have developed the notion of structured data items, most notably (to my knowledge) [[http://twiki.org | twiki]] and [[http://www.xwiki.org | xwiki]], as well as the interesting [[http://projects.nickblundell.org.uk/wikidbase | wikidbase]].
Deletions:
~- use a specific visual rendering (including [[http://www.microformats.org microformats]]) to format and display only key informations of each data item
~~ - to display it as a [[http://www.microformats.org microformat]], where applicable
~1) optionally, a contact card can be displayed as a [[http://www.microformats.org/wiki/hcard 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.)
~ - if p3="vCard", a download button is displayed, which allows to grab a file containing the contact cards in the [[http://en.wikipedia.org/wiki/VCard 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:
~- Other wikis have developed the notion of structured data items, most notably (to my knowledge) [[http://twiki.org twiki]] and [[http://www.xwiki.org xwiki]], as well as the interesting [[http://projects.nickblundell.org.uk/wikidbase wikidbase]].


Revision [20125]

Edited on 2008-07-13 17:06:44 by DomBonj [added link to wikidbase]
Additions:
~- Other wikis have developed the notion of structured data items, most notably (to my knowledge) [[http://twiki.org twiki]] and [[http://www.xwiki.org xwiki]], as well as the interesting [[http://projects.nickblundell.org.uk/wikidbase wikidbase]].
Deletions:
~- Other wikis have developed the notion of structured data items, most notably (to my knowledge) [[http://twiki.org twiki]] and [[http://www.xwiki.org xwiki]].


Revision [19773]

Edited on 2008-04-13 05:46:30 by DomBonj [typo]
Additions:
Enables to embed structured (or "semantically tagged", somehow like a database) data items in a page. You can then:
Deletions:
Enables to embed structured (or "semantically tagged", somehow like a database data items in a page. You can then:


Revision [19772]

Edited on 2008-04-13 05:40:28 by DomBonj [added documentation for hCard microformat support in v1.01]
Additions:
~- use a specific visual rendering (including [[http://www.microformats.org microformats]]) to format and display only key informations of each data item
""<table class="data" cellspacing="0" cellpadding="2" border="1">
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionality and allowed values depend on value of the 'type' parameter</td></tr>
~- or //req// with context-dependent //p1//, //p2// and //p3//, if you want to perform a request
""<table class="data" cellspacing="0" cellpadding="2" border="1">
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined generic types are ItemTable, ToDos and Cards (see explanation in the 'Long description' paragraph below)</td></tr>
~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;
~~ - to display it as a [[http://www.microformats.org microformat]], where applicable
""<table class='data' cellpadding='2' cellspacing='1' border='2'><thead><tr><th class='comment'>date_open</th><th class='comment'>owner</th><th class='comment'>status</th><th class='comment'>date_due</th><th class='comment'>desc</th></tr></thead><tbody><tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design </td></tr></tbody></table>""
""<table class='data' cellpadding='2' cellspacing='1' border='2'><thead><tr class='comment'><th>owner</th><th>description</th><th>due date</th><th>page link</th></tr></thead><tbody><tr><td>kbill</td><td>Book flight to Lake Tahoe</td><td style='background-color:red; color:white; '>2006-12-2</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr><tr><td>jdoe</td><td>Complete logo design</td><td>2007/11/13</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr></tbody></table>""
>>//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 :
""<div class="vcard"><span class="n"><span class="fn"><span class="given-name">John</span> <span class="family-name">Doe</span></span></span><div class="org" style="display: inline; font-style: italic; margin-left: 0.5em;">His_org</div><div class="email" style="font-size: smaller; "><a href="mailto:jdoe@his_organization.org">jdoe@his_organization.org</a></div><div class="tel" style="font-size: smaller; "><span class="value">(+41) 123 4567</span></div><div class="tel" style="font-size: smaller; "><span class="type">fax</span> <span class="value">(123) 654-898</span></div></div>""
>>
~1) one field is mandatory: n, containing the name of the contact, formatted as 'last_name[;given_name[;middle_name]]'
~1) optional fields are:
~~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)
~1) 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: ""<a href='mailto:jdoe@his_organization.org' title='phone:(+41) 123 4567 / fax: (123) 654-898'>John Doe (His_org)</a>"".
~1) optionally, a contact card can be displayed as a [[http://www.microformats.org/wiki/hcard 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.)
""<table class='data' cellpadding='2' cellspacing='1' border='2'><thead><tr><th class='comment'>Last name</th><th class='comment'>Given name</th><th class='comment'>Email</th><th class='comment'>Phone</th><th class='comment'>Fax</th><th class='comment'>Organization</th></tr></thead><tbody><tr><td>Doe</td><td>John</td><td>jdoe@his_organization.org</td><td>(+41) 123 4567</td><td>(123) 654-898</td><td>His_org</td></tr></tbody></table>""
TEL:(+41) 123 4567
""<table class='data' cellpadding='2' cellspacing='1' border='2'><thead><tr class='comment'><th>date_open</th><th>owner</th><th>status</th><th>date_due</th><th>desc</th><th>priority</th></tr></thead>
<tbody><tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design</td><td>2</td></tr>
</tbody></table>""
""<table class='data' cellpadding='2' cellspacing='1' border='2'><thead><tr class='comment'><th>owner</th><th>desc</th><th>status</th><th>date_open</th><th>date_due</th><th>priority</th></tr></thead>
<tbody><tr><td>jdoe</td><td>Complete logo design</td><td>open</td><td>2006-10-3</td><td>2007/11/13</td><td>2</td></tr>
</tbody></table>""
~- Double and single quotes around parameters and values shall be used in the same way as in the examples.
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML/Javascript form into the page.
~- Possible refactoring: use an object approach to dynamically extend a base class with new structured data item types, each packaged in its own file.
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved when processing requests.
~- One could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntactic parser and is currently beyond my resources.
Deletions:
~- use a specific visual rendering to format and display only key informations of each data item
""<table cellspacing="0" cellpadding="2" border="1">
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionality and allowed values depend on value of the //type// parameter</td></tr>
~- either //req// with context-dependent //p1//, //p2// and //p3//, if you want to perform a request
""<table cellspacing="0" cellpadding="2" border="1">
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined types are ItemTable, ToDos and Cards (see explanation in the 'Long description' paragraph below)</td></tr>
~1) 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 terminology). Note that fields are not typed;
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr><th class='comment'>date_open</th><th class='comment'>owner</th><th class='comment'>status</th><th class='comment'>date_due</th><th class='comment'>desc</th></tr><tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design </td></tr></table>""
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>owner</th><th>description</th><th>due date</th><th>page link</th></tr><tr><td>kbill</td><td>Book flight to Lake Tahoe</td><td style='background-color:red; color:white; '>2006-12-2</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr><tr><td>jdoe</td><td>Complete logo design</td><td>2007/11/13</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr></table>""
~1) one field is mandatory: n, containing the name of the contact, formatted as 'last_name[;given_name[;middle_name[;title]]]')
~1) optional fields are: org (organization), email, tel and fax.
~1) a contact card is rendered by default as an inline text diplaying 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: ""<a href='mailto:jdoe@his_organization.org' title='phone:(+41) 123 4567 / fax: (123) 654-898'>John Doe (His_org)</a>"".
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr><th class='comment'>Last name</th><th class='comment'>Given name</th><th class='comment'>Email</th><th class='comment'>Phone</th><th class='comment'>Fax</th><th class='comment'>Organization</th></tr><tr><td>Doe</td><td>John</td><td>jdoe@his_organization.org</td><td>(+41) 123 4567</td><td>(123) 654-898</td><td>His_org</td></tr></table>""
TEL;WORK:(+41) 123 4567
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>date_open</th><th>owner</th><th>status</th><th>date_due</th><th>desc</th><th>priority</th></tr>
<tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design</td><td>2</td></tr>
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>owner</th><th>desc</th><th>status</th><th>date_open</th><th>date_due</th><th>priority</th></tr>
<tr><td>jdoe</td><td>Complete logo design</td><td>open</td><td>2006-10-3</td><td>2007/11/13</td><td>2</td></tr>
~- Use of double and single quotes around parameters and values shall follow the example.
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page.
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved in request handling.
~- One could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntaxic parser and is currently beyond my resources.
~- Another possibility would have been to use an XML format (e.g. in the spirit of [[http://microformats.org/ microformats]]) to define the data items. However, it seemed to bring more complexity than actual value.


Revision [19491]

Edited on 2008-01-29 17:27:09 by BrianKoontz [Previous version restored]
Additions:
=====Structdata Action Documentation=====
//Not Included in official Wikka version//
>>==See also:==
Development: StructDataAction>>This is the documentation page for the Structdata action.::c::
===Documentation===
==Short description==
Enables to embed structured (or "semantically tagged", somehow like a database 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
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 :
~- 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
""<table cellspacing="0" cellpadding="2" border="1">
<thead>
<tr><th scope="col">name</th><th scope="col">type</th><th scope="col">required?</th><th scope="col">default</th><th scope="col">description</th></tr>
</thead>
<tbody>
<tr><td>type</td><td>string</td><td>required</td><td></td><td>The data item type. Predefined types are ToDo and Card (see explanation in the 'Long description' paragraph below)</td></tr>
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionality and allowed values depend on value of the //type// parameter</td></tr>
<tr><td>print</td><td>string</td><td>optional</td><td></td><td>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)</td></tr>
</tbody>
</table>""
~- either //req// with context-dependent //p1//, //p2// and //p3//, if you want to perform a request
""<table cellspacing="0" cellpadding="2" border="1">
<thead>
<tr><th scope="col">name</th><th scope="col">type</th><th scope="col">required?</th><th scope="col">default</th><th scope="col">description</th></tr>
</thead>
<tbody>
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined types are ItemTable, ToDos and Cards (see explanation in the 'Long description' paragraph below)</td></tr>
<tr><td>p1</td><td>string</td><td>optional</td><td></td><td>The request's first parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
<tr><td>p2</td><td>string</td><td>optional</td><td></td><td>The request's second parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
<tr><td>p3</td><td>string</td><td>optional</td><td></td><td>The request's third parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
<tr><td>help</td><td>string</td><td>optional</td><td></td><td>If this parameter is present, a one line description of the request and its parameters is displayed</td></tr>
</tbody>
</table>""
__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 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 defiined 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;
~1) 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.
~1) control the visual rendering of each data item. You can choose:
~~ - 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 in any custom way you may provide code for.
~1) 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.
~1) date existence check is performed for date_open and date_due.
~1) no specific visual rendering has been defined. print='table' usually gives good results:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr><th class='comment'>date_open</th><th class='comment'>owner</th><th class='comment'>status</th><th class='comment'>date_due</th><th class='comment'>desc</th></tr><tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design </td></tr></table>""
__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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>owner</th><th>description</th><th>due date</th><th>page link</th></tr><tr><td>kbill</td><td>Book flight to Lake Tahoe</td><td style='background-color:red; color:white; '>2006-12-2</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr><tr><td>jdoe</td><td>Complete logo design</td><td>2007/11/13</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr></table>""
==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:
~1) one field is mandatory: n, containing the name of the contact, formatted as 'last_name[;given_name[;middle_name[;title]]]')
~1) optional fields are: org (organization), email, tel and fax.
~1) no data validation is performed.
~1) a contact card is rendered by default as an inline text diplaying 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: ""<a href='mailto:jdoe@his_organization.org' title='phone:(+41) 123 4567 / fax: (123) 654-898'>John Doe (His_org)</a>"".
__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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr><th class='comment'>Last name</th><th class='comment'>Given name</th><th class='comment'>Email</th><th class='comment'>Phone</th><th class='comment'>Fax</th><th class='comment'>Organization</th></tr><tr><td>Doe</td><td>John</td><td>jdoe@his_organization.org</td><td>(+41) 123 4567</td><td>(123) 654-898</td><td>His_org</td></tr></table>""
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 [[http://en.wikipedia.org/wiki/VCard 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;WORK:(+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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>date_open</th><th>owner</th><th>status</th><th>date_due</th><th>desc</th><th>priority</th></tr>
<tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design</td><td>2</td></tr>
<tr><td>2006-10-4</td><td>kbill</td><td>open</td><td>2006-12-2</td><td>Book flight to Lake Tahoe</td></tr>
</table>""
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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>owner</th><th>desc</th><th>status</th><th>date_open</th><th>date_due</th><th>priority</th></tr>
<tr><td>jdoe</td><td>Complete logo design</td><td>open</td><td>2006-10-3</td><td>2007/11/13</td><td>2</td></tr>
<tr><td>kbill</td><td>Book flight to Lake Tahoe</td><td>open</td><td>2006-10-4</td><td>2006-12-2</td></tr>
</table>""
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===
~- Use of double and single quotes around parameters and values shall follow the example.
~- A field can not be multi-line (should be fixed in release 1.1.7.)
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page.
===Other considerations===
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved in request handling.
~- One could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntaxic parser and is currently beyond my resources.
~- Another possibility would have been to use an XML format (e.g. in the spirit of [[http://microformats.org/ 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) [[http://twiki.org twiki]] and [[http://www.xwiki.org xwiki]].
==Author==
DomBonj
CategoryDocumentation
Deletions:
<<===This page has moved===
This page can now be found on the [[Docs:StructDataActionInfo Wikka Documentation Server]].
Thanks for updating your bookmarks!
An archive of [[http://wikkawiki.org/StructDataActionInfo/revisions
old revisions of this page]] is still available for reference.<<
::c::
CategoryMigratedDocs


Revision [18094]

Edited on 2008-01-27 02:34:53 by DomBonj [Migrated to doc server]
Additions:
<<===This page has moved===
This page can now be found on the [[Docs:StructDataActionInfo Wikka Documentation Server]].
Thanks for updating your bookmarks!
An archive of [[http://wikkawiki.org/StructDataActionInfo/revisions
old revisions of this page]] is still available for reference.<<
::c::
CategoryMigratedDocs
Deletions:
=====Structdata Action Documentation=====
//Not Included in official Wikka version//
>>==See also:==
Development: StructDataAction>>This is the documentation page for the Structdata action.::c::
===Documentation===
==Short description==
Enables to embed structured (or "semantically tagged", somehow like a database 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
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 :
~- 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
""<table cellspacing="0" cellpadding="2" border="1">
<thead>
<tr><th scope="col">name</th><th scope="col">type</th><th scope="col">required?</th><th scope="col">default</th><th scope="col">description</th></tr>
</thead>
<tbody>
<tr><td>type</td><td>string</td><td>required</td><td></td><td>The data item type. Predefined types are ToDo and Card (see explanation in the 'Long description' paragraph below)</td></tr>
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionality and allowed values depend on value of the //type// parameter</td></tr>
<tr><td>print</td><td>string</td><td>optional</td><td></td><td>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)</td></tr>
</tbody>
</table>""
~- either //req// with context-dependent //p1//, //p2// and //p3//, if you want to perform a request
""<table cellspacing="0" cellpadding="2" border="1">
<thead>
<tr><th scope="col">name</th><th scope="col">type</th><th scope="col">required?</th><th scope="col">default</th><th scope="col">description</th></tr>
</thead>
<tbody>
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined types are ItemTable, ToDos and Cards (see explanation in the 'Long description' paragraph below)</td></tr>
<tr><td>p1</td><td>string</td><td>optional</td><td></td><td>The request's first parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
<tr><td>p2</td><td>string</td><td>optional</td><td></td><td>The request's second parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
<tr><td>p3</td><td>string</td><td>optional</td><td></td><td>The request's third parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
<tr><td>help</td><td>string</td><td>optional</td><td></td><td>If this parameter is present, a one line description of the request and its parameters is displayed</td></tr>
</tbody>
</table>""
__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 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 defiined 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;
~1) 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.
~1) control the visual rendering of each data item. You can choose:
~~ - 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 in any custom way you may provide code for.
~1) 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.
~1) date existence check is performed for date_open and date_due.
~1) no specific visual rendering has been defined. print='table' usually gives good results:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr><th class='comment'>date_open</th><th class='comment'>owner</th><th class='comment'>status</th><th class='comment'>date_due</th><th class='comment'>desc</th></tr><tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design </td></tr></table>""
__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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>owner</th><th>description</th><th>due date</th><th>page link</th></tr><tr><td>kbill</td><td>Book flight to Lake Tahoe</td><td style='background-color:red; color:white; '>2006-12-2</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr><tr><td>jdoe</td><td>Complete logo design</td><td>2007/11/13</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr></table>""
==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:
~1) one field is mandatory: n, containing the name of the contact, formatted as 'last_name[;given_name[;middle_name[;title]]]')
~1) optional fields are: org (organization), email, tel and fax.
~1) no data validation is performed.
~1) a contact card is rendered by default as an inline text diplaying 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: ""<a href='mailto:jdoe@his_organization.org' title='phone:(+41) 123 4567 / fax: (123) 654-898'>John Doe (His_org)</a>"".
__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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr><th class='comment'>Last name</th><th class='comment'>Given name</th><th class='comment'>Email</th><th class='comment'>Phone</th><th class='comment'>Fax</th><th class='comment'>Organization</th></tr><tr><td>Doe</td><td>John</td><td>jdoe@his_organization.org</td><td>(+41) 123 4567</td><td>(123) 654-898</td><td>His_org</td></tr></table>""
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 [[http://en.wikipedia.org/wiki/VCard 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;WORK:(+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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>date_open</th><th>owner</th><th>status</th><th>date_due</th><th>desc</th><th>priority</th></tr>
<tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design</td><td>2</td></tr>
<tr><td>2006-10-4</td><td>kbill</td><td>open</td><td>2006-12-2</td><td>Book flight to Lake Tahoe</td></tr>
</table>""
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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>owner</th><th>desc</th><th>status</th><th>date_open</th><th>date_due</th><th>priority</th></tr>
<tr><td>jdoe</td><td>Complete logo design</td><td>open</td><td>2006-10-3</td><td>2007/11/13</td><td>2</td></tr>
<tr><td>kbill</td><td>Book flight to Lake Tahoe</td><td>open</td><td>2006-10-4</td><td>2006-12-2</td></tr>
</table>""
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===
~- Use of double and single quotes around parameters and values shall follow the example.
~- A field can not be multi-line (should be fixed in release 1.1.7.)
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page.
===Other considerations===
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved in request handling.
~- One could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntaxic parser and is currently beyond my resources.
~- Another possibility would have been to use an XML format (e.g. in the spirit of [[http://microformats.org/ 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) [[http://twiki.org twiki]] and [[http://www.xwiki.org xwiki]].
==Author==
DomBonj
CategoryDocumentation


Revision [16611]

Edited on 2007-05-20 10:10:40 by DomBonj [added 'scope' parameter to ItemTable request]
Additions:
=====Structdata Action Documentation=====
Development: StructDataAction>>This is the documentation page for the Structdata action.::c::
Enables to embed structured (or "semantically tagged", somehow like a database data items in a page. You can then:
~- either a pair (//type//, //data//), if you want to define a data item
<tr><td>type</td><td>string</td><td>required</td><td></td><td>The data item type. Predefined types are ToDo and Card (see explanation in the 'Long description' paragraph below)</td></tr>
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionality and allowed values depend on value of the //type// parameter</td></tr>
~- either //req// with context-dependent //p1//, //p2// and //p3//, if you want to perform a request
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined types are ItemTable, ToDos and Cards (see explanation in the 'Long description' paragraph below)</td></tr>
~- If you pass ''both'' a //type// and a //req// parameter, the //req// parameter will be ignored
Well, here is a solution. With the Structdata action you can do four things:
~1) 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.
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)
~- Use of double and single quotes around parameters and values shall follow the example.
~- A field can not be multi-line (should be fixed in release 1.1.7.)
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page.
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved in request handling.
~- One could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntaxic parser and is currently beyond my resources.
~- Another possibility would have been to use an XML format (e.g. in the spirit of [[http://microformats.org/ 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) [[http://twiki.org twiki]] and [[http://www.xwiki.org xwiki]].
Deletions:
=====StructData Action Documentation=====
Development: StructDataAction.>>This is the documentation page for the structdata action.::c::
Enables to embed structured (or "semantically tagged", somehow like a database record) data items in a page. You can then:
~&To access items across all wiki pages, locate this line:
if (($row['_wikkapage']==$this->GetPageTag()) && ($row['type']==$p1))
and change to
if ($row['type']==$p1)
~- either a pair ('type', 'data'), if you want to define a data item
<tr><td>type</td><td>string</td><td>required</td><td></td><td>The data item type. Predefined types are ToDo and Card (see explanation in 'Long description' paragraph below)</td></tr>
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionality and allowed values depend on value of the 'type' parameter</td></tr>
~- either 'req' with optionnally 'p1', 'p2' and 'p3', if you want to perform a request
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined types are ItemTable, ToDos and Cards (see explanation in 'Long description' paragraph below)</td></tr>
~- if you pass ''both'' a 'type' and a 'req' parameter, the 'req' parameter will be ignored
Well, here is a solution. With the structdata action you can do four things:
~1) 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.
~- a field can not be multi-line.
~- a possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page.
~- a nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved in request handling.
~- one could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntaxic parser and is currently beyond my resources.
~- another possibility would have been to use an XML format (e.g. in the spirit of [[http://microformats.org/ 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


Revision [16559]

Edited on 2007-05-13 01:03:37 by BrianKoontz [Instructions to enable access across all wiki pages]
Additions:
~&To access items across all wiki pages, locate this line:
if (($row['_wikkapage']==$this->GetPageTag()) && ($row['type']==$p1))
and change to
if ($row['type']==$p1)


Revision [15810]

Edited on 2006-12-16 15:04:35 by DomBonj [Instructions to enable access across all wiki pages]
Additions:
~ - if p3="vCard", a download button is displayed, which allows to grab a file containing the contact cards in the [[http://en.wikipedia.org/wiki/VCard 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:
Deletions:
~ - if p3="vCard", a download button is displayed, which allows to grab a file containing the contact cards in the [[http://en.wikipedia.org/wiki/VCard vCard]] format (which can be imported into a Personal Information Manager or a phone). In this example, ""{{structdata req="Cards" p3="vCard"}}"" gives access to a file containing:


Revision [15808]

Edited on 2006-12-16 13:57:15 by DomBonj [Added documentation for ItemTable and vCard export]
Additions:
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 [[http://en.wikipedia.org/wiki/VCard vCard]] format (which can be imported into a Personal Information Manager or a phone). In this example, ""{{structdata req="Cards" p3="vCard"}}"" gives access to a file containing:
%%BEGIN:VCARD
VERSION:2.1
N:DOE;John
FN:John Doe
ORG:His_org
TEL;WORK:(+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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>date_open</th><th>owner</th><th>status</th><th>date_due</th><th>desc</th><th>priority</th></tr>
<tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design</td><td>2</td></tr>
<tr><td>2006-10-4</td><td>kbill</td><td>open</td><td>2006-12-2</td><td>Book flight to Lake Tahoe</td></tr>
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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>owner</th><th>desc</th><th>status</th><th>date_open</th><th>date_due</th><th>priority</th></tr>
<tr><td>jdoe</td><td>Complete logo design</td><td>open</td><td>2006-10-3</td><td>2007/11/13</td><td>2</td></tr>
<tr><td>kbill</td><td>Book flight to Lake Tahoe</td><td>open</td><td>2006-10-4</td><td>2006-12-2</td></tr>


Revision [15807]

Edited on 2006-12-16 10:34:24 by DomBonj [typos]
Additions:
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?"
~1) 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 terminology). Note that fields are not typed;
Deletions:
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?"
~1) 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;


Revision [15806]

Edited on 2006-12-15 16:46:18 by DomBonj [added example of Cards request]
Additions:
This is by essence ''not a turnkey tool'', as you have to define your data items and the requests to be performed upon them.
%%{{structdata type="Card" data="n='DOE;John' email='jdoe@his_organization.org' fax='(123) 654-898' tel='(+41) 123 4567' org='His_org'"}}%%
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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr><th class='comment'>Last name</th><th class='comment'>Given name</th><th class='comment'>Email</th><th class='comment'>Phone</th><th class='comment'>Fax</th><th class='comment'>Organization</th></tr><tr><td>Doe</td><td>John</td><td>jdoe@his_organization.org</td><td>(+41) 123 4567</td><td>(123) 654-898</td><td>His_org</td></tr></table>""
~- a field can not be multi-line.
~- a possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page.
~- a nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved in request handling.
~- one could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntaxic parser and is currently beyond my resources.
~- another possibility would have been to use an XML format (e.g. in the spirit of [[http://microformats.org/ 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
Deletions:
This is by essence ''not a turnkey tool'', as you have to define your data items and the request to be performed upon them.
%%{{structdata type="Card" data="n='DOE;John' email='jdoe@his_organization.org' fax='(123) 654-8987' tel='(+41) 123 4567' org='His_org'"}}%%
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.
~- a field can not be multi-line (yet).
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page.
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved in request handling.
~- One could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntaxic parser and is currently beyond my resources.
~- Another possibility would have been to use an XML format (e.g. in the spirit of [[http://microformats.org/ 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


Revision [15805]

Edited on 2006-12-15 01:34:28 by BrianKoontz [Minor edit]
Additions:
%%{{structdata type="Card" data="n='DOE;John' email='jdoe@his_organization.org' fax='(123) 654-8987' tel='(+41) 123 4567' org='His_org'"}}%%
Deletions:
%%{{structdata type="Card" data="n='DOE;John' email='jdoe@his_organization.org' fax='(123) 654-898 tel='(+41) 123 4567' org='His_org'"}}%%


Revision [15747]

Edited on 2006-12-03 09:47:08 by DomBonj [Minor edit]
Additions:
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionality and allowed values depend on value of the 'type' parameter</td></tr>
Deletions:
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionnality and allowed values depend on value of the 'type' parameter</td></tr>


Revision [15746]

Edited on 2006-12-03 09:46:41 by DomBonj [Minor edit]
Additions:
~~ - to display it as a list, a table or an inline text by using predefined display modes; or
Deletions:
~~ - to display is as a list, a table or an inline text by using predefined display modes; or


Revision [15744]

Edited on 2006-12-03 08:54:42 by DomBonj [Minor edit]
Additions:
==Usage==
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:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr class='comment'><th>owner</th><th>description</th><th>due date</th><th>page link</th></tr><tr><td>kbill</td><td>Book flight to Lake Tahoe</td><td style='background-color:red; color:white; '>2006-12-2</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr><tr><td>jdoe</td><td>Complete logo design</td><td>2007/11/13</td><td align='center'><a href='./StructDataActionInfo'>StructDataActionInfo</a></td></tr></table>""
==Example 2: Contact card structured data item==
%%{{structdata type="Card" data="n='DOE;John' email='jdoe@his_organization.org' fax='(123) 654-898 tel='(+41) 123 4567' org='His_org'"}}%%
~1) a contact card is rendered by default as an inline text diplaying 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: ""<a href='mailto:jdoe@his_organization.org' title='phone:(+41) 123 4567 / fax: (123) 654-898'>John Doe (His_org)</a>"".
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.
~- a field can not be multi-line (yet).
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page.
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change to the database structure. However, this approach relies on regular expressions and is probably not very scalable in terms of the performance achieved in request handling.
~- One could wish, instead of having pre-cooked requests, to be able to run SQL-style SELECT statements. This would require a syntaxic parser and is currently beyond my resources.
Deletions:
==Usage:==
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 above defined To-do ist items, ""{{structdata req="ToDos"}} would display the following:
%%{{structdata type="Card" data="n='DOE;John' email='jdoe@himself.org' fax='(+1) 415 696 123' tel='212-898-31321' org='himself'"}}
%%
~1) a contact card is rendered as an inline text. Example: ""<a href='mailto:jdoe@his_organization.org' title='phone:(123)-456-7890 / fax: (123) 654-898'>John Doe (His organization)</a>"".
~1) 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.
~- a field can not be multi-line (yet)
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change on the database structure. However, this approach is probably not very scalable in terms of performance of request handling.
~- 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.


Revision [15743]

Edited on 2006-12-03 08:36:44 by DomBonj [Minor edit]
Additions:
~~ An error message will indicate failure to validate a given data item. Note that this requires you to provide the corresponding code.
===Examples===
== Example 1: To-Do list structured data item==
%%{{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' "}}%%
~1) no specific visual rendering has been defined. print='table' usually gives good results:
""<table class='wikka' cellpadding='2' cellspacing='1' border='2'><tr><th class='comment'>date_open</th><th class='comment'>owner</th><th class='comment'>status</th><th class='comment'>date_due</th><th class='comment'>desc</th></tr><tr><td>2006-10-3</td><td>jdoe</td><td>open</td><td>2007/11/13</td><td>Complete logo design </td></tr></table>""
__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 above defined To-do ist items, ""{{structdata req="ToDos"}} would display the following:
===To-do, bugs and limitations===
~- a field can not be multi-line (yet)
~- A possible path of development would be to provide dynamic edition/validation capabilities for data items by embedding a HTML form into the page
===Other considerations===
Deletions:
~~ An error message will indicate failure to validate a given data item. Note that this requires you to provide the corresponding code;
==Examples:==
%%{{structdata type="ToDo" print="false" data="owner='kbill' status='open' desc='Book flight to Lake Tahoe' priority='2' date_open='2006-10-3' "}}%%
~1) no specific visual rendering has been defined. print='table' usually gives good results.
~1) 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.
==Other considerations==


Revision [15736]

Edited on 2006-12-02 19:33:37 by DomBonj [Minor edit]
Additions:
~- A nice feature of this action is that it is possible to freely mix regular wiki page content and structured data items, without any change on the database structure. However, this approach is probably not very scalable in terms of performance of request handling.


Revision [15734]

Edited on 2006-12-02 18:54:28 by DomBonj [Minor edit]
Additions:
~- use a specific visual rendering to format and display only key informations of each data item
Parameters shall be of either of two (exclusive) types:
<tr><td>print</td><td>string</td><td>optional</td><td></td><td>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)</td></tr>
<tr><td>help</td><td>string</td><td>optional</td><td></td><td>If this parameter is present, a one line description of the request and its parameters is displayed</td></tr>
~~ - to make it invisible; or
__Definition of two To-Do list items. The second one will not be displayed__
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.
~1) date existence check is performed for date_open and date_due.
~1) no specific visual rendering has been defined. print='table' usually gives good results.
~1) 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:
~1) one field is mandatory: n, containing the name of the contact, formatted as 'last_name[;given_name[;middle_name[;title]]]')
~1) optional fields are: org (organization), email, tel and fax.
~1) no data validation is performed.
~1) a contact card is rendered as an inline text. Example: ""<a href='mailto:jdoe@his_organization.org' title='phone:(123)-456-7890 / fax: (123) 654-898'>John Doe (His organization)</a>"".
~1) 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 [[http://microformats.org/ 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
Deletions:
~- use a specific visual rendering to display and format only key informations of each data item
Parameters shall be either of two (exclusive) types:
~~ - to make it visible or not; or
__Definition of To-Do list items. The second one will not be displayed__
Comments on the four functions listed above
~1) three fields are mandatory: owner, desc (description of the task), date_open and date_due. Dates shall follow the 'yyyy-mm-dd' format.
~1) date validation is performed
~1) no specific visual rendering has been defined. print='table' usually give good results.
~1) a request called "ToDo" 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 displayed. If parameter p2 is passed, only data items whose status is equal to p2 are displayed.
%%{{{{structdata type="Card" data="n='DOE;John' email='jdoe@himself.org' fax='(+1) 415 696 123' tel='212-898-31321' org='himself'"}}
}}%%
==Design considerations==
Full SQL-style request language with parser
XML
microformats
structured wikis: xwiki and twiki


Revision [15732]

Edited on 2006-12-02 07:17:14 by DomBonj [Minor edit]
Additions:
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 display and format only key informations of each data item
~- call predefined requests (a la SQL) to select and process data items across all wiki pages
This is by essence ''not a turnkey tool'', as you have to define your data items and the request to be performed upon them.
<tr><td>type</td><td>string</td><td>required</td><td></td><td>The data item type. Predefined types are ToDo and Card (see explanation in 'Long description' paragraph below)</td></tr>
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined types are ItemTable, ToDos and Cards (see explanation in 'Long description' paragraph below)</td></tr>
<tr><td>p1</td><td>string</td><td>optional</td><td></td><td>The request's first parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
<tr><td>p2</td><td>string</td><td>optional</td><td></td><td>The request's second parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
<tr><td>p3</td><td>string</td><td>optional</td><td></td><td>The request's third parameter.Typically used to filter or sort, but actual semantics are request-specific</td></tr>
~- if you pass ''both'' a 'type' and a 'req' parameter, the 'req' parameter will be ignored
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?"
~~ An error message will indicate failure to validate a given data item. Note that this requires you to provide the corresponding code;
~1) control the visual rendering of each data item. You can choose:
%%{{structdata (type="datatype" data="fieldslist" [print="printmode"] | req="reqname" [p1="val1"][p2="val2"][p3="val3"] [help]) }}%%
Deletions:
Enables to embed structured (or "semantically tagged", a bit like a database record) data items in a page. You can then use a specific visual rendering, showing only key informations and call predefined requests (a la SQL) to select and process data items across all wiki pages.
This is by essence not a turnkey tool, as you have to define your data items and the request to be performed upon them.
<tr><td>type</td><td>string</td><td>required</td><td></td><td>The data item type. Predefined types are ToDo and Card.</td></tr>
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined types are ItemTable, ToDos and Cards</td></tr>
<tr><td>p1</td><td>string</td><td>optional</td><td></td><td>The request's first parameter.Typically used to filter or sort, but actual semantics are request-dependent</td></tr>
<tr><td>p2</td><td>string</td><td>optional</td><td></td><td>The request's second parameter.Typically used to filter or sort, but actual semantics are request-dependent</td></tr>
<tr><td>p3</td><td>string</td><td>optional</td><td></td><td>The request's third parameter.Typically used to filter or sort, but actual semantics are request-dependent</td></tr>
~- if you pass ''both'' a 'data' and a 'req' parameter, the 'req' parameter will be ignored
Didn't you ''ever'' think: "these wiki are nice, but if only I could somehow 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?"
~~ An error message will indicate failure to validate a given data item. Note this requires you to provide the corresponding code;
~1) control the visual rendering of your data item. You can choose:
%%{{structdata (type="datatype" data="fieldslist" [print="printmode"] | req="reqname" [p1="val1"][p2="val2"][p3="val3"] | help) }}%%


Revision [15731]

Edited on 2006-12-02 07:04:54 by DomBonj [Minor edit]
Additions:
Parameters shall be either of two (exclusive) types:
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionnality and allowed values depend on value of the 'type' parameter</td></tr>
<tr><td>req</td><td>string</td><td>required</td><td></td><td>The request id. Predefined types are ItemTable, ToDos and Cards</td></tr>
<tr><td>p1</td><td>string</td><td>optional</td><td></td><td>The request's first parameter.Typically used to filter or sort, but actual semantics are request-dependent</td></tr>
<tr><td>p2</td><td>string</td><td>optional</td><td></td><td>The request's second parameter.Typically used to filter or sort, but actual semantics are request-dependent</td></tr>
<tr><td>p3</td><td>string</td><td>optional</td><td></td><td>The request's third parameter.Typically used to filter or sort, but actual semantics are request-dependent</td></tr>
__Notes:__
~- if you pass ''both'' a 'data' and a 'req' parameter, the 'req' parameter will be ignored
~1) three fields are mandatory: owner, desc (description of the task), date_open and date_due. Dates shall follow the 'yyyy-mm-dd' format.
%%{{{{structdata type="Card" data="n='DOE;John' email='jdoe@himself.org' fax='(+1) 415 696 123' tel='212-898-31321' org='himself'"}}
Deletions:
Parameters shall be:
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionnality and allowed values depend on vlalue of the 'type' parameter</td></tr>
~1) three fields are mandatory: owner, date_open and date_due. Dates shall follow the 'yyyy-mm-dd' format.
%%{{{{structdata type="Card" data="n='DOE;John' email='jdoe@himself.org' fax='(+1) 415 696 123' tel='212-898-31321' ORG='himself'"}}


Revision [15730]

Edited on 2006-12-02 06:57:19 by DomBonj [Minor edit]
Additions:
XML


Revision [15724]

Edited on 2006-11-30 16:55:37 by DomBonj [Minor edit]
Additions:
DomBonj
Deletions:
Dominique Bonjour


Revision [15723]

Edited on 2006-11-30 16:51:40 by DomBonj [Minor edit]
Additions:
<tr><td>type</td><td>string</td><td>required</td><td></td><td>The data item type. Predefined types are ToDo and Card.</td></tr>
<tr><td>data</td><td>string</td><td>required</td><td></td><td>field1='value1' field2='value2' etc. Optionnality and allowed values depend on vlalue of the 'type' parameter</td></tr>
~1) 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;
~1) validate the list of parameters. You can:
__Definition of To-Do list items. The second one will not be displayed__
Comments on the four functions listed above
~1) three fields are mandatory: owner, date_open and date_due. Dates shall follow the 'yyyy-mm-dd' format.
~1) date validation is performed
~1) no specific visual rendering has been defined. print='table' usually give good results.
~1) a request called "ToDo" 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 displayed. If parameter p2 is passed, only data items whose status is equal to p2 are displayed.
Deletions:
<tr><td>type</td><td>string</td><td>optional</td><td></td><td>The data item type. Predefined types are ToDo and Card.</td></tr>
<tr><td>data</td><td>string</td><td>required if you passed a 'type' parameter</td><td></td><td>field1='value1' field2='value2' etc. Optionnality and allowed values depend on vlalue of the 'type' parameter</td></tr>
~1) embed in any page a "structured data item" which is defiined by a type (e.g. a To-Do list entry) and a (possibly empty) set of parameters (or fields, in the database language). Note that fields are not typed;
~1) validate the content of the parameter. You can:
__Definition of To-Do list items. The second one is not displayed__


Revision [15722]

Edited on 2006-11-30 16:39:04 by DomBonj [Minor edit]
Additions:
=====StructData Action Documentation=====
//Not Included in official Wikka version//
>>==See also:==
Development: StructDataAction.>>This is the documentation page for the structdata action.::c::
Enables to embed structured (or "semantically tagged", a bit like a database record) data items in a page. You can then use a specific visual rendering, showing only key informations and call predefined requests (a la SQL) to select and process data items across all wiki pages.
This is by essence not a turnkey tool, as you have to define your data items and the request to be performed upon them.
Two examples are provided :
~- a "To Do" list
~- a contact card
Parameters shall be:
~- either a pair ('type', 'data'), if you want to define a data item
~- either 'req' with optionnally 'p1', 'p2' and 'p3', if you want to perform a request
<tr><td>type</td><td>string</td><td>optional</td><td></td><td>The data item type. Predefined types are ToDo and Card.</td></tr>
<tr><td>data</td><td>string</td><td>required if you passed a 'type' parameter</td><td></td><td>field1='value1' field2='value2' etc. Optionnality and allowed values depend on vlalue of the 'type' parameter</td></tr>
Didn't you ''ever'' think: "these wiki are nice, but if only I could somehow 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 defiined by a type (e.g. a To-Do list entry) and a (possibly empty) set of parameters (or fields, in the database language). Note that fields are not typed;
~1) validate the content of the parameter. 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 this requires you to provide the corresponding code;
~1) control the visual rendering of your data item. You can choose:
~~ - to make it visible or not; 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.
~1) 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 To-Do list items. The second one is not 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' "}}%%
__Definition of a contact card__
%%{{{{structdata type="Card" data="n='DOE;John' email='jdoe@himself.org' fax='(+1) 415 696 123' tel='212-898-31321' ORG='himself'"}}
}}%%
==Design considerations==
Full SQL-style request language with parser
microformats
structured wikis: xwiki and twiki
Dominique Bonjour
Deletions:
[[WikkaDocumentation Wikka Documentation]]
=====xxxxx Action Documentation=====
//Included in Wikka since version X.X.X.X//
>>**See also**
Development: xxxxxAction.>>This is the documentation page for the xxxxx action.::c::
//This page is a **template**. It belongs to CategoryTemplate (which contains more handy templates). To create an **action documentation** page, [[http://wikka.jsnx.com/ActionInfoTemplate/clone clone this page]] to a page called **xxxxxActionInfo** (where xxxxx is the (capitalized) name of the action), replace all occurrences of 'xxxxx' with the name of the action and replace this paragraph with the actual content.//
__Note__: Please **remove** the "Wikka Documentation" link at the top, the CategoryDocumentation at the bottom and the "included in Wikka" note unless and until the action is part of the official Wikka distribution!
Describe your action in one sentence.
<tr><td>param1</td><td>string</td><td>optional</td><td>your_default</td><td>This is one of the params, your action uses. If yuopr action uses no params, remove this table</td></tr>
//Place for a longer description.//
Usage:
%%{{action_name [optional_param="xxx"]}}%%
Example:
you can put in an example here.
The name(s) of the person(s) who wrote this action.


Revision [15721]

The oldest known version of this page was created on 2006-11-30 15:11:30 by DomBonj [Minor edit]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki