Kromaĵo por strukturitaj datumoj

Tiu kromaĵo ebligas aldoni strukturitajn datumojn al ajna DokuWiki-paĝo. Pensu pri aldonaj nomitaj atributoj. Tiuj atributoj sekve povas esti serĉataj kaj akumulataj. La kromaĵo similas al kromaĵo repository, sed interne ĝi funkcias tute alie.

Tiu kromaĵo bezonas la SQLite-aldonon al PHP! (Devus esti inkludita en PHP5).

Tiu kromaĵo povas esti elŝutata permane aŭ tra la kromaĵ-administrilo de la supre indikita ligilo.

• An error occurred while fetching this feed: http://github.com/feeds/splitbrain/commits/dokuwiki-plugin-data/master

Ekde 2010-03-22 la data-kromaĵo uzas la sqlite-helpkromaĵon. Tial la datumbaza dosierloko kaj ĝia strukturo ŝanĝiĝis. Se vi volas teni vian malnovan datumbazon, faru sekvajn paŝojn antaŭ ol aktualigi la data-kromaĵon:

1. Instalu la sqlite-kromaĵon
2. Movu la dosieron data/cache/dataplugin.sqlite al data/meta/data.sqlite
3. Apliku sekvajn SQL-komandojn al la datumbazo (ekzemple per la administra paĝo de la sqlite-kromaĵo)

   CREATE TABLE opts (opt,val);
   CREATE UNIQUE INDEX idx_opt ON opts(opt);
   INSERT INTO opts VALUES ('dbversion', 1);

4. Aktualigi la data-kromaĵon

Se vi aktualigis la data-kromaĵon antaŭ tiuj paŝoj, malplena data.sqlite kreiĝis kaj vi devas kopii data/cache/dataplugin.sqlite super la ekzistanta data/meta/data.sqlite.

Tiu kromaĵo dependas de multaj partoj, kiuj havas ĉiuj similan sintakson. La sintakso difinas blokon kun diversaj ŝlosil/valor-paroj, kiuj agordas la konduton de la kromaĵa parto.

Tiu parto aldonas strukturitajn datumojn al paĝo. Ĉiuj enmetitaj datumoj estas ligataj al la paĝo. Ni komencu per ekzemplo:

---- dataentry projects ----
type            : web development
volume          : 1 Mrd    # how much do they pay?
employees       : Joe, Jane, Jim
customer_page   : customers:microsoft
deadline_dt     : 2009-08-17
server_pages    : servers:devel01, extern:microsoft
website_url     : http://www.microsoft.com
task_tags       : programming, coding, design, html
----

As you can see the block is defined by hyphens and the word dataentry. You may add additional words after the dataentry keyword. Those will be added as additional CSS classes in the final HTML output and can be queried as %class% later. You can use this for styling how different entry types should be displayed later or limiting aggregation to certain types of pages.

You may use the # character to add comments to the block. Those will be ignored and will neither be displayed nor saved. If you need to enter # as data, escape it with a backslash (\#). If you need a backslash, escape it as well (\\).

Inside the block you see column names and their values. There are a few rules for the column names:

• Use any name you like
• If the name ends with the s character, you may add multiple values separated by commas (like in the employees row). This removes the last s character from the rendered column name. If you want to avoid the multiple value option and keep your column name as is, add an underscore to the end of your name (example: “thickness_ : 1cm”).
• Special types can be added to the name to have the output formatted accordingly. Use an underscore to separate identifier and type. The following types are available currently:
  • dt – a date in the form YYYY-MM-DD, formatted as simple text but the input is checked for correct format
  • page – the entry is treated as Wiki pagename and will be linked in output
  • title – like page, but an additional display title can be given separated by a pipe
  • nspage – like page, but the column name is treated as namespace for the link.
  • url – the value will be treated as external link
  • tag – the values are linked to a page named after the column name, using the value as control filter for a data table
  • mail – the value is checked to contain a valid email address, additional text is used as name that will be linked with the given email address
  • img<num> – the input is assumed to be a image URL or local media id. The optional <num> is the wanted width in pixels to resize the image to (defaults to 40)
  • wiki – render the input as wikitext
  • pageid – the input is the caption for a link to the data entry page
  • when no type is given, it's just treated as simple string
  • new types can be create by using Type Aliases
• When using a type, add the s for multi-values at the very end (like in the server_pages row)

To aggregate the structured data attached to various pages in your wiki this syntax is used. It will display a configurable table with the data you want. The table can be sorted and filtered. Paging is supported as well. And just as with the dataentry, you may add additional words after the datatable keyword. Those will be added as additional CSS classes in the final HTML output. Let's start with an example again:

---- datatable ----
cols    : %pageid%, employees, deadline_dt, volume
headers : Details, Assigned Employees, Deadline, $$$
max     : 10
filter  : type=web development
sort    : ^volume
----

The above config will display a table with all web development projects, the employees assigned to the project, the deadline and the volume. The table will be sorted by the volume and will display a maximum of 10 projects.

The keyword before the colon is a configuration option and the value behind is the actual setting. To make it more fault tolerant often multiple option names are possible. Here is a list of all available options:

For filtering, multiple comparators are possible:

You may use the special word %user% in a filter to make it match against the currently logged in user. To compare with the current date, use the special word %now%.

This syntax will disable all caching for the current page!

There are a few variables available to be used as field names:

The datalist works like the datatable above and accepts the same parameters. But instead of displaying a table, an unordered list is shown. Each result row is one list item, all selected columns are joined with a space. The header parameter is completely ignored. No pagination is used.

---- datalist ----
cols    : %pageid%, volume
max     : 10
filter  : type=web development
sort    : ^volume
----

This mode allows you to display a list of pages which are similar to the current page because they share some of the structured data. Which columns are used for similarity comparison has to be given in the cols option. Additional filters and sorting options can be set. Here is an example:

---- datarelated ----
cols  : task_tags, type
title : Similar projects
max   : 5
sort  : ^volume
----

The shown config will look for pages which share values in the columns task and type. A maximum of 5 pages is shown, sorted by volume.

Refer to datatable on what options are available.

This mode will not disable caching for the page, so the list might not always be up to date.

This syntax will display the values of a given data name as a tag cloud. Each value will link back to the current page (unless configured otherwise). The page should also contain a Data Table - this table will then be filtered for all entries matching the selected tag.

Example:

---- datacloud ----
field: employees
min: 2
limit: 20
----

La supra kodo prezentus nubon de dungitoj, kiuj estas ligitaj al minimume du diversaj projektoj. Maksimume 20 plej okupitaj dungitoj estas montrataj.

Tiuj estas la eblaj opcioj por la nubo:

Aldone eblas indiki filtrilojn, priskribitajn en la datatable-sintakso.

Pozicio kaj dezajno de la enmetaj kaj prezentaj skatoloj povas esti farata pere de simpla CSS. Ĉio post la sintaksa ŝlosilvorto kreos aldonan klasnomon por la ĉirkaŭanta div. Aldone la kampŝlosiloj estas klasoj por la elementoj de la enmeta skatolo.

Ni supozu jenan “dataentry”-skatolon, kiel indikita supre.

---- dataentry character24 ----
name            : Jack Bauer
agency_nspage   : CTU
status_tags     : alive, active, disowned, furtive
.... more info
----

Nun vi povas dezajni la stilon de tiu skatolo pere de CSS en via conf/userstyle.css. Jen ekzemplo:

div.character24 {
  /* kodo por la kontenera bloko, kia pozicio, dezajno kaj bordoj ktp. */
  float: right;
  width: 33%;
}
 
div.character24 dl > dt { 
  /* tio ebligas dezajni la difintermojn */
  font-variant: small-caps;
}
 
div.character24 dl > dt + dd {
  /* tio permesas dezajni la difinajn valorojn */
  font-family: sans-serif;
}
 
div.character24 dl dd.name{
  /* tio pligrandigas la nomon */
  font-size: 120%;
}

Tipkromnomoj estas memkreitaj datumtipoj difinitaj el baza tipo (unu de la kunliveritaj tipoj kiel page aŭ neniu tipo), kaj libervole prefikso, postfikso aŭ komadisigita listo de validaj tipoj. Tipkromnomoj estas administrataj sur propra paĝo en la administra menuo kaj konservataj en la datumbazo. Ili povas esti uzataj en datumenmetoj, listoj kaj tabeloj same kiel la standardaj tipoj.

Ekzemple por krei novan datumtipon map, kiu malfermus Google Maps:

difinu interwiki adresmapon:

map     http://maps.google.com/maps?q=

Kaj en Admin → Page Aliases (do=admin&page=data_aliases) difinu:

kion vi nun povas uzi tiel:

---- dataentry  ----
Address_map  : 51.103028,-1.780611
----

La data.kromaĵo estas la unua kromaĵo, kiu provizas klientan modifilon por ĝiaj datum-enmetoj. Kun aktuala versio de DokuWiki datum-enmetoj havas propran modifo-butonon. Kiam oni premas tiun butonon, la uzanto ricevas formularon por modifi la enhavon de la datum-enmeto aŭ – depende de la agorda opcio edit_content_only – eĉ la strukturon, te. ŝanĝi la kamponomojn, tipon aŭ aldoni kaj forigi kampojn. Kun aktuala bureaucracy-versio ankaŭ haveblas iom da JavaScript-magio por modifi paĝokampojn kaj datentipojn.

• pliaj kontrolopcioj:
  • atributlisto (simile al etikeda nubo, sed kiel simpla listo)
  • serĉkampo
• pli bona dokumentado, ekzemploj
• Aldoni JavaScript-subtenon por la content_only-modifilo ankaŭ al la plena formularo
• ĉu pliaj datumtipoj?
• ligiloj en akumulaĵoj kaj datumenmetoj ne kreas retroligilojn
• serĉi datumojn en specifa nomspaco
• WHERE-testoj kontraŭ datenkampoj bezonas ekvivalenton al SQL INTERVAL (“WHERE field_dt < %now% + INTERVAL 6 MONTH” egalas al “field_dt de antaŭ 6 monatoj ĝis nun”)
• kompari kontraŭ “tiu paĝo”-nomo (en datatable)

Tiu kromaĵo povas esti vidata viva en la ŝablontabelo de tiu vikio. Rigardu la fontotekston por tiu paĝo kaj por selkaj individuaj ŝablonpaĝoj.

La datumoj kopiitaj al la SQLite-datumbazo devus esti aŭtomate aktualigataj, kiam ajn estas ŝanĝata la paĝo, kiu enhavas la dataentry-skatolon.

Tamen povus ekzisti cimoj, kiuj malebligas 100%-an fidindecon. Rigardu ĉe la malfermaj cimoj-sekcio kaj ŝanĝoj por vidi, kio povus esti difekta aŭ kio estis riparita antaŭ nelonge.

Kiam vi forigas la tutan datenbazon, ĉiuj entry-paĝoj devas esti revizitataj por replenigi la datumbazon. Ne ekzistas aŭtomata maniero fari tiel.

Se la paĝo estis modifita deekstere, aŭ estas freŝa datumbazo, unu truko aktualigi la datenbazon estas elŝuti la vikiajn paĝojn amase, uzante ekz. wget (komandlinia dosier-elŝutilo). Ekzemple: wget http://myserver/wiki/doku.php/document;presentation;37.

Kompreneble vi povas malfermi la datumbazon rekte per SQLite-komandlinia kliento kaj manipuli ĝin tra SQLite-komandoj.

Vi ne povas havi plurajn dataentry-skatolojn sur la sama paĝo, almenaŭ ne kun la sama strukturo.

La paĝidentigilo estas la primara ŝlosilo por identigi datumaron. El vidpunkto de la datumbazo ne estus diferenco inter la datenoj de diversaj skatoloj. Postaj datumoj superskribus simple pli frue menciitajn datumojn.

Via linuksa distribuo eble provizas la SQLite-PHP-aldonon en aparta pakaĵo de PHP. Ekz. Debian-sistemo listigas jenajn haveblajn pakaĵojn: php-sqlite, php-sqlite3, php5-sqlite, php5-sqlite3 – se vi uzas la php5-pakaĵon por PHP, vi devus instali la php5-sqlite-pakaĵon.

Se vi ankoraŭ havas demandojn, serĉu en la forumo - kaj se via demando ankoraŭ ne estis metita tie, demandu tie.

Bonvolu anonci cimojn kaj funkcipetojn en la temsekvilo indikita supre. Flikaĵoj devus esti sendataj en unuigita diff-formato aŭ kiel git-flikaĵoj kontraŭ la devl-branĉo. Aŭ eĉ pli bone: disbranĉigu la kodaron ĉe github kaj sendu kuniĝpeton.