]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blob - doc/todo/structured_page_data.mdwn
response
[git.ikiwiki.info.git] / doc / todo / structured_page_data.mdwn
1 This is an idea from [[JoshTriplett]].  --[[Joey]]
3 Some uses of ikiwiki, such as for a bug-tracking system (BTS), move a bit away from the wiki end
4 of the spectrum, and toward storing structured data about a page or instead
5 of a page. 
7 For example, in a bug report you might want to choose a severity from a
8 list, enter a version number, and have a bug submitter or owner recorded,
9 etc. When editing online, it would be nice if these were separate fields on
10 the form, rather than the data being edited in the big edit form.
12 There's a tension here between remaining a wiki with human-editable source
13 files, containing freeform markup, and more structured data storage. I
14 think that it would be best to include the structured data in the page,
15 using a directive. Something like:
17         part of page content
18         \[[data yaml="<arbitrary yaml here>"]]
19         rest of page content 
21 As long as the position of the directive is not significant, it could be
22 stripped out when web editing, the yaml used to generate/populate form fields, 
23 and then on save, the directive regenerated and inserted at top/bottom of
24 the page.
26 Josh thinks that yaml is probably a good choice, but the source could be a
27 `.yaml` file that contains no directives, and just yaml. An addition
28 complication in this scenario is, if the yaml included wiki page formatted content,
29 ikiwiki would have to guess or be told what markup language it used.
31 Either way, the yaml on the page would encode fields and their current content.
32 Information about data types would be encoded elsewhere, probably on a
33 parent page (using a separate directive). That way, all child pages could
34 be forced to have the same fields.
36 There would be some simple types like select, boolean, multiselect, string, wiki markup.
37 Probably lists of these (ie, list of strings). Possibly more complex data
38 structures.
40 It should also be possible for plugins to define new types, and the type
41 definitions should include validation of entered data, and how to prompt
42 the user for the data.
44 This seems conceptually straightforward, if possibly quite internally
45 complex to handle the more complicated types and validation.
47 One implementation wrinkle is how to build the html form. The editpage.tmpl
48 currently overrides the standard [[!cpan CGI::FormBuilder]] generated form,
49 which was done to make the edit page be laid out in a nice way. This,
50 however, means that new fields cannot be easily added to it using
51 [[!cpan CGI::FormBuilder]]. The attachment plugin uses the hack of bouilding
52 up html by hand and dumping it into the form via a template variable. 
54 It would be nice if the type implementation code could just use
55 FormBuilder, since its automatic form generation, and nice field validation
56 model is a perfect match for structured data. But this problem with
57 editpage.tmpl would have to be sorted out to allow that.
59 Additional tie-ins:
61 * Pagespecs that can select pages with a field with a given value, etc.
62   This should use a pagespec function like field(fieldname, value).  The
63   semantics of this will depend on the type of the field; text fields will
64   match value against the text, and link fields will check for a link
65   matching the pagespec value.
66 * The search plugin could allow searching for specific fields with specific
67   content. (xapian term search is a good fit).
69 See also:
71 [[tracking_bugs_with_dependencies]]
73 > I was also thinking about this for bug tracking.  I'm not sure what
74 > sort of structured data is wanted in a page, so I decided to brainstorm
75 > use cases:
76 >
77 > * You just want the page to be pretty.
78 > * You want to access the data from another page.  This would be almost like
79 >     like a database lookup, or the OpenOffice Calc [VLookup](http://wiki.services.openoffice.org/wiki/Documentation/How_Tos/Calc:_VLOOKUP_function) function.
80 > * You want to make a pagespec depend upon the data.  This could be used
81 >    for dependancy tracking - you could match against pages listed as dependencies,
82 >    rather than all pages linked from a given page.
83 >
84 >The first use case is handled by having a template in the page creation.  You could
85 >have some type of form to edit the data, but that's just sugar on top of the template.
86 >If you were going to have a web form to edit the data, I can imagine a few ways to do it:
87 >
88 > * Have a special page type which gets compiled into the form.  The page type would
89 >    need to define the form as well as hold the stored data.
90 > * Have special directives that allow you to insert form elements into a normal page.
91 >
92 >I'm happy with template based page creation as a first pass...
93 >
94 >The second use case could be handled by a regular expression directive. eg:
95 >
96 > \[[regex spec="myBug" regex="Depends: ([^\s]+)"]]
97 >
98 > The directive would be replaced with the match from the regex on the 'myBug' page... or something.
99 >
100 >The third use case requires a pagespec function.  One that matched a regex in the page might work.
101 >Otherwise, another option would be to annotate links with a type, and then check the type of links in
102 >a pagespec.  e.g. you could have `depends` links and normal links.
104 >Anyway, I just wanted to list the thoughts.  In none of these use cases is straight yaml or json the
105 >obvious answer.  -- [[Will]]
107 >> Okie.  I've had a play with this.  A 'form' plugin is included inline below, but it is only a rough first pass to
108 >> get a feel for the design space.
109 >>
110 >> The current design defines a new type of page - a 'form'.  The type of page holds YAML data
111 >> defining a FormBuilder form.  For example, if we add a file to the wiki source `test.form`:
113     ---
114     fields:
115       age:
116         comment: This is a test
117         validate: INT
118         value: 15
120 >> The YAML content is a series of nested hashes.  The outer hash is currently checked for two keys:
121 >> 'template', which specifies a parameter to pass to the FromBuilder as the template for the
122 >> form, and 'fields', which specifies the data for the fields on the form.
123 >> each 'field' is itself a hash.  The keys and values are arguments to the formbuilder form method.
124 >> The most important one is 'value', which specifies the value of that field.
125 >>
126 >> Using this, the plugin below can output a form when asked to generate HTML.  The Formbuilder
127 >> arguments are sanitized (need a thorough security audit here - I'm sure I've missed a bunch of
128 >> holes).  The form is generated with default values as supplied in the YAML data.  It also has an
129 >> 'Update Form' button at the bottom.
130 >>
131 >>  The 'Update Form' button in the generated HTML submits changed values back to IkiWiki.  The
132 >> plugin captures these new values, updates the YAML and writes it out again.  The form is
133 >> validated when edited using this method.  This method can only edit the values in the form.
134 >> You cannot add new fields this way.
135 >>
136 >> It is still possible to edit the YAML directly using the 'edit' button.  This allows adding new fields
137 >> to the form, or adding other formbuilder data to change how the form is displayed.
138 >>
139 >> One final part of the plugin is a new pagespec function.  `form_eq()` is a pagespec function that
140 >> takes two arguments (separated by a ',').  The first argument is a field name, the second argument
141 >> a value for that field.  The function matches forms (and not other page types) where the named
142 >> field exists and holds the value given in the second argument.  For example:
143     
144     \[[!inline pages="form_eq(age,15)" archive="yes"]]
145     
146 >> will include a link to the page generated above.
148 >>> Okie, I've just made another plugin to try and do things in a different way.
149 >>> This approach adds a 'data' directive.  There are two arguments, `key` and `value`.
150 >>> The directive is replaced by the value.  There is also a match function, which is similar
151 >>> to the one above.  It also takes two arguments, a key and a value.  It returns true if the
152 >>> page has that key/value pair in a data directive.  e.g.:
154     \[[!data key="age" value="15"]]
156 >>> then, in another page:
158     \[[!inline pages="data_eq(age,15)" archive="yes"]]
160 >>> I expect that we could have more match functions for each type of structured data,
161 >>> I just wanted to implement a rough prototype to get a feel for how it behaves.  -- [[Will]]
163 >> Anyway, here are the plugins.  As noted above these are only preliminary, exploratory, attempts. -- [[Will]]
165 >>>> I've just updated the second of the two patches below.  The two patches are not mutually
166 >>>> exclusive, but I'm leaning towards the second as more useful (for the things I'm doing). -- [[Will]]
168 I think it's awesome that you're writing this code to explore the problem
169 space, [[Will]] -- and these plugins are good stabs at at least part of it.
170 Let me respond to a few of your comments.. --[[Joey]]
172 On use cases, one use case is a user posting a bug report with structured
173 data in it. A template is one way, but then the user has to deal with the
174 format used to store the structured data. This is where a edit-time form
175 becomes essential.
177 > This was the idea with the 'form' plugin.  With the 'data' plugin I was exploring
178 > a different approach: try to keep the markup simple enough that the user can edit
179 > the markup directly, and still have that be ok.  I admit it is a stretch, but I thought
180 > it worth exploring.
182 Another use case is, after many such bugs have been filed,
183 wanting to add a new field to each bug report. To avoid needing to edit
184 every bug report it would be good if the fields in a bug report were
185 defined somewhere else, so that just that one place can be edited to add
186 the new field, and it will show up in each bug report (and in each bug
187 report's edit page, as a new form field).
189 > If I was going to do that, I'd use a perl script on a checked out
190 > workspace.  I think you're describing a rare operation and
191 > so I'd be happy not having a web interface for it.  Having said that,
192 > if you just wanted to change the form for *new* pages, then you
193 > can just edit the template used to create new pages.
195 Re the form plugin, I'm uncomfortable with tying things into
196 [[!cpan CGI::FormBuilder]] quite so tightly as you have.
198 > Yeah :).  But I wanted to explore the space and that was the
199 > easiest way to start.
201 CGI::FormBuilder
202 could easily change in a way that broke whole wikis full of pages. Also,
203 needing to sanitize FormBuilder fields with security implications is asking
204 for trouble, since new FormBuilder features could add new fields, or
205 add new features to existing fields (FormBuilder is very DWIM) that open
206 new security holes. 
208 > There is a list of allowed fields.  I only interpret those.
210 I think that having a type system, that allows defining specific types,
211 like "email address", by writing code (that in turn can use FormBuilder),
212 is a better approach, since it should avoid becoming a security problem.
214 > That would be possible.  I think an extension to the 'data' plugin might
215 > work here.
217 One specific security hole, BTW, is that if you allow the `validate` field,
218 FormBuilder will happily treat it as a regexp, and we don't want to expose
219 arbitrary perl regexps, since they can at least DOS a system, and can
220 probably be used to run arbitrary perl code.
222 > I validate the validate field :).  It only allows validate fields that match
223 > `/^[\w\s]+$/`.  This means you can really only use the pre-defined
224 > validation types in FormBuilder.
226 The data plugin only deals with a fairly small corner of the problem space,
227 but I think does a nice job at what it does. And could probably be useful
228 in a large number of other cases.
230 > I think the data plugin is more likely to be useful than the form plugin.
231 > I was thinking of extending the data directive by allowing an 'id' parameter.
232 > When you have an id parameter, then you can display a small form for that
233 > data element.  The submission handler would look through the page source
234 > for the data directive with the right id parameter and edit it.  This would
235 > make the data directive more like the current 'form' plugin.
237 > That is making things significantly more complex for less significant gain though. --[[Will]]
239 > Oh, one quick other note.  The data plugin below was designed to handle multiple
240 > data elements in a single directive.  e.g.
242     \[[!data key="Depends on" link="bugs/bugA" link="bugs/bugB" value=6]]
244 > would match `data_eq(Depends on,6)`, `data_link(Depends on,bugs/bugA)`, `data_link(Depends on,bugs/bugB)`
245 > or, if you applied the patch in [[todo/tracking_bugs_with_dependencies]] then you can use 'defined pagespecs'
246 > such as `data_link(Depends on,~openBugs)`.  The ability to label links like this allows separation of
247 > dependencies between bugs from arbitrary links.
249 ----
251     #!/usr/bin/perl
252     # Interpret YAML data to make a web form
253     package IkiWiki::Plugin::form;
254     
255     use warnings;
256     use strict;
257     use CGI::FormBuilder;
258     use IkiWiki 2.00;
259     
260     sub import { #{{{
261         hook(type => "getsetup", id => "form", call => \&getsetup);
262         hook(type => "htmlize", id => "form", call => \&htmlize);
263         hook(type => "sessioncgi", id => "form", call => \&cgi_submit);
264     } # }}}
265     
266     sub getsetup () { #{{{
267         return
268                 plugin => {
269                         safe => 1,
270                         rebuild => 1, # format plugin
271                 },
272     } #}}}
273     
274     sub makeFormFromYAML ($$$) { #{{{
275         my $page = shift;
276         my $YAMLString = shift;
277         my $q = shift;
278     
279         eval q{use YAML};
280         error($@) if $@;
281         eval q{use CGI::FormBuilder};
282         error($@) if $@;
283         
284         my ($dataHashRef) = YAML::Load($YAMLString);
285         
286         my @fields = keys %{ $dataHashRef->{fields} };
287         
288         unshift(@fields, 'do');
289         unshift(@fields, 'page');
290         unshift(@fields, 'rcsinfo');
291         
292         # print STDERR "Fields: @fields\n";
293         
294         my $submittedPage;
295         
296         $submittedPage = $q->param('page') if defined $q;
297         
298         if (defined $q && defined $submittedPage && ! ($submittedPage eq $page)) {
299                 error("Submitted page doensn't match current page: $page, $submittedPage");
300         }
301         
302         error("Page not backed by file") unless defined $pagesources{$page};
303         my $file = $pagesources{$page};
304         
305         my $template;
306         
307         if (defined $dataHashRef->{template}) {
308                 $template = $dataHashRef->{template};
309         } else {
310                 $template = "form.tmpl";
311         }
312         
313         my $form = CGI::FormBuilder->new(
314                 fields => \@fields,
315                 charset => "utf-8",
316                 method => 'POST',
317                 required => [qw{page}],
318                 params => $q,
319                 action => $config{cgiurl},
320                 template => scalar IkiWiki::template_params($template),
321                 wikiname => $config{wikiname},
322                 header => 0,
323                 javascript => 0,
324                 keepextras => 0,
325                 title => $page,
326         );
327         
328         $form->field(name => 'do', value => 'Update Form', required => 1, force => 1, type => 'hidden');
329         $form->field(name => 'page', value => $page, required => 1, force => 1, type => 'hidden');
330         $form->field(name => 'rcsinfo', value => IkiWiki::rcs_prepedit($file), required => 1, force => 0, type => 'hidden');
331         
332         my %validkey;
333         foreach my $x (qw{label type multiple value fieldset growable message other required validate cleanopts columns comment disabled linebreaks class}) {
334                 $validkey{$x} = 1;
335         }
336     
337         while ( my ($name, $data) = each(%{ $dataHashRef->{fields} }) ) {
338                 next if $name eq 'page';
339                 next if $name eq 'rcsinfo';
340                 
341                 while ( my ($key, $value) = each(%{ $data }) ) {
342                         next unless $validkey{$key};
343                         next if $key eq 'validate' && !($value =~ /^[\w\s]+$/);
344                 
345                         # print STDERR "Adding to field $name: $key => $value\n";
346                         $form->field(name => $name, $key => $value);
347                 }
348         }
349         
350         # IkiWiki::decode_form_utf8($form);
351         
352         return $form;
353     } #}}}
354     
355     sub htmlize (@) { #{{{
356         my %params=@_;
357         my $content = $params{content};
358         my $page = $params{page};
359     
360         my $form = makeFormFromYAML($page, $content, undef);
361     
362         return $form->render(submit => 'Update Form');
363     } # }}}
364     
365     sub cgi_submit ($$) { #{{{
366         my $q=shift;
367         my $session=shift;
368         
369         my $do=$q->param('do');
370         return unless $do eq 'Update Form';
371         IkiWiki::decode_cgi_utf8($q);
372     
373         eval q{use YAML};
374         error($@) if $@;
375         eval q{use CGI::FormBuilder};
376         error($@) if $@;
377         
378         my $page = $q->param('page');
379         
380         return unless exists $pagesources{$page};
381         
382         return unless $pagesources{$page} =~ m/\.form$/ ;
383         
384         return unless IkiWiki::check_canedit($page, $q, $session);
385     
386         my $file = $pagesources{$page};
387         my $YAMLString = readfile(IkiWiki::srcfile($file));
388         my $form = makeFormFromYAML($page, $YAMLString, $q);
389     
390         my ($dataHashRef) = YAML::Load($YAMLString);
391     
392         if ($form->submitted eq 'Update Form' && $form->validate) {
393                 
394                 #first update our data structure
395                 
396                 while ( my ($name, $data) = each(%{ $dataHashRef->{fields} }) ) {
397                         next if $name eq 'page';
398                         next if $name eq 'rcs-data';
399                         
400                         if (defined $q->param($name)) {
401                                 $data->{value} = $q->param($name);
402                         }
403                 }
404                 
405                 # now write / commit the data
406                 
407                 writefile($file, $config{srcdir}, YAML::Dump($dataHashRef));
408     
409                 my $message = "Web form submission";
410     
411                 IkiWiki::disable_commit_hook();
412                 my $conflict=IkiWiki::rcs_commit($file, $message,
413                         $form->field("rcsinfo"),
414                         $session->param("name"), $ENV{REMOTE_ADDR});
415                 IkiWiki::enable_commit_hook();
416                 IkiWiki::rcs_update();
417     
418                 require IkiWiki::Render;
419                 IkiWiki::refresh();
420     
421                 IkiWiki::redirect($q, "$config{url}/".htmlpage($page)."?updated");
422     
423         } else {
424                 error("Invalid data!");
425         }
426     
427         exit;
428     } #}}}
429     
430     package IkiWiki::PageSpec;
431     
432     sub match_form_eq ($$;@) { #{{{
433         my $page=shift;
434         my $argSet=shift;
435         my @args=split(/,/, $argSet);
436         my $field=shift @args;
437         my $value=shift @args;
438     
439         my $file = $IkiWiki::pagesources{$page};
440         
441         if ($file !~ m/\.form$/) {
442                 return IkiWiki::FailReason->new("page is not a form");
443         }
444         
445         my $YAMLString = IkiWiki::readfile(IkiWiki::srcfile($file));
446     
447         eval q{use YAML};
448         error($@) if $@;
449     
450         my ($dataHashRef) = YAML::Load($YAMLString);
451     
452         if (! defined $dataHashRef->{fields}->{$field}) {
453                 return IkiWiki::FailReason->new("field '$field' not defined in page");
454         }
455     
456         my $formVal = $dataHashRef->{fields}->{$field}->{value};
457     
458         if ($formVal eq $value) {
459                 return IkiWiki::SuccessReason->new("field value matches");
460         } else {
461                 return IkiWiki::FailReason->new("field value does not match");
462         }
463     } #}}}
464     
465     1
467 ----
469     #!/usr/bin/perl
470     # Allow data embedded in a page to be checked for
471     package IkiWiki::Plugin::data;
472     
473     use warnings;
474     use strict;
475     use IkiWiki 2.00;
476     
477     my $inTable = 0;
478     
479     sub import { #{{{
480         hook(type => "getsetup", id => "data", call => \&getsetup);
481         hook(type => "needsbuild", id => "data", call => \&needsbuild);
482         hook(type => "preprocess", id => "data", call => \&preprocess, scan => 1);
483         hook(type => "preprocess", id => "datatable", call => \&preprocess_table, scan => 1);   # does this need scan?
484     } # }}}
485     
486     sub getsetup () { #{{{
487         return
488                 plugin => {
489                         safe => 1,
490                         rebuild => 1, # format plugin
491                 },
492     } #}}}
493     
494     sub needsbuild (@) { #{{{
495         my $needsbuild=shift;
496         foreach my $page (keys %pagestate) {
497                 if (exists $pagestate{$page}{data}) {
498                         if (exists $pagesources{$page} &&
499                             grep { $_ eq $pagesources{$page} } @$needsbuild) {
500                                 # remove state, it will be re-added
501                                 # if the preprocessor directive is still
502                                 # there during the rebuild
503                                 delete $pagestate{$page}{data};
504                         }
505                 }
506         }
507     }
508     
509     sub preprocess (@) { #{{{
510         my @argslist = @_;
511         my %params=@argslist;
512         
513         my $html = '';
514         my $class = defined $params{class}
515                         ? 'class="'.$params{class}.'"'
516                         : '';
517         
518         if ($inTable) {
519                 $html = "<th $class >$params{key}:</th><td $class >";
520         } else {
521                 $html = "<span $class >$params{key}:";
522         }
523         
524         while (scalar(@argslist) > 1) {
525                 my $type = shift @argslist;
526                 my $data = shift @argslist;
527                 if ($type eq 'link') {
528                         # store links raw
529                         $pagestate{$params{page}}{data}{$params{key}}{link}{$data} = 1;
530                         my $link=IkiWiki::linkpage($data);
531                         add_depends($params{page}, $link);
532                         $html .= ' ' . htmllink($params{page}, $params{destpage}, $link);
533                 } elsif ($type eq 'data') {
534                         $data = IkiWiki::preprocess($params{page}, $params{destpage}, 
535                                 IkiWiki::filter($params{page}, $params{destpage}, $data));
536                         $html .= ' ' . $data;
537                         # store data after processing - allows pagecounts to be stored, etc.
538                         $pagestate{$params{page}}{data}{$params{key}}{data}{$data} = 1;
539                 }
540         }
541                 
542         if ($inTable) {
543                 $html .= "</td>";
544         } else {
545                 $html .= "</span>";
546         }
547         
548         return $html;
549     } # }}}
550     
551     sub preprocess_table (@) { #{{{
552         my %params=@_;
553     
554         my @lines;
555         push @lines, defined $params{class}
556                         ? "<table class=\"".$params{class}.'">'
557                         : '<table>';
558     
559         $inTable = 1;
560     
561         foreach my $line (split(/\n/, $params{datalist})) {
562                 push @lines, "<tr>" . IkiWiki::preprocess($params{page}, $params{destpage}, 
563                         IkiWiki::filter($params{page}, $params{destpage}, $line)) . "</tr>";
564         }
565     
566         $inTable = 0;
567     
568         push @lines, '</table>';
569     
570         return join("\n", @lines);
571     } #}}}
572     
573     package IkiWiki::PageSpec;
574     
575     sub match_data_eq ($$;@) { #{{{
576         my $page=shift;
577         my $argSet=shift;
578         my @args=split(/,/, $argSet);
579         my $key=shift @args;
580         my $value=shift @args;
581     
582         if (! exists $IkiWiki::pagestate{$page}{data}) {
583                 return IkiWiki::FailReason->new("page does not contain any data directives");
584         }
585         
586         if (! exists $IkiWiki::pagestate{$page}{data}{$key}) {
587                 return IkiWiki::FailReason->new("page does not contain data key '$key'");
588         }
589         
590         if ($IkiWiki::pagestate{$page}{data}{$key}{data}{$value}) {
591                 return IkiWiki::SuccessReason->new("value matches");
592         } else {
593                 return IkiWiki::FailReason->new("value does not match");
594         }
595     } #}}}
596     
597     sub match_data_link ($$;@) { #{{{
598         my $page=shift;
599         my $argSet=shift;
600         my @params=@_;
601         my @args=split(/,/, $argSet);
602         my $key=shift @args;
603         my $value=shift @args;
604     
605         if (! exists $IkiWiki::pagestate{$page}{data}) {
606                 return IkiWiki::FailReason->new("page $page does not contain any data directives and so cannot match a link");
607         }
608         
609         if (! exists $IkiWiki::pagestate{$page}{data}{$key}) {
610                 return IkiWiki::FailReason->new("page $page does not contain data key '$key'");
611         }
612         
613         foreach my $link (keys %{ $IkiWiki::pagestate{$page}{data}{$key}{link} }) {
614                 # print STDERR "Checking if $link matches glob $value\n";
615                 if (match_glob($link, $value, @params)) {
616                         return IkiWiki::SuccessReason->new("Data link on page $page with key $key matches glob $value: $link");
617                 }
618         }
619     
620         return IkiWiki::FailReason->new("No data link on page $page with key $key matches glob $value");
621     } #}}}
622     
623     1