Differences

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

--- devel:metadata [2013-02-26 19:15] – 146.60.141.165
+++ devel:metadata [2023-02-28 07:43] (current) – Link to new dokuwiki repo saggi
@@ Line 11: / Line 11: @@
 ===== Metadata Renderer =====
-Info in the ''meta'' directory is initially written by the metadata renderer. It creates a parallel file for each page named ''$id.meta'' in the ''meta'' directory. The file is a serialized multi-dimensional PHP array whose keys follow the [[http://dublincore.org/|Dublin Core]] element names.
+Info in the ''meta'' directory is initially written by the metadata renderer. It creates a parallel file for each page named ''<pageid>.meta'' in the ''meta'' directory. The file is a serialized multi-dimensional PHP array whose keys follow the [[http://dublincore.org/|Dublin Core]] element names.
 ==== Data Structure ====
@@ Line 17: / Line 17: @@
 Currently, the following metadata is saved by the core metadata renderer:
-  * 'title' -- string, first heading
+  * ''title'' -- string, first heading
-  * 'creator' -- string, full name of the user who created the page
+  * ''creator'' -- string, full name of the user who created the page
-  * 'user' -- string, the login name of the user who created the page
+  * ''user'' -- string, the login name of the user who created the page
-  * 'description' -- array
+  * ''description'' -- array
-    * 'abstract' -- raw text abstract (250 to 500 chars) of the page
+    * ''abstract'' -- raw text abstract (250 to 500 chars) of the page
-    * 'tableofcontents' -- array, list of header id ('hid'), title ('title'), list item type ('type') and header level ('level')
+    * ''tableofcontents'' -- array, list of arrays with header id ('hid'), title ('title'), list item type ('type') and header level ('level')
-  * 'contributor' array, list of user ID => full name of users, who have contributed to the page
+  * ''contributor'' array, list of user ID => full name of users, who have contributed to the page
-  * 'date' -- array
+  * ''date'' -- array
-    * 'created' -- timestamp, creation date
+    * ''created'' -- timestamp, creation date
-    * 'modified'-- timestamp, date of last non-minor modification
+    * ''modified''-- timestamp, date of last non-minor modification
-    * 'valid'
+    * ''valid''
-      * 'age' -- seconds, period in seconds before the page should be refreshed (used by 'rss' syntax only)
+      * ''age'' -- seconds, period in seconds before the page should be refreshed (used by 'rss' syntax only)
-  * 'last_change' -- array, the last changelog entry
+  * ''last_change'' -- array, the last changelog entry
-    * 'date' -- timestamp, date of the last change
+    * ''date'' -- timestamp, date of the last change
-    * 'ip' -- ip of the user editing
+    * ''ip'' -- ip of the user editing
-    * 'type' -- type of the edit (C create, E edit, e minor edit, D delete, R revert)
+    * ''type'' -- type of the edit (C create, E edit, e minor edit, D delete, R revert)
-    * 'id' -- id of the page
+    * ''id'' -- id of the page
-    * 'user' -- username of the user editing
+    * ''user'' -- username of the user editing
-    * 'sum' -- summary of the editor
+    * ''sum'' -- summary of the editor
-    * 'extra' -- extra data, used for storing the revision (timestamp) in the case of a revert
+    * ''extra'' -- extra data, used for storing the revision (timestamp) in the case of a revert
-  * 'relation' -- array
+  * ''relation'' -- array
-    * 'isreferencedby' -- array, list of pages that link to this page: ID => boolean exists, this is not used or written by DokuWiki core
+    * ''isreferencedby'' -- array, list of pages that link to this page: ID => boolean exists, this is not used or written by DokuWiki core
-    * 'references' -- array, list of linked pages: ID => boolean exists
+    * ''references'' -- array, list of linked pages: page ID => boolean exists
-    * 'firstimage' -- id or url of the first image in the page
+    * ''media'' -- array, list of linked media files: media ID => boolean exists
-    * 'haspart' -- array, list of included rss feeds (and more, see below)
+    * ''firstimage'' -- id or url of the first image in the page
-  * 'internal' -- array
+    * ''haspart'' -- array, list of included rss feeds (and more, see below)
-    * 'cache' -- boolean, if the cache may be used
+  * ''internal'' -- array
-    * 'toc' -- boolean, if the toc shall be displayed
+    * ''cache'' -- boolean, if the cache may be used
+    * ''toc'' -- boolean, if the toc shall be displayed
 Additionally, plugins can support more metadata elements. Currently used:
-  * 'relation' -- array
+  * ''relation'' -- array
-    * 'haspart' -- array, list of included pages: ID => boolean exists ([[plugin:include]] plugin) or rss feeds
+    * ''haspart'' -- array, list of included pages: ID => boolean exists ([[plugin:include]] plugin) or rss feeds
-  * 'subject' -- array, lists of tags ([[plugin:tag]] plugin, [[plugin:blogtng]] plugin, [[plugin:flattr]] plugin); this is used by ''feed.php'', if present
+    * ''odt'' -- array, list with properties for [[plugin:ODT]] plugin
-  * 'type' -- string, 'draft' for drafts ([[plugin:blog]] plugin)
+      * ''template'' -- media id of ODT-file used as template
-  * 'geo' -- array, list of geographic tags ([[plugin:geotag]], [[plugin:openlayersmap]] plugin)
+  * ''subject'' -- array, lists of tags ([[plugin:tag]] plugin, [[plugin:blogtng]] plugin, [[plugin:flattr]] plugin); this is used by ''feed.php'', if present
+  * ''type'' -- string, 'draft' for drafts ([[plugin:blog]] plugin)
+  * ''geo'' -- array, list of geographic tags ([[plugin:geotag]], [[plugin:openlayersmap]], [[plugin:socialcards]] and [[plugin:spatialhelper]] plugins)
+    * ''lat'' -- number, latitude of this location in decimal degrees
+    * ''lon'' -- number, longitude of this location in decimal degrees
+    * ''alt''  -- number, altitude in meter above sea level
+    * ''region'' -- string, region of this location, eg. a province or state
+    * ''country'' -- string, the country of this location
+    * ''placename'' -- string, placename describing this location or area
+    * ''geohash'' -- string, geohash of this location
 It's recommended to use keys from the [[http://dublincore.org/documents/dces/|Dublin Core element set]] for any metadata that might be interesting for external use.
+For plugin internal data it is recommended to store your keys under the ''plugin'' key:
+  * ''plugin'' -- array, contains keys for all plugins storing metadata
+    * ''yourplugin'' -- array, the keys you need for your plugin
 This data is stored in an associative array with two keys: 'current' for all current data (including persistent one), 'persistent' for data that shall be kept over metadata rendering.
@@ Line 69: / Line 84: @@
 ==== Running of metadata rendering ====
-The metadata rendering is only started by the ''[[xref>p_get_metadata]]'' and ''[[xref>p_set_metadata]]''. This differs from the xhtml renderer. The wikipage parsing process has two stages: generation of the instructions by the [[devel:parser#handler|Handler]] and next the generation of xhtml output with these instructions as input. As all [[devel:parser#renderer|Renderers]] the metadata renderer uses the same instructions as input. In the metadata renderer the metadata can directly be accessed at ''renderer%%->%%meta'' and ''renderer%%->%%persistent''. The metadata creates also an abstract, raw text abstract from the rendered instruction can be added by <code php>
+The metadata rendering is only started by the ''[[xref>p_get_metadata()]]'' and ''[[xref>p_set_metadata()]]''. This differs from the xhtml renderer. The wikipage parsing process has two stages: generation of the instructions by the [[devel:parser#handler|Handler]] and next the generation of xhtml output with these instructions as input. As all [[devel:parser#renderer|Renderers]] the metadata renderer uses the same instructions as input. In the metadata renderer the metadata can directly be accessed at ''renderer%%->%%meta'' and ''renderer%%->%%persistent''. Some examples and bit of explanation can be found at [[devel:syntax_plugins#render_method|syntax plugins development documentation]].
-//capture only the first few sections, is switched off by eg. section metarenderer
+The metadata renderer creates also an short raw text abstract. The abstract is created from the rendered instruction by adding compact text without html to ''$this%%->%%doc''. Use the ''$this%%->%%capture'' to check whether the renderer still collects text for the abstract.
+<code php>
+// capture only the first few sections.
+// Is switched off as well by eg. section metarenderer
 if ($this->capture){
     if($linktitle) {
@@ Line 79: / Line 98: @@
 }
 </code>
-The timing is thus not equal to xhtml renderer, but depends on render flags given to the ''p_get_metadata'' and the [[#Metadata and caching|cache status]]. The logic here is to guarantee the metadata renderer is running when needed, but not unnecessary. Read more about render flags in [[#functions to Get and Set Metadata]] below.
+The timing is thus not equal to xhtml renderer, but depends on render flags given to the ''p_get_metadata()'' and the [[#Metadata and caching|cache status]]. The logic here is to guarantee the metadata renderer is running when needed, but not unnecessary. Read more about render flags in [[#functions to Get and Set Metadata]] below.
 ==== Metadata and Plugins ====
@@ Line 93: / Line 113: @@
 Note that persistent metadata is never cleaned and always used as basis for the current metadata so when switching from persistent to non-persistent metadata in a plugin make sure you implement a cleanup routine which removes persistent metadata from your plugin whenever it exists. For this reason non-persistent metadata should also be preferred whenever possible.
-If you want to make sure that your plugins metadata doesn't interfere with other plugins or DokuWiki itself consider using ''plugin_$plugin'' as prefix/top level key (especially for persistent metadata, current metadata that fits in the Dublin Core element set should be stored as outlined above).
+If you want to make sure that your plugin's metadata doesn't interfere with other plugins or DokuWiki itself consider using ''plugin_$plugin'' as prefix/top level key (especially for persistent metadata, current metadata that fits in the Dublin Core element set should be stored as outlined above).
 As it is very difficult to cleanly update persistent metadata properties that are arrays from various places (in most cases you don't know which is old metadata that should be cleaned up and which is metadata from other plugins that should be kept - or not because the plugin was disabled) consider using keys that are unique to your plugin for this case and merge them manually into the current metadata using the [[.event:parser_metadata_render|PARSER_METADATA_RENDER]] event, that way you can for example store custom tags in the persistent metadata and add them to the ''subject'' metadata. Then your plugin's metadata also won't be used anymore when your plugin is disabled.
@@ Line 113: / Line 133: @@
   * ''[[xref>p_set_metadata]]($id, $data, $render, $persistent)'' sets some properties in the metadata, uses the metadata inside the renderer when there is a renderer for the specified page.
     * ''$id'' is the ID of a wiki page; required
-    * ''$data'' is an array with key => value pairs to be set in the metadata, required. Note that here the keys are only keys for the top level, if the key is ''description'', ''data'' or ''contributor'' the value is expected to be an array and merged with the existing data, if the key is ''relation'', all sub-keys will be merged when there is existing array data for them.
+    * ''$data'' is an array with ''%%key => value%%'' pairs to be set in the metadata, required. Note that here the keys are only keys for the top level. If the key is ''description'', ''data'' or ''contributor'' the value is expected to be an array and merged with the existing data, if the key is ''relation'', all sub-keys will be merged when there is existing array data for them. Other keys are not merged as array, but just stored as value, which will overwrite eventually subkeys.
     * ''$render'' boolean, whether or not the page metadata should be generated with the renderer before the metadata is set; optional, default is false
     * ''$persistent'' a boolean which indicates whether or not the particular metadata value will persist through the next metadata rendering.  The default value is true.
@@ Line 139: / Line 159: @@
 Example for getting the ids of all pages that link to a certain page: <code php>$result = idx_get_indexer()->lookupKey('relation_references', $id);</code> (note that this functionality including an ACL check is available as ''[[xref>ft_backlinks|ft_backlinks($id)]]'').
-For more advanced queries (like getting all values stored for a certain metadata property) can be needed to access the index files directly using ''[[xref>idx_getIndex]]'', feel free to suggest additional features for the metadata index in the [[https://bugs.dokuwiki.org|bug tracker]].
+For more advanced queries (like getting all values stored for a certain metadata property) can be needed to access the index files directly using ''[[xref>idx_getIndex]]'', feel free to suggest additional features for the metadata index in the [[https://github.com/dokuwiki/dokuwiki/issues|bug tracker]].
 The [[plugin:tag]] plugin uses the metadata index, in its helper part there are example of how the index can be queried, in its action part you can see how the index is written.