User Tools

Site Tools


docs:adminman

Differences

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

Link to this comparison view

docs:adminman [2017/09/19 16:31] (current)
Line 1: Line 1:
 +====== Admin manual ======
 +===== Design =====
 +Loki was designed as an extension of the [[http://​www.dokuwiki.org/​dokuwiki|DokuWiki]]. There are a lot of wiki engines avaliable on the Internet. There are many different conceptions. Many of them are similar, but there are plenty differences in wikitext syntax, implementation or runtime enviroment. This is why, instead of designing another wiki system, the idea of using existing stable and tested wiki engine and concept of the implementation of the plugin to this system.
  
 +There are several kinds of plugins avaliable in DokuWiki:
 +  * ''​syntax plugins''​ - extending existing wikitext syntax
 +  * ''​admin plugins''​ - enhancing system management capabilities
 +  * ''​action plugins''​ - redefining selected core wiki operations, (eg. saving wikipages)
 +  * ''​renderer plugins''​ - allowing to create new export modes (possibly replacing the standard XHTML renderer)
 +  * ''​helper plugins''​ - providing other plugins some common features
 +
 +Loki is implemented as a syntax plugin and renderer plugin. Figure below shows how Loki works:
 +
 +{{ .:​loki-arch.png?​550 |Loki architecture}}
 +
 +According to the standard operation procedure of DokuWiki, text received on input is fed to lexical analyser (Lexer) which identifies the special wiki markups. Found markups are translated into instructions for renderer and parsed by the parser. The processed text is displayed by the renderer so that the page can be viewed by the user. Loki is integrated with this system at the phase of the lexical and renderer analysis. Loki extends basic DokuWiki syntax by adding ''<​pl>​...</​pl>''​ tags. Plugin translates informations indluded between these tags to data and commands which can be interpreted by Prolog engine. These data are saved on the server hard drive in special files (one file per one wiki page), and commands are processed by SWI-Prolog. Results are rendered and displayed on the wiki page. In a similar way Loki supports Semantic MediaWiki markups.
 +
 +===== Implementation =====
 +**Syntax plugin** - ''​syntax.php''​ - contains definition of ''​syntax_plugin_prolog''​ class which is responsible for searching and processing prolog annotations in DokuWiki text. There are implemented folloging methods:
 +
 +^ Name ^ Description^
 +|''​getType()''​|Returns the type of syntax that Loki plugin defines. Loki syntax is ''​protected''​ type which means that content of Loki tags should not be futher processed (like ''<​code>''​ or ''<​html>''​ tags).|
 +|''​getSort()''​|Returns a number determining priority. It is important when the charset matches to the number of patterns.|
 +|''​connectTo($mode)''​|In this method the pattern of input is added. In this place plugin informs lexical analyser that content of ''<​pl>''​ tags should be processed by Loki.|
 +|''​postConnect()''​|In this method pattern informing when the parser is leaving syntax mode is defined. For Loki this is ''</​pl>''​.|
 +|''​handle($match,​ $state, $pos, &​$handler)''​ |Method responsible for preparing the matched syntax for use in the renderer|
 +|''​renderer($mode,​ &​$renderer,​ $data)''​ |Method used to render the content.|
 +
 +**Renderer plugin** - ''​renderer.php''​ - contains definition of ''​renderer_plugin_prolog''​ class. Renderer plugin extends standard DokuWiki renderer, and enriches DokuWiki syntax. It is also responsible to saving prolog data on hard drive. Avaliable methods:
 +
 +^ Name ^ Description^
 +|''​canRender($format)''​|Allows Loki to be default XHTML DokuWiki visualizer|
 +|''​document_start()''​|This method is executed at the beginning of the page rendering process and it prepares necessary file paths.|
 +|''​header($text,​ $level, $pos)''​|Method executed when renderer reaches header markup and it supports standard DokuWiki header servicing as well as additional code responsible for gathering knowledge about headers on particular Wiki pages.|
 +|''​internallink($id,​ $name=NULL, $search=NULL,​ $returnonly=false,​ $linktype='​content'​)''​|enriches standard DokuWiki internal link servicing with possibility of defining, relations, attributes and categories, as well as in case of header method mechanism for gathering knowledge about internal links on Wiki pages.|
 +|''​externallink($url,​ $name=NULL)''​|This method renders external links on the page and translates them to Prolog code.|
 +|''​internalmedia($src,​ $title=NULL,​ $align=NULL,​ $width=NULL,​ $height=NULL,​ $cache=NULL,​ $linking=NULL)''​|This method is responsible for rendering links to files and supports queries in SMW syntax. Function calls queries with SWI-Prolog engine and displays results on the page as internal links.|
 +
 +Moreover, both classes includes following method:
 +  * ''​getInfo()''​ - Returns information about plugin and author. Obligatory function of DokuWiki extensions.
 +
 +**Prolog rules** - ''​loki.pl''​ - implements two-way Loki interface. It includes prolog rules allowing to load and print the data stored in wiki. It allows to select range of data being read. Rules defined in this file:
 +  * ''​wikiconsult/​1'',​ ''​list/​0'',​ ''​list/​1''​ - called from wiki level
 +  * ''​shell_wikiconsult/​0'',​ ''​shell_list/​0'',​ ''​shell_list/​1''​ - called from console level.
 +
 +''​wikiconsult''​ rules saves informations inluded in files with prolog data of wiki pages (''​txt''​ files) to temporary file ''​tempfile.pl''​. After then ''​consult(tempfile).''​ is called.
 +''​list''​ rules calls ''​listing''​ command for part of or all loaded data.
 +
 +**Wiki text editor toolbar** - ''​script.js''​ - Wiki text editor toolbar is extended by some new icons (ASK queries, SPARQL queries, Prolog queries etc.).
 +
 +{{ .:​loki-toolbar.png?​800 |}}
 +
 +**Action plugin** - ''​action.php''​ - The action plugins are kind of extensions of DokuWiki that trigger defined by authors functions in response to some occuring events. All of action plugins registers inside ''​register(&​$controller)''​ function event and function (which has to be executed while that event occurs). It is done through calling:
 +<​code>​$controller->​register_hook(<​EVENT NAME>, <​BEFORE/​AFTER>,​$this,​ <celled function>,​ <​parameters<​del>​Strike-through Text</​del>>​);</​code>​
 +Loki action plugin uses the ''​ACTION_ACT_PREPROCESS''​ event. It means that defined function is called every time when on wiki page any action is performed (including refreshing the wiki pages). In Loki action plugin is used to export wiki page to RDF file by using ''​exportrdf''​ action.
 +
 +**Used directories**.
 +  * ''​conf''​ - directory containing configuration files. It contains following files:
 +      * ''​metadata.php''​ - This file defines configuration parameters, their names and types.
 +      * ''​default.php''​ - This file contains dafault values for defined parameters. In this place there is configuration parameter allowing to set number of page levels which are exported to RDF.
 +  * ''​lang''​ - directory containing language files. Allows to display text according to DokuWiki language settings. In ''​lang''​ directory there are directories which names are language symbols (eg. pl, en, ru, de, etc). There are two languages avaliable in Loki: polish (''​pl''​) and english (''​en''​).
 +  * ''​utl''​ - directory containing Loki utility files
 +    * ''​loki_utl.php''​ - this file defines ''​LokiUtl''​ class which includes basic functions used in Loki:
 +        * ''​call_prolog($goal,​ $scope="​*",​ $hash=NULL)''​ - function calling prolog engine with the specified goal. Allows to specify data range and ''​hash''​ file, where this data are located. When ''​hash=NULL''​ function itself collects semantic data located in given range. When parameter ''​hash''​ is defined, time of search operation is much shorter.
 +        * ''​recursive_mkdir($path,​ $mode=0777)''​ - Creates necessary directories on hard drive with appropriate permissions.
 +        * ''​isort($a,​ $b)''​ - Sorts two texts ignoring lowercase and uppercase letters.
 +        * ''​is_attribute($property,​ $hash=NULL)''​ - checks if the property is an attribute (it means, if it is used in wiki as second parameter of ''​wiki_attribute/​3''​ predicate)
 +        * ''​is_relation($property,​ $hash=NULL)''​ - checks if the property is an relation (it means, if it is used in wiki as second parameter of ''​wiki_relation/​3''​ predicate)
 +    * ''​loki_utl_ask.php''​ - This file defines ''​LokiUtlAsk''​ class. This class supports SMW ''#​ask''​ queries. Content (two public functions):
 +        * ''​function process_ask($fulltask)''​ - Function processing ''#​ask''​ queries. As a parameter it takes the full text of query (written on wiki page by user). Function returns array which includes: query result as a two-dimensional array, array of results headers and their parameters, query options and goal in Prolog used for searching pages consistent with the results.
 +        * ''​function prepare_format($options)''​ - Returns array of HTML tags used to display results on page. As the ''​$options''​ parameter, query options array received by using ''​process_ask''​ function, should be given.
 +    * ''​loki_utl_rdf.php''​ - this file defines ''​LokiUtlRdf''​ class. Contains one function:
 +        * ''​export_rdf($pageid,​ $maxlevels)''​ - Translates semantic data on ''​pageid''​ page and associated pages up to ''​maxlevel''​ level, to RDF/XML format.
 +    * ''​loki_utl_sparql.php''​ - this file defines ''​LokiUtlSparql''​ class.
 +        * ''​process_sparql($fullquery)''​ - Receives full SPARQL query text and returns query result which is formated and can be displayed on a web page.
 +    * ''​loki_utl_special.php''​ - this file defines ''​LokiUtlSpecial''​ class. Special pages support.
 +        * ''​list_categories()''​ - Returns list of all categories used in wiki.
 +        * ''​list_relations()''​ - Returns list of all relations used in wiki.
 +        * ''​list_attributes()''​ - Returns list of all attributes used in wiki.
 +        * ''​list_category_uses($category)''​ - Returns list of all pages that belongs to given category.
 +        * ''​list_relation_uses($relation)''​ - Returns list of all pages that contains defined relation and its values for this pages.
 +        * ''​list_attribute_uses($attribute)''​ -  Returns list of all pages that contains defined attribute
 +
 +===== Files created by users =====
 +Sometimes there is possibility to create aditional file on the server hard drive.
 +==== Prolog ====
 +First possibility is to create file related with current DokuWiki page. It can help to built the knowledge base. All code between ''<​pl>​...</​pl>''​ tags with ''​cache=“true”''​ option will be saved in this file. Example: ​
 +<​code>​
 +<pl cache="​true">​
 +woman(kate).
 +woman(ann).
 +man(eric).
 +</pl>
 +</​code>​
 +
 +To refer to created file use scope option in ''<​pl>​...</​pl>''​ tag. Example:
 +
 +<​code><​pl goal="​woman(X),​write(X),​nl,​fail."​ scope="​prolog:​examples"></​pl></​code>​
 +
 +This code will be replaced with a result as in the first example from [[http://​loki.ia.agh.edu.pl/​lokidev/​manual:​userman#​prolog_in_dokuwiki|User Manual]] but knowledge base will be builded from all files related with pages in namespace given in scope parameter. This mechanism allows to combine knowledge from different pages. ​
 +
 +==== Debugging ====
 +Sometimes there could be useful to save result of debugging in file. Using debugging functions was described in [[http://​loki.ia.agh.edu.pl/​lokidev/​manual:​userman#​debug_functions|User Manual]]. Loki allows one more option in using ''​msgerr''​ parameter :
 +  * ''​tofile''​ - Error messages are written to a file on the server. The file is saved in ''​$DOKU_HOME/​lib/​plugins/​tmp''​. Avaliable only for administrator.
 +Example:
 +<​code><​pl goal="​invalid_goal"​ scope="​*"​ msgerr="​tofile"></​pl></​code>​
 +Result will be saved on file located in ''​$DOKU_HOME/​lib/​plugins/​tmp''​.
 +
 +===== Download and Installation =====
 +Loki is developed as a plugin to the [[http://​www.dokuwiki.org/​dokuwiki|Dokuwiki]] system. Download and install Loki following the instructions given below.
 +==== Requirements ====
 +  * Working [[http://​www.dokuwiki.org/​dokuwiki|Dokuwiki]] installation (in Unix environment)
 +  * SWI [[http://​www.swi-prolog.org/​|SWI Prolog]] and [[http://​curl.haxx.se/​|cURL]] library
 +==== Download ====
 +Avaliable Loki sources:
 +  * Public URL: http://​loki.ia.agh.edu.pl/​download/​loki.zip
 +  * CVS: **For authorized users** the Loki may be obtained from [[http://​geist.agh.edu.pl/​prv:​tech:​cvs|GEIST CVS]] repository: cvs co loki
 +==== Installation ====
 +You can install Loki using [[http://​www.dokuwiki.org/​plugin:​plugin|Plugin Manager]] of your Dokuwiki installation or manually by unpacking downloaded files to directory **$DOKUWIKI_HOME$/​lib/​plugins**.
 +==== Configuration ====
 +  * In [[http://​www.dokuwiki.org/​config|Administration/​Configuration]] settings of you Dokuwiki installation set **renderer_xhtml** option to Loki plugin.
 +  * Put the **loki.php** and **smw.php** files in the **$DOKUWIKI_HOME$/​inc/​geshi** directory (syntax highlighting).
docs/adminman.txt · Last modified: 2017/09/19 16:31 (external edit)