Differences

This shows you the differences between two versions of the page.

--- plugin:pagemod [2015-08-06 12:38] – 89.202.231.254
+++ plugin:pagemod [2024-01-20 07:55] (current) – Aleksandr
@@ Line 1: / Line 1: @@
-====== Sales ======
+====== pagemod Plugin ======
-^ Date ^ Supplier ^ Our Cost (Single) ^ Client Cost (Single) ^ Quantitiy Ordered ^ Client Cost (Full), ex VAT ^
+---- plugin ----
-| 01/02/2009 | B&C | 54.00 | 56.00 | 234.00 | 213.00 |
+description: A plugin which allows you to add information to existing pages via forms. It works with the Bureaucracy Plugin
-| 03/03/2009 | IT Vision | 34 | 989 | 3 | 2390 |
+author     : Baseline IT
-| 01/02/2009 | Computer Corporation | 3453 | 3453 | 345 | 34535 |
+email      : info@baseline-remove-this-it.co.za
-| a | Computer Corporation | a | marco | a | 2 |
+type       : syntax
-<pagemod add_sale output_before>| @@Date@@ | @@Supplier@@ | @@Our Cost (Single)@@ | @@Client Cost (Single)@@ | @@Quantity Ordered@@ | @@Client Cost (Full), ex VAT@@ |
+lastupdate : 2014-11-10
-</pagemod>
+compatible : 2016-06-26, Detritus, Hrun, Ponder Stibbons, Greebo, Hogfather, Igor
+depends    : bureaucracy
+conflicts  :
+similar    :
+tags       : form, create, update, editing
+downloadurl: https://github.com/rendezz/dokuwiki-pagemod/archive/master.zip
+bugtracker : https://github.com/rendezz/dokuwiki-pagemod/issues
+sourcerepo : https://github.com/rendezz/dokuwiki-pagemod/
+screenshot_img :
+----
+===== Download and Installation =====
+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
+===== Overview =====
+I created 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.
+It works loosely in the following way:
+    - A form exists on a page (created by the [[plugin:bureaucracy]] plugin)
+      * this can be the page to be modified or it can be another page.
+      * this form contains the action field ''action pagemod <targetpage> <pagemod_id>''
+    - A results placeholder sits on a target page
+      * this placeholder is enclosed by the ''<pagemod> </pagemod>'' tags
+    - The form is filled in and submitted. Subsequently the pagemod action extends the target page by including a copy of the placeholder wherein the variables are replaced with the form values.
+So here are the features:
+  * A page with a form 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.
+    * All the sections need to have the same ''pagemod_id'' as the submitting form
+  * A person can update a 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 you want people to only have access to read the resultant page, but not change it, protect the **form** page.
+    * No read access to result page for a user, prevents modifying it via form.
+  * Updating more pages at once is possible by adding an action field for each page
+That's it.
+===== Usage =====
+==== Form Syntax ====
+Defining a form is done via the [[plugin:bureaucracy]] plugin, please check that for complete syntax.  But here are the additions by this plugin:
+<code>
 <form>
-action pagemod ztpf:consegne add_sale
+action pagemod <target namespace:page> <pagemod_id>
-fieldset "Add your bits to the table"
+<...various fields for submit...>
-textbox   "Date"
-select   "Supplier" "B&C|Computer Corporation|IT Vision|Compu Cable|Matrix"
-textbox  "Our Cost (Single)"
-textbox  "Client Cost (Single)"
-textbox  "Quantity Ordered"
-textbox  "Client Cost (Full), ex VAT"
 submit
 </form>
+</code>
-===== Reverse Order List =====
+To make bureaucracy use the pagemod action, you need to add **action pagemod** with the following parameters:
-<pagemod add_sale output_after>
+  * ''target'' : The target page, allowed notations:
-  * Date is @@Date@@, Support is @@Supplier@@, Our Cost is @@Our Cost (Single)@@, Client Cost is @@Client Cost (Single)@@, Quantity is @@Quantity Ordered@@, Full Client Cost is @@Client Cost (Full), ex VAT@@</pagemod>
+    * absolute pageids (e.g. ''page'', ''namespace:otherpage'')
-  * Date is a, Support is Computer Corporation, Our Cost is a, Client Cost is marco, Quantity is a, Full Client Cost is 2
+    * Relative pageids, which are solved with respect to current page (e.g. ''.:neighbourpage'')
-  * Date is 01/02/2009, Support is Computer Corporation, Our Cost is 3453, Client Cost is 3453, Quantity is 345, Full Client Cost is 34535
+    * **_self** to denote the same page as the form
-  * Date is 03/03/2009, Support is IT Vision, Our Cost is 34, Client Cost is 989, Quantity is 3, Full Client Cost is 2390
+  * ''pagemod_id'' : If using multiple pagemod enclosures in a page, this is to identify which enclosure to fill and include in the page. **NOTE: the ''pagemod_id'' value cannot include a dash character ("-"). A dash character will break the ''<pagemod>...</pagemod>'' section such that it will render as mere text and not function. The underscore character ("_") works.**
-  * Date is 01/02/2009, Support is B&C, Our Cost is 54.00, Client Cost is 56.00, Quantity is 234.00, Full Client Cost is 213.00
+==== Template Syntax ====
-===== Nothing should be seen below here ever =====
+Defining a pagemod template is done within a page with the following code:
-<pagemod anothername>  * Oops, not supposed to ever see me
+<code>
+<pagemod <pagemod_id> <params>>
+The wiki text will be parsed to 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 around, that is visible again.
+</code>
+Or an real example for adding rows to a table:
+<code>
+Some more text, and a table with as last row the pagemod placeholder.
+^ Table header 1 ^ Table header 2 ^
+<pagemod table_adder output_before>| @@table value 1@@ | @@table value 2@@ |
+</pagemod>
+</code>
+**Note:** If the resulting table is later edited with [[plugin:edittable|EditTable Plugin]], then the above pagemod code will disappear (only existing contents remain).
+The pagemod enclosure starts with:
+  <pagemod <pagemod_id> <params>>
+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. Converting of the contents of the pagemod enclosure is done with the [[plugin:bureaucracy]] plugin's replacements function. So similar patterns are available.
+===Meta variables===
+The meta variable are some extra variables for the pagemod plugin. The meta variables values 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.
+==== Incrementing number (by 1) ====
+The [[plugin:bureaucracy#number_field|bureaucracy plugin]] has the following fields working perfectly with Pagemod Plugin:
+  * ''number'' field, for example:
+    * ''number "Auto Incremental Nr. by one" ++ 0000 !'' where the field show up the following number, being able top modify it acording to your moment needs and
+  * ''hiddenautoinc'', a hidden field. Ex:
+    * ''hiddenautoinc "Hidden Auto incremental field" ''
+  *  Both of them has auto incrementing counter on each succesfull submit.
+<code>
+number "One"
+number "Two" ++
+number "Third" >3 <40
+hiddenautoinc "Four (notice: conflicts with Two)"
+number "Fifth" 000
+number "Sixth" ++ 000
+</code>
+==== Upload ====
+For the moment, //2019-04-02 14:53// the pagemod upload do not work right of the box. it needs the patpatch offered here:
+[[https://github.com/BaselineIT/dokuwiki-pagemod/blob/891b6465a4b2a1db1d548611cc2584b49ec815c1/helper/pagemod.php]]
+**On the same page example:**
+<code>
+<form>
+action pagemod _self add_sale
+fieldset "Add your bits to the table" !
+number "Nr. de ordine internă automat" ++
+date "Data începerii melodiei"
+select   "Supplier" "B&C|Computer Corporation|IT Vision|Compu Cable|Matrix"
+textbox  "Our Cost (Single)" !
+textbox  "Quantity Ordered" !
+fieldset  "Your Order"
+textbox   "Your Name" !
+select    "What do you want"  "Car|Blimp" !
+fieldset  "Car Parameters" "What do you want" "Car"
+number    "Number of Wheels" !
+textbox   "Extras" !
+fieldset  "Blimp Parameters" "What do you want" "Blimp"
+select    "Filling" "Helium|Hot Air"
+number    "Size" !
+fieldset  "Payment"
+yesno     "Can you pay right now?" !
+fieldset  "Details" "Can you pay right now?"
+textbox   "Name" !
+number    "Amount" !
+fieldset  ""
+yesno     "Incarci un fisier?"
+fieldset  "" "Incarci un fisier?"
+file "Incarca un fisier"
+hidden "acoldesch" "={{"
+hidden "acolinch" "=}}"
+hidden "foldedin" "=++Upload|"
+hidden "foldedout" "=++"
+fieldset  ""
+submit "Salveaza"
+</form>
+</code>
+<code>
+<sortable r2>
+^ Nr.  ^ Data Automata  ^ Date Manuala  ^ Supplier  ^ Our Cost (Single)  ^ Rotile?  ^ Quantity Ordered  ^ Upload  ^
+| a12 | 06 Nov 2018 | 2018-11-06  | B&C |   |   |   | ++Upload|{{..:10_fl.mid}}++ |
+<pagemod add_sale>| a@@Nr. de ordine internă automat@@ | @@meta.date.format.d M Y@@ | @@Data începerii melodiei@@  | @@Supplier| @@ | @@Quantity Ordered| @@ | @@Filling| @@ | @@Quantity Ordered| @@ | @@foldedin| @@@@acoldesch| @@@@Incarca un fisier| @@@@acolinch| @@@@foldedout| @@ |
+</pagemod>
+</sortable>
+</code>
+--- [[user>florious|Florin C.]] //2019-04-02 15:10//
+===== FAQ =====
+===== Development =====
+In November 2014 the pagemod plugin is updated to use a helper for the pagemod action. The Bureaucracy Plugin is updated in November 2014 as well, it will load this helper automatically if used in a form. The new version of Bureaucracy supports only the new version of Pagemod.
+Remark: the file ''bureaucracy/actions/pagemod.php'' is now unused. You may remove it manually.
+==== Previous versions ====
+  * http://freecode.baselineit.net/dokuwiki/pagemod-latest.zip (previous version 1.2 - 2010-09-29)
+  * http://freecode.baselineit.net/dokuwiki/pagemod-1.1.zip (previous version 1.1)
+  * http://freecode.baselineit.net/dokuwiki/pagemod-1.0.zip (previous version 1.0)
+IMPORTANT NOTE: When you have installed these previous versions, you WILL need to UPDATE it once.  This is because it installs some stuff into the bureaucracy directory, but this action doesn't happen on install, but does happen on update.
+To update the plugin, click "Update" in the Admin/Plugins section of your DokuWiki.
+=== Manual installation of previous version ===
+In ''[wiki-root]/lib/plugins/'' this plugin adds:
+<code>
+pagemod/
+pagemod/syntax.php
+bureaucracy/
+bureaucracy/actions/
+bureaucracy/actions/pagemod.php
+</code>
+(note: since November 2014 no files are copied to bureaucracy plugin folder anymore)
+===== Bugs and feature requests=====
+The pagemod plugin is strongly intertwined with the bureaucracy plugin. For general questions and issues see also the [[bureaucracy|Bureaucracy plugin]] wiki page and the [[https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/issues|Bureaucracy issue tracker]].
+Please report issues and requests for Pagemod Plugin at https://github.com/rendezz/dokuwiki-pagemod/issues
+QUESTION: Can pagemod be triggered conditionally? Let's say there is a form with a yesno field. Could pagemod be called only when the yesno field is checked?
+==== Problem and solution ====
+The standard pagemod helper code does not do any substitution of page names according to bureaucracy variables.  I have designed a form which contains:
+  textbox Hnode
+  action  smg:config:@@Hnode@@ add_hwchange
+the problem being that ''@@Hnode@@'' is interpreted as "Hnode" and not the entered value.  The problem seems to lie in the helper script in ''public function run''.  I have added a call to ''$this->replace'' (as is done in ''public function parsePagemod'') just before the ''resolve_pageid'' call.  It now appears to be working.
+diff:
+,40d38
+  <             //Allow for the substitution os elements of the page name
+  <             $page_to_modify = $this->replace($page_to_modify);
+===== Example usecases =====
+An bundle of example pages is available:
+  * http://freecode.baselineit.net/dokuwiki/pagemod-namespace.tar.bz2
+Content:
+  * Some forms which modify the page of the form, or just another page.
+  * Extending an existing table
+  * Adding additional list items
+==== 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]].
+<code>
+======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>
+</code>
+--- //M. 2010/04/02//