====== pagemod plugin ======

===== Overview =====

I created [[doku>plugin:pagemod|this plugin]] because I have long wished for a way to add data structured in a specific way to a page in a repetitive fashion.  A clear example of this is adding data to a table.  How about a form on that page which could ask the right questions and when submitted add the information submitted as an additional row at the end of the table.

When I saw the [[doku>plugin:bureaucracy]] plugin I knew it could be done and the way that plugin is written lends itself well to extension and so here it is and it works loosely in the following way:

  * A form exists on a page (created by the [[doku>plugin:bureaucracy]] plugin), this can be the page to be modified or it can be another page.
  * A results placeholder sits on a page, this placeholder is enclosed by the **pagemod** tags
  * The form is filled in and submitted inline with the [[doku>plugin:bureaucracy]] requirements and the pagemod action rewrites the target page, replacing the placeholders with the output of parsing.  It then adds another placeholder, so that you can continue to add to the page.

That's really the functionality, its quite simple.

So here are the features:

  * The form and the target can be the same page or different pages (i.e. a page can update itself or another page).
  * Each **pagemod** enclosure has an id, so multiple forms can be used to update different parts of a page.
  * The form can update multiple sections of a page.  That is there can be multiple **pagemod** enclosures with different parts of the data in each, it will parse all of them as long as they have the same **id** as the submitting form.
  * A person can update page that they **don't** have write access to.  Only read access is required to modify a page via the form.  This is not a bug, its a feature.  It means you can prevent people from modifying a page unless they do it via a form.
    * If want people to only have access to read the resultant page, but not change it, protect the **form** page.
    * If you don't want people to have access to read the resultant page, deny them read access, then the form will also not work for them.
      * FIXME (Does this mean they still have access to the form, but it generates an error when they try to use it?)

That's it.

===== Usage =====

==== Examples ====

Example Files can be found here:

  * http://freecode.baselineit.net/dokuwiki/pagemod-namespace.tar.bz2


==== Form Syntax ====

Defining a form is done via the [[doku>plugin:bureaucracy]] plugin, please check that for complete syntax.  But here are the changes:
<code>
<form>
action pagemod <target page/namespace> <pagemod_id>

<...various fields for submit...>
submit
</form>
</code>

To make bureaucracy use the pagemod action, you need to add **action pagemod** with the following parameters:

  * target : This is a page id which can include a namespace, so pagemod:same_page or whatever. **Since 2009/10/12 release :** You can use the special target **_self** to denote the same page as the enclosure.
  * pagemod_id : This is to identify which pagemod enclosures to translate

==== Template Syntax ====

Defining a pagemod template is done within a page with the following code:
<code>
<pagemod <pagemod_id> <params>>
wiki text while will be parsed for transform tags like @@field from form@@ or ##field2 from form##

the contents of this section are invisible and will not show up on this page.
</pagemod>

some other wiki text 

then some more

^ table header 1 ^ table header 2 ^
<pagemod table_adder output_before>| @@table value 1@@ | @@table value 2@@ |
</pagemod>
</code>

The pagemod enclosure starts with:
<code>
<pagemod <pagemod_id> <params>>
</code>
where the following is true:

  * pagemod_id : This is the id of the pagemod.  The form has an pagemod_id, it will modify all the pagemod enclosures with the same id.
  * params : params are separated by , and can be one of the following:
    * output_after : indicates that the output of the translation must come after the rewrite of the pagemod enclosure, the default is to output before the rewrite
    * output_before : this is the default behaviour, to output the translation before the rewrite of the pagemod enclosure

The pagemod enclosure ends with the following:

</pagemod>

and the contents are not shown when the wiki page is viewed.  Translation of the contents of the pagemod enclosure is done inline with the [[plugin:bureaucracy]] plugin's template function.

** Since release 2009/10/12 ** There also exists the concept of meta variables, they are variables that are generated by the plugin at runtime.  They are the following

  * **@@meta.date@@** : The current date in dd/mm/yyyy
  * **@@meta.datetime@@** : The current datetime according to ISO 8601
  * **@@meta.date.format.//format//@@** : The current date in the format you specify.  This format is the one used by the PHP date() function found [[http://www.php.net/manual/en/function.date.php|here]] (e.g. @@meta.date.format.d/m/Y@@ will achieve the same as @@meta.date@@)
  * **@@meta.user.id@@** : The user who submitted the form's username
  * **@@meta.user.mail@@** : The users email address (if we know it)
  * **@@meta.user.name@@** : The users full name (if we know it)
  * **@@meta.page.id@@** : The full id of the page
  * **@@meta.page.name@@** : The name of the page
  * **@@meta.page.namespace@@** : The namespace of the page

New meta information tag requests should be sent to me for implementation.

> 2010-03-20 I added a auto-increment meta tag to your plugin. I needed it for a bug tracker/feature request system. If you're interested, I'll send it to you. Just send me an email to laplix¢2010¢at$gmail$dot¢com (remove the money symbols). It is not fully tested yet (right now, I only tested it with _self) but it does what I want, so...
>>Sounds like a useful addition.. Could you share your code here?? Cheers!
===== Conclusion =====

Please let me know of any bugs or issues, requests.  I know a large number of people have requested a plugin like this, so I hope people find it useful.

===== Feedback =====

==== Non-editable runtime values (ADDED 2009-10-12) ====

We're using this plugin to log activity reports so I required the feature to include some non-editable runtime values like current date and user attributes in pagemod's output. I've done it this way:
<code diff>
13a14
>         global $INFO;
32a34,41
>         $patterns[] = '/(@@|##)@DATE@(@@|##)/';
>         $values[]   = strftime($conf['dformat']);
>         $patterns[] = '/(@@|##)@USER@(@@|##)/';
>         $values[]   = $_SERVER['REMOTE_USER'];
>         $patterns[] = '/(@@|##)@NAME@(@@|##)/';
>         $values[]   = $INFO['userinfo']['name'];
>         $patterns[] = '/(@@|##)@MAIL@(@@|##)/';
>         $values[]   = $INFO['userinfo']['mail'];
</code>
I've no experience in PHP so maybe this solution isn't optimal but it does work :-)  --- [[lost@infidel.name|Dmitry Rubinstain]].

** From Author : This is now possible using the meta tags described in the documentation above **

==== Autodetect current page id (ADDED 2009-10-12) ====

This plugin rocks ! IMHO, it provides such great features that it should be advertised on the front page. I'm planning to use it as a commenting system. Would it be possible to auto-detect the current page id (like the [[doku>plugin:backlinks2]] plugin does) ? For example : 

  <form>
  action pagemod auto new_comment
  fieldset "Add your comments below"
  textbox  "Name"
  select   "Rate it" "Excellent|Good|Bad"
  textarea "Comment"
  submit
  </form>

It would save an incredible amount of time when you have to insert forms in many pages ! --- //Laynee 2009/10/05 16:22//

** From Author : This is now possible using the _self target described in the documentation above **

Woohooh! The new version works like a charm ! Thank you very much :) --- //Laynee 2009/10/12 16:00//

==== Minimalistic Guestbook ====
I used this plugin for a minimalistic guestbook. Although my wiki can be edited by everyone, I think visitors would be more willing to leave a message through a little form. See http://windhoff.net/wiki/playground/playground how it works. An javascript based alternative to this is the [[plugin:disqus|plugin:disqus]].
<file>
====== Guestbook ======
===== New Comment =====
<form>
action pagemod _self add_comment
fieldset "Write new comment"
textbox  "Name" /^((?!<\/nowiki>).)*$/
email "Email (optional)" /^((?!<\/nowiki>).)*$/ !
textarea "Comment" /^((?!<\/nowiki>).|\n)*$/
submit
</form>

===== Comments =====
<pagemod add_comment output_after>
//@@meta.date.format.r@@://
^<nowiki>@@Name@@</nowiki> |<nowiki>@@Email (optional)@@</nowiki>|
|<nowiki>@@Comment@@</nowiki> ||
</pagemod>
</file>
 --- //M. 2010/04/02 03:17//

===== Fixed Bugs (And won't/can't fix) =====

==== Error message in combination with bureaucracy plugin ====

Hi, I installed pagemod together with the bureaucracy plugin, but I can't get them to work. After submitting data through a bureaucracy form (e.g. the demo-page) I receive the following error:

  Fatal error: Class 'syntax_plugin_bureaucracy_actions' not found in /lib/plugins/bureaucracy/actions/pagemod.php on line 7

What am I doing wrong? I tried this on DokuWiki 2009-12-25c as well as on older versions, with same error.

>I've updated my installation to DokuWiki 2009-12-25c, Pagemod 2009-10-12 and Bureaucracy 2010-01-22. I now encounter the same error. I guess Pagemod needs to be updated to work with the latest versions of Bureaucracy. I reinstalled my old version of Bureaucracy (it should be [[http://github.com/splitbrain/dokuwiki-plugin-bureaucracy/tree/e0a32b67327e54a95f20390e7cdb8d1854ca1230|this one]]) and now it works --- //Laynee 2010/02/03 18:03//

>Replace in the file bureaucracy/actions/pagemod.php from line 32 to 40 with that 
<code>
        // run through fields and prepare replacements
        foreach($data as $opt) {
            $label = preg_quote($opt->getParam('label'));
	        $value = $opt->getParam('value'); 
            if(in_array($opt->getParam('cmd'),$this->nofield)) continue;
	        $label = preg_replace('/([\/\.])/','\\\$1',$label);
            $patterns[] = '/(@@|##)'.$label.'(@@|##)/i';
            $values[]   = $value;
        }

</code> --- // Rdemont 2010/02/19 //

>> I tried both solutions above, but still remain with the same error. Something else I might be missing? --- // LWolf 2010/02/25 //

>> Its a type syntax_plugin_bureaucracy_actions needs to be replaced by syntax_plugin_bureaucracy_action. At least, this worked for me --- //Gerione 2010/3/4//

>> I have the same big problem ! Help me please :-( --- //[[philippe@lapeyrie.fr|Ph LAPEYRIE]] 2010/03/16 23:25//

>> **THE SOLUTION** = //Rdemont// + //Gerione//. It's all right for me. LOL --- //[[philippe@lapeyrie.fr|Ph LAPEYRIE]] 2010/03/16 23:51//

** From Author : Fixed, now working with the new bureacracy, thanks for the help. **

==== Multiple forms on one page (RESOLVED) ====

Multiple forms + pagemod sections on one page (and not only, read more) do not work.

**Scenario 1**: I have one page (name it: ''materials'') with two pagemod forms and two datasets, 
  * each pair with different id (exactly: ''am311'' and ''cm113'' if that matters), 
  * both pairs identical otherwise (same fields, same structure).

**Scenario 2**: I have one page with form (''materials'') and two datasets with data (''materials:am311'' and ''materials:cm113'')
  * each pair with different id (exactly: ''am311'' and ''cm113'' if that matters), 
  * both pairs forms/datasets identical otherwise (same fields, same structure).

In both scenarios, data gets added to both datasets, instead of one of them (''am311'' or ''cm113'').

**From Author : This is not a bug in this module, its a bug in bureaucracy.  If you have multiple bureaucracy forms on a page, the result is always generated from the first's parameters (action parameters) since it doesn't set these in the form, but re-reads them from the page**

**<del>From Author : This bug is fixed by redeploying bureaucracy with the file with my patch detailed [[plugin:bureaucracy#download_and_installation|here]], I have mailed Andreas and asked him to include my fix in his code.</del>**

**From Author : This bug appears to have been fixed, many thanks to the bureaucracy maintainer for this**

==== small bug for @@meta.user.id@@  ====
Great plugin ! I use it all the time. small bug for @@meta.user.id@@ which doesn't work for me :
I think it should use //return $INFO['user'];// instead of //return $INFO['userinfo']['user'];//

**From Author : I cannot replicate this, both accessors work **

>> 2011-11-15 From besancon@math.jussieu.fr: I have the same bug with @@meta.user.id@@. According to http://www.dokuwiki.org/devel:environment#global_variables, you get the login name with $INFO['client'] instead of $INFO['userinfo']['user'] which is not documented at all. You have to correct file "bureaucracy/actions/pagemod.php" on line 109 by changing
  return $INFO['userinfo']['user'];
to
  return $INFO['client'];

==== Question on Period Use in Field Name ====

I was wondering if there is a way to use the period in field names, so you could make numbered items like "1. What is your name?", etc. (using a period currently breaks the template) The only way I'm able to do this currently is writing a static "1. What is your name?" which is followed immediately by a "Name [    ]" line, which gets really cluttered if you're trying to do something like a numbered questionnaire.

On the other hand, is there any way to show a field title like "Please enter you name", but assign it to a variable like @@name@@ for use in the pagemod tag? I apologize if this question is better asked on the bureaucracy plugin page.--- // [[kououken@gmail.com|Kououken]] 2010/03/02 //

** From Author : Fixed in 1.2 **

==== Is it possible to check the value of a placeholder? ====

Hi! I am quite new to wikis, so please forward me to the right place if my question is wrong here. Is there any way to check the value of a placeholder and treat the form depending on its value? Something like "if @@name@@=='Green' then //<show output of the form>//"?  //[[anna.averbakh@inf.uni-hannover.de|Anna]] 2010/03/03//

** From Author : This isn't functionality I am looking at adding, because its open ended in terms of possibilities **



==== Shows an empty screen after submitting the form ====

After I submit the form the page reloads but shows only the header, footer and sidebar without the content.
The results output doesn't work regardless that I try to add them to the same or another page.

The other bureaucracy actions (email and template) work fine.

>>I have the same problem and I can't find any solutions on this page. I would like to add that my DokuWiki is hosted on a "UniServer" installation and I'm running the latest version of DokuWiki and bureaucracy, but my page only shows the header other then that it's as described above. I'm hoping to bring some attention to this problem by placing this comment --- //[[ricaxe@telia.com|Ric]] 2010/05/10 23:49//

>>The same happens here, just a blank page after submit when using the "Minimalistic Guestbook" -- Any suggestions? --- //[[rdoerrer@gmx.de|Rainer]]2010-09-28//

** From Author : I cannot replicate this even using the latest software,firefox/opera and ie7, please can you give me more information, like does it work, but just not display?  What platform version etc **

** From Author : This has been confirmed fixed by the bug raiser, no idea what I did, but nevertheless the bug has moved on **

==== Drop-down Boxes ====

I already asked this on the bureaucracy page but maybe it could be implemeted here. Is there a way to use multiple drop-downboxes where the input in the first box affects which options are available in the 2nd one and so on? Thanks! - Paul

**From Author - This will have to be done in the bureaucracy plugin, I don't have much to do with the front end.**

==== Multiple actions ====

When looking for the possibility of using both mail and pagemod actions from the same form, I came across a small extension to the pagemod plugin, namely the 'pagemodandmail' action handler. However, likely because both buraucracy and pagemod has come in new versions, I had to do som small adjustments to make it work. So this is the version 1.2 compliant version of the extension.

To install, add the following piece of code as a file named 'pagemodandmail.php' in dokuwikilib/plugins/bureaucracy/actions directory:
<code>
<?php // charset=utf-8
/**
 * Action pagemod followed by sendemail for DokuWiki plugin bureaucracy
 */

class syntax_plugin_bureaucracy_action_pagemodandmail extends syntax_plugin_bureaucracy_action {

    /**
     * Simply extract the relevant arguments and call the relevant actions
     */
    function run($data, $thanks, $argv) {
        global $ID;
        global $conf;
        require_once(DOKU_PLUGIN . 'bureaucracy/actions/action.php');
        require_once(DOKU_PLUGIN . 'bureaucracy/actions/pagemod.php');
        require_once(DOKU_PLUGIN . 'bureaucracy/actions/mail.php');

        $pagemodargs = array_slice($argv,0,2);
        $emailargs = array_slice($argv,2);

        $class = 'syntax_plugin_bureaucracy_action_pagemod';
        $pagemodder = new $class();
        $pagemodsuccess = $pagemodder->run($data, $thanks, $pagemodargs);

        $class = 'syntax_plugin_bureaucracy_action_mail';
        $emailer = new $class();
        $emailsuccess = $emailer->run($data, $thanks, $emailargs);

        $rmsg = '';
        if (!$pagemodsuccess) {$rmsg .= "Pagemod failed";}
        if (!$emailsuccess) {$rmsg .= "Emailing failed";}
        if ($rmsg=='') {return $thanks;}
        else {return $rmsg.join(',',$errors);}
    }
}
</code>

Use the following notation in the form:
<code>
action pagemodandmail <page:to:update> <tag> <email_address1> <email_address2> <email_address3> ....
</code>
Example:
<code>
<form>
action pagemodandmail support:subsystem:registered_bugs buglist 1st_address@example.com 2nd_address@example.com
Thanks "Thanks for your input."
Fieldset "Error report"
Textbox  "Name" 
email "Email"
select "Subsystem" "sub1|sub2|sub3"
textarea "Description"
textarea "Error message(s)"
submit "Send report"
</form>
</code>
The page support:subsystem:registered_bugs must be edited with the following pagemod entry
<code>
^ Name ^ Subsystem ^ Description ^ Error message(s) ^
<pagemod buglist output_before>|@@Name@@ |@@Email@@ |@@Subsystem@@ |@@Description@@ |@@Error message(s)@@ |</pagemod>
</code>
// [[knutsd@met.no|Knut S. Dale]] 2010/12/27 //

==== Multiple Pages changed from one form ====

Would such syntax be possible:

<code>
<form>
action pagemod _self,another:page:somewhere:else id
fieldset "Ereignis eingeben"
textbox "Ereignis:" /^((?!<\/code>).|\n)*$/
date "Gültig von:"   
date "bis:" 
textarea  "Details:" /^((?!<\/code>).|\n)*$/
submit "Ereignis veröffentlichen"
</form>
</code>

making it possible to have one form which places the info on more than one page? - Andy

===== Bugs =====

  * I experienced this: if the %%@@Variable@@%% is on the begining of the line, it allways expand into empty string, even if I fill the form. And I found another difference - with bureaucracy template mode, not filled variables were kept as were, but with pagemod mode, they are replaced with empty strings.
  * Use of plugin is problematic if you use it with tables AND use ''edittable'' plugin - see description in [[plugin:edittable]].
  * Is there a size/length constraint?  I am responding to a new page question and it will not let me post a long response.