Differences

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

--- json:json_plugin [2023/10/27 01:04] – admin
+++ json:json_plugin [2024/03/11 09:37] (current) – external edit 127.0.0.1
@@ Line 2: / Line 2: @@
 ---- plugin ----
-description: Build JSON database inside dokuwiki page and use the data in the page.
+description: Build JSON database inside DokuWiki page and use the data in the page
 author     : Janez Paternoster
 email      : janez.paternoster@siol.net
 type       : syntax, action, helper, remote
-lastupdate : 2023-10-26
+lastupdate : 2024-03-11
-compatible : Hogfather,Igor,Jack Jackrum
+compatible : Hogfather, Igor, Jack Jackrum, Kaos
 depends    :
 conflicts  :
@@ Line 22: / Line 22: @@
 ===== Installation =====
 Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
@@ Line 31: / Line 32: @@
 ===== Description =====
-With JSON Data Plugin you can build [[https://json.org/|JSON]] database inside dokuwiki page. JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is a [[wp>Document-oriented database]], so no SQL is used.
+With JSON Data Plugin you can build [[https://www.json.org/|JSON]] database inside DokuWiki page. JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is a [[wp>Document-oriented database]], so no SQL is used.
 To add JSON database into the wiki page write:
@@ Line 57: / Line 59: @@
   * Show or hide sections of DokuWiki page, based on value of specific JSON element.
   * As a datasource for a javascript widget.
-  * Json data can also be edited and safely stored back into the dokuwiki page via ajax call.
+  * JSON data can also be edited and safely stored back into the dokuwiki page via ajax call.
 ===== Demo =====
-There 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 for JSON Data Definition and Usage. You can copy the contents of the demo files into your Dokuwiki and experiment with them.
+There 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 for JSON Data Definition and Usage. You can copy the contents of the demo files into your DokuWiki and experiment with them.
+===== Support =====
+For issues or just questions use [[https://gitlab.com/dokuwiki-json/json/-/issues|Issues]] on Gitlab. Please don't email directly.
 ===== JSON Data Definition Syntax =====
 Each page must define it's JSON data. Data are inline or are loaded from external (text) files on each page refresh. Only those data are loaded, which are defined inside a page. Data are defined with one or more '%%<json>%%' elements:
 ''<json ''//attributes//''>''//inline_json//''</json>''
-When the dokuwiki page is served, there is internally a variable, which is an empty object on the beginning. For example ''json_database = {}''. After the above first ''<json>'' element is rendered, variable is something like this: ''json_database = {"person": {"firstname": "James", "lastName": "Smith"}}''. After each subsequent ''<json>'' element data is added to that database. ''path'' attribute specifies, where in the ''json_database'' data are appended or replaced.
+When the DokuWiki page is served, there is internally a variable, which is an empty object on the beginning. For example ''%%json_database = {}%%''. After the above first ''<json>'' element is rendered, variable is something like this: ''%%json_database = {"person": {"firstname": "James", "lastName": "Smith"}}%%''. After each subsequent ''%%<json>%%'' element data is added to that database. ''path'' attribute specifies, where in the ''json_database'' data are appended or replaced.
 ==== Inline JSON ====
-Valid [[https://json.org/|JSON]] data can be located between %%<json ...>%% and %%</json>%% tags. If both, inline data and data referenced by 'src' attribute are specified, then inline data have precedence. Inline data will replace overlapped data referenced by 'src' attribute.
+Valid [[https://www.json.org/|JSON]] data can be located between %%<json ...>%% and %%</json>%% tags. If both, inline data and data referenced by 'src' attribute are specified, then inline data have precedence. Inline data will replace overlapped data referenced by 'src' attribute.
 ==== Attribute 'id' ====
 ''id'' attribute must be specified, when we want to access this json element from somewhere else or if we want to write inline JSON data via ajax call. It must be unique on one page.
 ==== Attribute 'path' ====
-'path' attribute specifies, where in the 'json_database' data will be added. For example ''path=person1.address'' will write data into ''json_database.person1.address''. ''.'' (dot) is used as a delimiter between tokens. If tokens contains spaces, then they must be inside quotes.
+''path'' attribute specifies, where in the 'json_database' data will be added. For example ''path=person1.address'' will write data into ''json_database.person1.address''. ''.'' (dot) is used as a delimiter between tokens. If tokens contains spaces, then they must be inside quotes.
 If token is number, then it points to n-th array member. ''0'' points to first array member and so on. Special token ''_FIRST_'' or ''_LAST_'' points to the first or to the last member.
-If there are already data on the specified path, then new data will recursively replace overlapped original data. (For detailed rules see php function [[https://secure.php.net/manual/en/function.array-replace-recursive
+If there are already data on the specified path, then new data will recursively replace overlapped original data. (For detailed rules see php function [[phpfn>array_replace_recursive]].) This is true, if the following two modifiers are not used.
-.php|array-replace-recursive]].) This is true, if the following two modifiers are not used.
 Modifier **-**: if ''-'' (minus) is set in the beginning of the path attribute, then original data on the path will be erased before new data will be written. For example ''path=-person1.address''.
@@ Line 96: / Line 107: @@
 ==== Attribute 'src' ====
-''src'' attribute contains a [[wiki:syntax#links|Dokuwiki link]] to the external data. External data is a text file. It may be document from the same dokuwiki or it can be located anywhere on the net.
+''src'' attribute contains a [[wiki:syntax#links|DokuWiki link]] to the external data. External data is a text file. It may be document from the same dokuwiki or it can be located anywhere on the net.
 <code>
 src=path:to:remote_document
@@ Line 107: / Line 119: @@
 External data may be a pure JSON file, it begins with ''['' or ''{''.
-External data may be a text file with %%<json>%% elements inside - remote dokuwiki page. Remote dokuwiki page then first loads data according to the rules inside its %%<json>%% elements, builds its own database and then passes the generated database into our document. Please note, that %%<json>%% elements inside remote dokuwiki page may also contain 'src' attribute. In this case data from that 'src' are also loaded. Data are loaded recursively. How deep recursion goes is controlled in configuration setting 'src_recursive'.
+External data may be a text file with %%<json>%% elements inside - remote DokuWiki page. Remote DokuWiki page then first loads data according to the rules inside its %%<json>%% elements, builds its own database and then passes the generated database into our document. Please note, that %%<json>%% elements inside remote dokuwiki page may also contain 'src' attribute. In this case data from that 'src' are also loaded. Data are loaded recursively. How deep recursion goes is controlled in configuration setting 'src_recursive'.
 External data may be a specific %%<json>%% element from remote dokuwiki page. In that case %%<json>%% element must have an 'id' attribute. It is referenced as in third example above. If target %%<json>%% element have a 'src' attribute, then data is loaded recursively.
-Wildcards may be may be used in 'src' attribute. See fourth example above. In that case multiple files are read and integrated into our database. See [[https://www.php.net/manual/en/function.glob.php|glob() function]].
+Wildcards may be may be used in 'src' attribute. See fourth example above. In that case multiple files are read and integrated into our database. See [[phpfn>glob()|glob() function]].
 Fifth example above shows, that 'src' attribute can not only be used for the file path, it can also contain JSON data. This way some already defined data from page can be "cloned" and reused. Similar as in [[#data_snippets_inside_inline_json|Data snippets inside inline JSON]]. JSON data are automatically recognized, if 'src' attribute contains: ''['', ''{'' or ''%'' on the beginning and '']'', '']'' or ''%'' on the end.
@@ Line 117: / Line 129: @@
 ==== Attribute 'src_ext' ====
 This attribute is similar to 'src'. But the link to remote data is defined externally. Value of 'src_ext' contains a name, which must begin with ''json_''. For example, 'our_document' contains:
 <code>
@@ Line 133: / Line 146: @@
 ==== Attribute 'src_path' ====
-If attribute 'src_path' is specified, then only part of database referenced by 'src' attribute is used. Path on 'src' specified by 'src_path' must exist. Rules for 'src_path' are the same as for 'path', except modifiers are not used.
+If attribute ''src_path'' is specified, then only part of database referenced by 'src' attribute is used. Path on 'src' specified by 'src_path' must exist. Rules for 'src_path' are the same as for 'path', except modifiers are not used.
 ==== Attribute 'src_path_ext' ====
 This attribute is similar to 'src_path', but the value is defined externally in query string. It works the same way as attribute 'src_ext'.
 ==== Attribute 'display' ====
 This attribute controls, which part of %%<json>%% element is rendered on html page. Multiple data can be displayed with jQuery UI Tabs widget. Attribute 'display' is a comma separated list of tokens. Default value for this attribute is specified in configuration setting 'json_display'. Tokens:
   * 'original' - display data already in database combined with data from 'src' attribute. But not yet combined with 'inline' data.
@@ Line 162: / Line 178: @@
 ==== Attribute 'archive' ====
-This attribute enables us to make archive of the JSON database loaded by 'src' or 'src_ext' attribute. Archive is stored into Dokuwiki page itself as JSON string. This action is triggered, when user presses a button.
-We can specify 'archive' attribute for each %%<jsonxxx>%% element on the page. We can specify 'archive=make' or 'archive=disable'. If at least one %%<jsonxxx>%% element has 'archive' attribute equal to 'make' or 'disable', then button 'Archive JSON database' appears on the top of Dokuwiki page. When user presses that button, following procedure is triggered:
+This attribute enables us to make archive of the JSON database loaded by 'src' or 'src_ext' attribute. Archive is stored into DokuWiki page itself as JSON string. This action is triggered, when user presses a button.
+We can specify 'archive' attribute for each %%<jsonxxx>%% element on the page. We can specify 'archive=make' or 'archive=disable'. If at least one %%<jsonxxx>%% element has 'archive' attribute equal to 'make' or 'disable', then button 'Archive JSON database' appears on the top of DokuWiki page. When user presses that button, following procedure is triggered:
   - Verify for errors: user permission, file unmodified, lock, etc.
-  - Search Dokuwiki page and find all ''%%<jsonxxx archive=make ...>%%'' elements. Replace them with ''%%<jsonxxx archive='%%/JSON_encoded_string/%%' ...>%%''.
+  - Search DokuWiki page and find all ''%%<jsonxxx archive=make ...>%%'' elements. Replace them with ''%%<jsonxxx archive='%%/JSON_encoded_string/%%' ...>%%''.
   - Find all ''%%<jsonxxx archive=disable src=... src_ext=...>%%'' elements and replace them with ''%%<jsonxxx archive_disabled=disable src_disabled=... src_ext_disabled=...>%%''. This disables 'src' and 'src_ext' attributes.
-  - Save the Dokuwiki page.
+  - Save the DokuWiki page.
-When Dokuwiki page is archived, then 'archive' attribute of some or all %%<jsonxxx>%% elements contains JSON database. Data is then read from 'archive' attribute. 'src' and 'scr_ext' attributes are then ignored. Inline JSON data remain unchanged.
+When DokuWiki page is archived, then 'archive' attribute of some or all %%<jsonxxx>%% elements contains JSON database. Data is then read from 'archive' attribute. 'src' and 'scr_ext' attributes are then ignored. Inline JSON data remain unchanged.
@@ Line 179: / Line 196: @@
 %$path [(table_row_filter)] {header} #format# (filter)%
 </code>
-Each of: path, row_filter, header, format, filter is optional. Order of the brackets is important. If square brackets are used, then table will be rendered. Else if curly brackets are used, then list will be rendered. Otherwise single variable will be rendered. If special character must be used inside the pattern, then use [[https://www.ascii.cl/htmlcodes.htm|HTML code]]. Use ''&#37;'' instead of ''%'', for example.
+Each of: ''[[#path]]'', ''[[#table_row_filter]]'', ''[[#header]]'', ''[[#format]]'', ''[[#filter]]'' is optional. Order of the brackets is important. If square brackets are used, then table will be rendered. Else if curly brackets are used, then list will be rendered. Otherwise single variable will be rendered. If special character must be used inside the pattern, then use [[https://ascii.cl/htmlcodes.htm|HTML code]]. Use ''&#37;'' instead of ''%'', for example.
 ==== path ====
 'path' specifies part of the 'json_database', which will be rendered. ''.'' (dot) is used as a delimiter between tokens. Path may contain spaces, no quotes should be used. Following characters are not allowed inside path: '[]{}#()'. There are two special tokens, which may be used as part of the path: ''__FIRST__'' selects the first element inside the array and ''__LAST__'' selects the last element inside he array.
 ==== table_row_filter ====
 Square brackets will render table. //table_row_filter// inside brackets is optional. It will display each row of the table, if filter is matched. Rules are the same as for filter below.
 ==== header ====
 //header// is a comma separated list of ''key:value'' pairs, where ''key'' is a header description and ''value'' is a path to variable. It is used to render a header in a table or in a list of properties.
@@ Line 196: / Line 218: @@
 If we want to use one tooltip for whole table row, then we use just ''_tooltip_'' string for the ''key''.
 ==== format ====
 Format may be applied on any variable, list item or table column. It can render value of the variable to format other than text. Supported formats are:
   * ''code'' - render variable as json code.
@@ Line 204: / Line 228: @@
   * ''email'' - render as email address. Variable may have title specified.
   * ''media?L200x300'' - render as internal or external media file. ''?'' and parameters are optional. First letter for parameter must be 'l' for left, 'c' for center or 'r' for right position of the media file. Other part of parameter is width x height. Parameter may also be just 'linkonly'. Variable may have title specified.
-  * ''rss n nosort reverse author date details'' - Render as rss. Rules are the same as for [[https://www.dokuwiki.org/wiki:syntax#rss_atom_feed_aggregation|Dokuwiki syntax]].
+  * ''rss n nosort reverse author date details'' - Render as rss. Rules are the same as for [[wiki:syntax#rss_atom_feed_aggregation|DokuWiki syntax]].
   * ''ejs?''//''template''// - Use [[https://ejs.co/|Embedded JavaScript templating]]. EJS will render data according to the //''template''// with usage of the powerful javaScript language. This option must be enabled in configuration settings, it is disabled by default. //''template''// is a string designed according to the rules for ejs, for example ''<$=d.toUpperCase()$>''. Variable (data) is passed to javaScript as ''d''. Because of string limitations not all characters may be passed to the template directly: characters ''%'', ''#'', '':'', '','', ''<%='' and ''%>'' must be written as ''&percnt;'', ''&num;'', ''&colon;'', ''&comma;'', ''<$='' and ''$>''.
 Format may be used to render single variable or specific member of list or specific table column. For list or table, format must be a comma separated list of key:value pairs, where key is header description (same as in //header//) and value is format.
 ==== filter ====
 Filter may be applied inside brackets on any variable, list or table. If it evaluates to true, contents of the variable will be shown, otherwise not. Filter consists of one or multiple conditions separated by keywords ''or'' or ''and''. Condition is a path compared to some value(string, numeric, boolean or null). Comparison operators are: ''=='', ''!='', ''<'', ''>'', ''%%<=%%'' or ''>=''. Comparison operator and value may also be omitted. There is no precedence or brackets possible. Quotes should not be used.
 ==== Examples ====
@@ Line 227: / Line 254: @@
 | **Table with filter** | ''%%%$path.to.var [(subvar.in.row == something)] { ... }%%%'' | Same as above, but only those rows will be rendered, which match the filter. |
 | **Conditionally hide section** | ''%%%$-start (path.to.cond1 == true)%%%''//''dokuwiki-contents''//''%%%$end%%%'' | Evaluate //filter// inside brackets. If true, then any //dokuwiki-contents// will be normally rendered. If false, then //dokuwiki-contents// will be hidden and if //dokuwiki-contents// contains title, it won't be shown in TOC. |
-| **Conditionally hide inline text** | ''%%%$-starti ( ... )% ... %$end%%%'' | Same as above, but for inline Dokuwiki contents. Mind extra 'i' in 'starti'. |
+| **Conditionally hide inline text** | ''%%%$-starti ( ... )% ... %$end%%%'' | Same as above, but for inline DokuWiki contents. Mind extra 'i' in 'starti'. |
 ===== Data snippets inside inline JSON =====
 <code>
 <json path=renault>{
@@ Line 241: / Line 269: @@
 If data is string, then double quotes must be used. Strings can also be concatenated. For example, ''%%"%$path.name%, %$path.age% years"%%'' can be used for json string concatenated from two predefined strings.
 ==== Insert referenced data into array elements ====
 This is advanced feature. Let's say, we have two data definitions: one for items database and one for item purchase history. For example:
 <code>
@@ Line 275: / Line 305: @@
 %$path[(row_filter){property.path: data.path.1.{reference.path}.data.path.2, ...}](filter)%
 </code>
 ===== Text macros =====
-Json define ''%%<json ...> ... </json>%%'' or extract ''%%%$ ... %%%'' patterns can be quite verbose and some lengthy attributes may repeat across multiple pages.
-It is possible to use macros defined by [[https://www.dokuwiki.org/plugin:textinsert|textinsert Plugin]]. First install the plugin, then define some macros in it. Use ''%%#@macro_name@#%%'' patterns inside json define or extract patterns. Json define or extract patterns are preprocessed for simple replacement of macros defined globally by textinsert Plugin.
+JSON define ''%%<json ...> ... </json>%%'' or extract ''%%%$ ... %%%'' patterns can be quite verbose and some lengthy attributes may repeat across multiple pages.
+It is possible to use macros defined by [[plugin:textinsert|textinsert Plugin]]. First install the plugin, then define some macros in it. Use ''%%#@macro_name@#%%'' patterns inside json define or extract patterns. JSON define or extract patterns are preprocessed for simple replacement of macros defined globally by textinsert Plugin.
 For example, if macro ''table_header'' is defined as ''%%{"Part description": part, "Quantity of parts": quantity}%%'', then you can use ''%%%$data [] #@table_header@# %%%''.
@@ Line 285: / Line 317: @@
 ===== Use JavaScript widgets with JSON data =====
-JSON plugin has interface for other sub-plugins, which can use JSON data inside JavaScript widgets for example. It is relative simple to write such a plugin. For example [[https://www.dokuwiki.org/plugin:jsoneditor|JSONEditor]] plugin uses nice [[https://json-editor.github.io/json-editor/|JSON Schema based Editor]] JavaScript library, which generates forms based on JSON Schema. It uses ''<jsoneditor>'' element, which is first rendered by JSON plugin. Jsoneditor plugin has only helper.php script, which renders some additional html code into page. Data from the JSON database are already available for the widget as well as data saving mechanism.
+JSON plugin has interface for other sub-plugins, which can use JSON data inside JavaScript widgets for example. It is relative simple to write such a plugin. For example [[plugin:jsoneditor|JSONEditor]] plugin uses nice [[https://json-editor.github.io/json-editor/|JSON Schema based Editor]] JavaScript library, which generates forms based on JSON Schema. It uses ''<jsoneditor>'' element, which is first rendered by JSON plugin. JSONeditor plugin has only helper.php script, which renders some additional html code into page. Data from the JSON database are already available for the widget as well as data saving mechanism.
 ===== Remote access to JSON data =====
-DokuWiki has a [[https://www.dokuwiki.org/devel:xmlrpc|XML-RPC API]] which can be used to access/interact with your wiki from other applications.
+DokuWiki has a [[devel:xmlrpc|XML-RPC API]] which can be used to access/interact with your wiki from other applications.
 ==== Available Functions ====
+=== plugin.json.get ===
 ^ Name | **plugin.json.get** |
 ^ Description | Generate JSON database on page and return data from the JSON_path. |
-^ Parameter (string) pagename | Dokuwiki [[https://www.dokuwiki.org/pagename|page name]]. |
+^ Parameter (string) pagename | DokuWiki [[:pagename|page name]]. |
 ^ Parameter (string) JSON_path | Path on the JSON database, see [[#attribute_path]]. Optional parameter, empty by default. |
 ^ Parameter (boolean) addLog | If true, additional information about JSON generation will be returned. Optional parameter, false by default. |
 ^ Return (object) | {'status': 'OK_or_error_description', 'data': 'JSON_data', 'log': 'JSON_loading_log' } |
+=== plugin.json.set ===
 ^ Name | **plugin.json.set** |
 ^ Description | Find ''<json id=...'' element inside page and set its inline data. |
-^ Parameter (string) pagename | Dokuwiki [[https://www.dokuwiki.org/pagename|page name]]. |
+^ Parameter (string) pagename | DokuWiki [[:pagename|page name]]. |
 ^ Parameter (string) json_id | Id of the json element, see [[#attribute_id]]. |
 ^ Parameter (array%%|%%string) data | Data to be put inside json element. Must be an array, empty string or valid JSON string. |
 ^ Parameter (boolean) overwrite | If true, existing data will be overwritten. Optional parameter, false by default. |
 ^ Return (string) | 'OK' on success or error description. |
+=== plugin.json.append ===
 ^ Name | **plugin.json.append** |
 ^ Description | Find ''<json id=...'' element inside page and append data to its inline database. Inline JSON data must be an array or empty. If empty, new array will be initialized. |
-^ Parameter (string) pagename | Dokuwiki [[https://www.dokuwiki.org/pagename|page name]]. |
+^ Parameter (string) pagename | DokuWiki [[:pagename|page name]]. |
 ^ Parameter (string) json_id | Id of the json element, see [[#attribute_id]]. If empty, complete page will be treated as JSON database (page must be a JSON array, empty or non-existent). |
 ^ Parameter (array%%|%%string) data | JSON Data to be appended inside json element. Must be an array or valid JSON string. |
 ^ Return (string) | 'OK' on success or error description. |
-==== Example usage with python ====
-First enable [[https://www.dokuwiki.org/devel:xmlrpc|Dokuwiki's XML-RPC API]] as described. See also [[https://python-dokuwiki.readthedocs.io/en/latest/|python-dokuwiki]].
+==== Example usage with Python ====
+First enable [[devel:xmlrpc|DokuWiki's XML-RPC API]] as described. See also [[https://python-dokuwiki.readthedocs.io/en/latest/|python-dokuwiki]].
 <code python>#pip install dokuwiki
 import dokuwiki
@@ Line 322: / Line 368: @@
 person = {'firstName': 'James', 'lastName': 'Smith', 'age': 40}
-wiki.send("plugin.json.set", "path:to:page", "id_attr", person)</code>
+wiki.send("plugin.json.set", "path:to:page", "id_attr", person)
+</code>