1====== JSON Generate Document Plugin ======
2
3---- plugin ----
4description: Integrate "Generate new document" JSON based functionality into json plugin.
5author     : Janez Paternoster
6email      : janez.paternoster@siol.net
7type       : syntax, action
8lastupdate : 2023-10-26
9compatible : Hogfather,Igor,Jack Jackrum
10depends    : json
11conflicts  :
12similar    : json, jsoneditor, jsontable, struct, addnewpage, copypage
13tags       : data, json, database, button, create, form
14
15downloadurl: https://gitlab.com/dokuwiki-json/jsongendoc/-/archive/master/json-master.zip
16bugtracker : https://gitlab.com/dokuwiki-json/jsongendoc/-/issues
17sourcerepo : https://gitlab.com/dokuwiki-json/jsongendoc
18donationurl: https://paypal.me/jnz022
19
20screenshot_img: https://gitlab.com/dokuwiki-json/jsongendoc/-/raw/master/demo/screenshot.png
21----
22
23===== Installation =====
24Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
25
26Install also [[https://www.dokuwiki.org/plugin:json|JSON plugin]].
27
28===== Description =====
29JSON Generate Document Plugin is based on [[https://www.dokuwiki.org/plugin:json|JSON plugin]]. It adds a form with a button to the page. User can select the JSON data and enter the name for the new document. When user presses the button, new text based document is generated, which is based on specified template. Patterns ''@ ... @'' inside template are replaced by corresponding JSON data. Also sections from template are hidden or displayed according to condition calculated from JSON data.
30
31Newly created document can the be saved as a Dokuwiki page to the server, or it can be downloaded via browser to the client machine. It is possible to generate and download any text based document, for example txt, html, svg, cvs, ...
32
33Here is a [[https://dokuwiki-json-demo.1001beauty.si/|Dokuwiki JSON Demo Server]] with JSON database integrated into DokuWiki. Also source code of this plugin contains demo. You can copy the contents of the demo files into your Dokuwiki and experiment with them.
34
35
36===== Template =====
37Template is basically a dokuwiki page, which may have some ''@ ... @'' patterns, which will be replaced by JSON data. There are three types of pattern:
38^ Pattern     ^ Description ^
39| ''@ ... @'' | Standard patterns from [[https://www.dokuwiki.org/namespace_templates|Namespace Templates]]. |
40| ''@%%%$%%-start(''// filter //'')%''// dokuwiki_section //''%%%$%%end%@'' | If //filter// (see [[https://www.dokuwiki.org/plugin:json|JSON Data Plugin]]) is evaluated to true, then //dokuwiki_section// will be added to the document, otherwise it will be removed. |
41| ''@%''''$''// path //''%@'' | Variable on path is type of string, number or boolean. Extract data. |
42| ::: | Variable on path is type of array. Extract json. |
43| ::: | Variable on path is undefined. Extract ''null''. |
44
45
46===== Usage =====
47Syntax is similar as in [[https://www.dokuwiki.org/plugin:json|JSON Data Plugin]]:\\
48''<jsongendoc'' //attributes// ''>'' //inline_json// ''</jsongendoc>''
49
50It is parsed with same parser as ''<json>'' elements, so rules for //attributes// and //inline_json// are the same. It loads JSON data the same way, from //src// attribute and from //inline_json//. It only has some extra attributes, additional render and additional action.
51
52This syntax generates a form with the following fields:
53  * **Select box** - Select box is generated from JSON data, if it contains array of similar data objects.
54  * **Inpit field** - User enters a name for the new document into the input field.
55  * **Button** - After user presses a button, a command is sent to the server. If there are no errors, then new Document is generated from template and JSON data. Document is either stored to the server or offered for download. Server returns information about success or failure, which are displayed below the form.
56
57==== Attribute 'mime' ====
58If this attribute is omitted or it is empty string, then newly generated file will be stored to the server as a new Dokuwiki page. Otherwise it must contain [[https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types|Mime type]] of the Document, which will be downloaded. For example: ''text/plain'', ''text/html'', ''text/csv'', ''image/svg+xml'', ''application/json'', ''application/xml'', etc.
59
60==== Attribute 'namespace' ====
61It specifies the [[https://www.dokuwiki.org/namespaces|namespace]] (location) for the template and for the new document(if //mime// is undefined). If it is not specified, then current location is used. If a //docname// or //template// attribute contains full file path, then namespace attribute is ignored.
62
63==== Attribute 'template' ====
64It specifies the template file. If template is not specified, then [[https://www.dokuwiki.org/namespace_templates|Namespace Template]] is used.
65
66==== Attribute 'docname' ====
67If specified, then it will be shown in **Inpit field** as default for the new document name. If value has some hashes at the end, they will be replaced with auto incrementing number. For example ''docname=my_doc_####'' will set the value of Input field to something like 'my_doc_0022'.
68
69==== Attribute 'select' ====
70This attribute is optional. It specifies the options inside the Select box. JSON data must be an array with similar data objects.
71
72'select' attribute contains a comma separated list of ''key: path'' pairs, where key is number in sequence and path is a path to variable from array element. Those key/path pairs specifies the name of the option for each array element inside the Select box.
73Example: ''select='0:name, 1:type, template:path.to.template'''.
74
75If this attribute is not specified, then Select box is not shown. Complete JSON data are passed to the template.
76