DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:bureaucracy

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
plugin:bureaucracy [2018-04-19 09:46] – [Dependencies with Fieldsets] Klap-inplugin:bureaucracy [2024-02-09 10:35] (current) Aleksandr
Line 2: Line 2:
  
 ---- plugin ---- ---- plugin ----
-description: Easily create HTML forms to collect data which can be sent via email or used to create pages.+description: Easily create HTML forms to collect data which can be sent via email or used to create pages
 author     : Andreas Gohr author     : Andreas Gohr
 email      : andi@splitbrain.org email      : andi@splitbrain.org
 type       : syntax, action type       : syntax, action
-lastupdate : 2018-03-28 +lastupdate : 2023-05-16 
-compatible : Frusterick Manners+compatible : Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum, Kaos
 depends    :  depends    : 
-conflicts bureaucracy-au, form+conflicts bureaucracyau, form
 similar    : form, contact, contactmodern, conform similar    : form, contact, contactmodern, conform
 tags       : form, email, poll, create tags       : form, email, poll, create
 screenshot_img: :plugin:bureaucracy.png screenshot_img: :plugin:bureaucracy.png
 +
 downloadurl: https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/zipball/master downloadurl: https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/zipball/master
 sourcerepo : https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/ sourcerepo : https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/
Line 23: Line 24:
 ===== Download and Installation ===== ===== Download and Installation =====
  
-Download and install the plugin using the [[plugin:plugin|Plugin Manager]] using the download link given above. Refer to [[:Plugins]] on how to install plugins manually.+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
  
 ==== Changes ==== ==== Changes ====
Line 33: Line 34:
 ==== Recommended additional Plugins ==== ==== Recommended additional Plugins ====
  
-You might want to use on an open wiki the [[CAPTCHA]] plugin to avoid automated spam. When captcha plugin is installed, bureaucracy integrate automatically the captcha check in its form submit handling. The [[SMTP]] plugin may help when your DokuWiki can't send mails. When you use the template action of bureaucracy, you can add in the template a dataentry of the [[Data]] plugin that structures and stores your information for good accessibility, whereas the dataentry you can use placeholders of bureaucracy to place information from the form.\\ The recent [[Struct]] plugin draws heavy inspiration from the data plugin and allows for central management of wanted structured data while keeping the functionality of the data plugin. The struct plugin supports integration with the Bureaucracy Plugin. This allows reusing the input mechanisms of the different types in Bureaucracy forms and creation of structured data when pages are created through Bureaucracy's template action.+On an open wiki, you might want to use the [[CAPTCHA]] plugin to avoid automated spam. When it is installed, Bureaucracy automatically integrates the captcha check in its form submission handling.  
 + 
 +The [[SMTP]] plugin may help when your DokuWiki can't send mails.  
 + 
 +When you use Bureaucracy's //template// action, you can add in the template a dataentry of the [[Data]] plugin that structures and stores your information for good accessibility, whereas the dataentry you can use placeholders of bureaucracy to place information from the form. 
 + 
 +The recent [[Struct]] plugin draws heavy inspiration from the data plugin and allows for central management of wanted structured data while keeping the functionality of the data plugin. The struct plugin supports integration with the Bureaucracy Plugin. This allows reusing the input mechanisms of the different types in Bureaucracy forms and creation of structured data when pages are created through Bureaucracy's template action. 
 + 
 +=== Additional Actions === 
 + 
 +An additional plugin to look at is [[pagemod]], which adds a ''pagemod'' action for the Bureaucracy plugin to add data to an existing page (in addition to the current templating and mailing functionality) 
 + 
 +=== Additional Fields ===
  
-//additional actions// \\  +The [[Data]] plugin can not only be useful in templates as mentioned above, but it also provides a ''data_aliastextbox'' field that lets you create fields with types and type aliases of the data plugin. Some of these types have a nice layout e.g. pagesuggestions or listing using predefined options from type aliases. See [[data#bureaucracy_plugin_and_type_aliases|example]].
-An additional plugin to look at is the [[pagemod]] plugin which add an action ''pagemod'' for the bureaucracy plugin to add data to an existing page (in addition to the current templating and mailing functionality)+
  
-//additional fields// \\  +With [[Struct]] plugin, you can use any [[plugin:struct:bureaucracy#single_field|field]] from any defined schema as a field in a bureaucracy form. You can also add a [[plugin:struct:bureaucracy#complete_schema|whole schema]] to the form.
-The [[Data]] plugin can be useful in templates as mentioned before, but it provides a ''data_aliastextbox'' field too, that lets you create fields with types and type aliases of the data plugin. Some of these types have a nice layout e.g. pagesuggestions or listing using predefined options from type aliases. See [[data#bureaucracy_plugin_and_type_aliases|example]].\\ With [[Struct]] plugin, you can use any [[plugin:struct:bureaucracy#single_field|field]] from any defined schema as a field in a bureaucracy form. You can also add a [[plugin:struct:bureaucracy#complete_schema|whole schema]] to the form.+
  
 ==== Warning ==== ==== Warning ====
Line 137: Line 148:
     * creates a checkbox     * creates a checkbox
     * needs a label     * needs a label
-    * needs default values for yes and no ('' =true_value !false_value ''). If only used for a fieldset the default values are not required.+    * needs default values for yes and no (''%% "=true value" "!false value" %%''). If only used for a fieldset the default values are not required.
   * **select**   * **select**
     * creates a dropdown list     * creates a dropdown list
     * needs a label     * needs a label
     * needs a second argument containing the select options separated by a pipe ''|'' char\\ (''%% "Peaches|Apples|Oranges" %%'')     * needs a second argument containing the select options separated by a pipe ''|'' char\\ (''%% "Peaches|Apples|Oranges" %%'')
 +  * **multiselect**
 +    * you can select multiple values
 +    * needs a label
 +    * needs a second argument containing the select options separated by a pipe ''|'' char\\ (''%% "Peaches|Apples|Oranges" %%'')
 +    * example: ''%% multiselect "Label" "Opt1|Opt2|Opt3" =Opt1,Opt3 %%''
 +    * In mail action: all options will be joined by "'', ''" in e-mail message
 +    * In template action:
 +      * if field is marked with "@" all selected options will be joined with page separator
 +      * during template substitution all options will be joined by "'', ''" or you can provide optional separator: ''@@Label(separator)@@''
   * **radio**   * **radio**
     * creates a set of radiobuttons     * creates a set of radiobuttons
Line 188: Line 208:
       * datatypes with a type alias that defines 'valid values' will appear as a (multi)select field       * datatypes with a type alias that defines 'valid values' will appear as a (multi)select field
       * otherwise it appears as usual textbox, sometimes with [[data#custom_entry_editor|added features]] as datepicker and pagesuggestions       * otherwise it appears as usual textbox, sometimes with [[data#custom_entry_editor|added features]] as datepicker and pagesuggestions
-  *  **struct_field** (needs plugin)+  *  **struct_field** + **struct_fieldhidden** (needs plugin)
     * Just specify a field from a defined schema "<schema>.<name>" from [[Struct|Struct plugin]]     * Just specify a field from a defined schema "<schema>.<name>" from [[Struct|Struct plugin]]
     * Label is used from definition as well as validation rules     * Label is used from definition as well as validation rules
Line 264: Line 284:
  
 <code> <code>
-  * field  = Tell us about yourself"+  * field  = Tell us about yourself
   * name   = Your Name   * name   = Your Name
   * age    = Your Age   * age    = Your Age
Line 343: Line 363:
 ===== Action Modes ===== ===== Action Modes =====
  
-The bureaucracy does three things:+Bureaucracy does three things:
  
   - it displays a neat form   - it displays a neat form
   - it validates user input   - it validates user input
-  - it gives the user input to action mode+  - it sends the user'input to an action mode
  
-The last step is where the data is processed. What action is to be used is defined in the ''action'' field as described above. Currently three modes are supported: ''mail'', ''template'', and ''script''. Additional modes (e.g. for storing the data in a database) can easily be added.+The last step is where the data is processed. The action to use is defined in the ''action'' fieldas described above. Currently three modes are supported: ''mail'', ''template'', and ''script''. Additional modes (e.g. to store the data in a database) can easily be added.
  
 ==== Mail Mode ==== ==== Mail Mode ====
  
-This is a simple action. When used default all user input will be sent by email to the configured email address. See the example above how to use it. You may specify multiple recipient mail addresses separated by spaces.+This is a simple action. When used defaultall user input will be sent by email to the configured email address. See the example above how to use it. You may specify multiple recipient mail addresses separated by commas.
  
  
Line 380: Line 400:
  
 <code html> <code html>
-Dear @@Your Name@@, +Dear @@Your Name@@,</br> 
- +</br> 
-You are <b>great<b>, you just <i>purchased</i> our @@What do you want@@! +You are <b>great</b>, you just <i>purchased</i> our @@What do you want@@!</br> 
- +</br> 
-We will deliver it fast as possible, see the  +We will deliver it fast as possible, see the </br> 
-<a href="http://example.com/conditions">conditions</a>+<a href="http://example.com/conditions">conditions</a>.</br> 
- +</br> 
-Kind regards, +Kind regards,</br> 
-Future Machines company+Future Machines company</br>
 </code> </code>
  
Line 482: Line 502:
 ^Placeholder ^ action ^ ^Placeholder ^ action ^
 | ''@@Field label@@''\\ ''##Field label##'' | Will be replaced by the actual values the user filled into\\ the form. | | ''@@Field label@@''\\ ''##Field label##'' | Will be replaced by the actual values the user filled into\\ the form. |
 +|''@curNS(arg)@''\\ ''@getNS(arg)@''\\ ''@noNS(arg)@''\\ ''@p_get_first_heading(arg)@''|Will be replaced with a result of the corresponding dokuwiki function. ''arg'' can be both a static value, eg. ''@curNS(some:test:value)@'' or the placeholder of a field, eg. ''@p_get_first_heading(@@field@@)@''.|
 | ''@@Field label|Nice alternative@@''      | For empty field the text ''Nice alternative'' is shown   | | ''@@Field label|Nice alternative@@''      | For empty field the text ''Nice alternative'' is shown   |
 |''@NSBASE@''                               | (only template action) Namespace that contains new page.\\ eg. if the new page is ''foo:bar:baz:bang'', ''@NSBASE@'' will contain ''baz'' | |''@NSBASE@''                               | (only template action) Namespace that contains new page.\\ eg. if the new page is ''foo:bar:baz:bang'', ''@NSBASE@'' will contain ''baz'' |
 | %Y %F %a %Y-%m-%d %s... etc               | [[phpfn>strftime]] parameters to refer to current time   | | %Y %F %a %Y-%m-%d %s... etc               | [[phpfn>strftime]] parameters to refer to current time   |
-| <nowiki>%%</nowiki>                       | Replaced by ''%'' char, needed to avoid accidental time\\ replacements in your template.| +| <nowiki>%%</nowiki>                       | Replaced by ''%'' char, needed to avoid accidental time replacements in your template.| 
-|''<nowiki>@DATE(<datetime>,%%Y-%%m-%%e)@</nowiki>''\\ ''@DATE(<datetime>)@''  | Accepts different datetime formats, which are outputted in the\\ requested [[phpfn>strftime]] format. Providing no format returns date\\ with format of the [[config:dformat]] setting. |+|''<nowiki>@DATE(<datetime>,%%Y-%%m-%%d)@</nowiki>''\\ ''@DATE(<datetime>)@''  | Accepts different [[phpfn>class.datetime|datetime]] formats, which are outputted in the requested [[phpfn>strftime]] format. If no format is provided, date is returned with format of the [[config:dformat]] setting. ([[plugin:bureaucracy#template_placeholder_date|Example]]) |
 | ''@ID@ @USER@ @MAIL@'' ... etc | DokuWiki [[:namespace_templates#replacement_patterns|replacement patterns]] for templates are available too | | ''@ID@ @USER@ @MAIL@'' ... etc | DokuWiki [[:namespace_templates#replacement_patterns|replacement patterns]] for templates are available too |
 | ''@FORMPAGE_ID@ @FORMPAGE_NS@ @FORMPAGE_CURNS@'' ... etc | Works like [[:namespace_templates#replacement_patterns|replacement patterns]] but refers to the page with the form | | ''@FORMPAGE_ID@ @FORMPAGE_NS@ @FORMPAGE_CURNS@'' ... etc | Works like [[:namespace_templates#replacement_patterns|replacement patterns]] but refers to the page with the form |
Line 492: Line 513:
 |''@TABLEHTML@'', ''@TABLETEXT@''           | (only mail action) html or text table of all field values | |''@TABLEHTML@'', ''@TABLETEXT@''           | (only mail action) html or text table of all field values |
 |''<noinclude>...</noinclude>''             | Tags with their content are removed       | |''<noinclude>...</noinclude>''             | Tags with their content are removed       |
 +|''<noreplace>...</noreplace>''             | The content between ''<noreplace>...</noreplace>'' is preserved without performing any replacements but tags itself are removed.      |
 |''@LANG@''                                 | Languagecode as configured                | |''@LANG@''                                 | Languagecode as configured                |
 |''@TRANS@''                                | Languagecode obtained from page id of form| |''@TRANS@''                                | Languagecode obtained from page id of form|
Line 542: Line 564:
 This action gives the data to a PHP script supplied by the administrator. The script then can do whatever it wants with the data. This action gives the data to a PHP script supplied by the administrator. The script then can do whatever it wants with the data.
  
-The script must be placed in ''conf/plugin/bureaucracy/'' directory. It must contain one class that is named ''bureaucracy_handler_//scriptname//'' and implements the interface ''[[https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/blob/master/interfaces/bureaucracy_handler_interface.php|dokuwiki\plugin\bureaucracy\interfaces\bureaucracy_handler_interface]]''+The script must be placed in ''conf/plugin/bureaucracy/'' directory. It must contain one class that is named ''helper_plugin_bureaucracy_handler_//scriptname//'' and implements the interface ''[[https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/blob/master/interfaces/bureaucracy_handler_interface.php|dokuwiki\plugin\bureaucracy\interfaces\bureaucracy_handler_interface]]''
  
 That means the class has to have the ''handleData($fields, $thanks)'' method with the fields and the thanks-message as parameters. It returns a thanks-message on success or ''false'' on error. That means the class has to have the ''handleData($fields, $thanks)'' method with the fields and the thanks-message as parameters. It returns a thanks-message on success or ''false'' on error.
Line 562: Line 584:
 use dokuwiki\plugin\bureaucracy\interfaces\bureaucracy_handler_interface; use dokuwiki\plugin\bureaucracy\interfaces\bureaucracy_handler_interface;
  
-class bureaucracy_handler_example implements bureaucracy_handler_interface {+class helper_plugin_bureaucracy_handler_example implements bureaucracy_handler_interface {
  
     /**     /**
Line 607: Line 629:
   * Fifth Number field returns values which are completed with leading zeros. Input of 23 will be returned as 023.   * Fifth Number field returns values which are completed with leading zeros. Input of 23 will be returned as 023.
   * Sixth Number is a combination of Two and Fifth   * Sixth Number is a combination of Two and Fifth
 +
 +==== Template placeholder @DATE@ ====
 +
 +  hidden "today" "=%Y-%m-%d"
 +  hidden "backtrack" "=@DATE(now -3 years,%%Y-%%m-%%d)@"
 +
 +  * in the template placeholder @DATE(...,...)@ the first parameter (before the comma) with the [[phpfn>class.datetime|datetime]] format can be used, for example, to dynamically calculate a date relative to today's date, powered by the php function [[phpfn>datetime.modify]] -> note specific locations of whitespaces in the syntax
 +  * the second parameter (behind the comma) with the strftime syntax can be used for formating the date output, as needed -> note that % in the [[phpfn>strftime]] parameters here have to be escaped by %%
  
 ===== Development ===== ===== Development =====
Line 648: Line 678:
   'fields' => helper_plugin_bureaucracy_field[], // all the fields of the form   'fields' => helper_plugin_bureaucracy_field[], // all the fields of the form
 ); );
 +</code>
 +
 +==== Hook into email action ====
 +
 +The event ''PLUGIN_BUREAUCRACY_EMAIL_SEND'' gives developers of other plugins access to the submitted form data before it is actually sent in the ''actionmail.php''.
 +
 +This makes it easier to provide custom fields in bureaucracy emails.
 +
 +The event data includes the form fields info and all the values, so they can be processed by third-party plugins:
 +
 +<code>
 +$evdata = [
 +    'fields' => $fields,
 +    'values' => &$this->values
 +];
 </code> </code>
  
Line 775: Line 820:
  
   * [[:tips:button_align|How to align a <button> element?]]   * [[:tips:button_align|How to align a <button> element?]]
-  * User-Forum: [[https://forum.dokuwiki.org/thread/13956|Left align in Bureaucracy Plugin]]+  * User-Forum: [[https://forum.dokuwiki.org/d/13956|Left align in Bureaucracy Plugin]]
  
 ===== Issues ===== ===== Issues =====
  
 Please report bug or feature request on the [[https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/issues|Github bugtracker]]. Please report bug or feature request on the [[https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/issues|Github bugtracker]].
plugin/bureaucracy.1524123965.txt.gz · Last modified: 2018-04-19 09:46 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki