This shows you the differences between two versions of the page.
docs:loki-tutorial [2017/09/19 14:31] |
docs:loki-tutorial [2022/03/23 16:59] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Loki using tutorial ====== | ||
+ | This is complete tutorial to usage of the Loki plugin by any DokuWiki user. It provides description of Loki features with functional examples. While reading this tutorial you will learn how to create simple Movies Knowledge Base in Loki. | ||
+ | |||
+ | ===== First steps ===== | ||
+ | Here we will show some new features you can see while working with the Loki for the first time. | ||
+ | |||
+ | ==== New options in UI ==== | ||
+ | The DokuWiki editor has its own Graphical User Interface for easier work with text. It's buttons are placed above the area of writing. Loki adds some new buttons to let you easily insert semantics into your text. All of them are listed below: | ||
+ | |||
+ | * First is the button with " | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * ''?'' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | Since they are just UI buttons for inserting the code, I don't describe how to use it. It will be covered later. | ||
+ | |||
+ | ==== Special pages ==== | ||
+ | Loki has special pages for every type of semantics it uses: | ||
+ | * categories page for listing all Categories | ||
+ | * relations page for listing all Relations | ||
+ | * attributes page for listing all Attributes | ||
+ | |||
+ | It also has groups of special pages associated with the three types mentioned before. For every attribute, relation and category used in our wiki we can create special page that describes it. After placing the attribute, relation or category in our article, we can create page like: '' | ||
+ | |||
+ | ===== Defining categories ===== | ||
+ | |||
+ | Let's start with simple example. In this case it will be small knowledge base of the movies and persons related to them. First we will create few pages containing only categories and titles of the movies. Then we will go further and add some details to our pages. | ||
+ | |||
+ | The movie base will be kept in the '' | ||
+ | |||
+ | Let's provide first semantic information into this page. '' | ||
+ | |||
+ | <code loki> | ||
+ | |||
+ | We can also change the display of the category name, by placing our custom text after '' | ||
+ | |||
+ | <code loki>It is one of the [[category: | ||
+ | |||
+ | If you don't want to show link to the category in the text just simply put space as a custom display: | ||
+ | |||
+ | <code loki> | ||
+ | |||
+ | In that case category tag can be placed anywhere in the page text. The most popular are at the beginning and the end of text. | ||
+ | |||
+ | In the same way we will create three additional pages with movies from the Indiana Jones series: | ||
+ | |||
+ | * temple_of_dooom | ||
+ | * last_crusade | ||
+ | * kingdom_of_the_crystal_skull | ||
+ | |||
+ | All of them will have defined category '' | ||
+ | |||
+ | The final code of our movie page should look like this: | ||
+ | |||
+ | <code loki> | ||
+ | ==== Raiders of the Lost Ark ==== | ||
+ | |||
+ | [[category: | ||
+ | </ | ||
+ | |||
+ | ===== Defining attributes ===== | ||
+ | Attributes are used to define information included in the article. They relate to basic information that can be presented as a number, date or any other generic, non-unique data type. Attribute values itself have no meaning like: 2008 can be year as good as an amount of leaves growing on the tree. Any values that correspond to the objects that can be defined and are somehow original should be placed as relations (described later). That way we separate simple data, that would not have description from the complicated one. Also attributes should be used when we say that the object has some property like: length, weight, size and so on. In that case attributes are immanently in the subject (page). Relations are about different connections between the subject and object. They are placed outside of the subject and are another objects. | ||
+ | |||
+ | Let's continue with our movie base. Each movie has defined year of the production. It is sort of property. Then we can insert semantic notation into every movie page about the year it was produced. We will to this by placing tag: | ||
+ | |||
+ | <code loki> | ||
+ | |||
+ | Of course we can place it anywhere: in the sentence like above or just separately in the table with basic information on the movie. There is no difference for Loki. The name of the attribute can be any string. Also with spaces. It is important to remember that '' | ||
+ | |||
+ | Also here you can use '' | ||
+ | |||
+ | Now we will add another attributes to the movies: | ||
+ | * title - full title of the movie | ||
+ | * action_time - the time the action of the movie takes place | ||
+ | * action_place - the places where the action takes place | ||
+ | * language - primary language of the movie | ||
+ | |||
+ | In the case of the language we can define it as a relation to the language page, but for the purposes of this tutorial we will keep it like that. Same with the action place, which can be link to the countries and places. But the countries will be used as a relation in another example. | ||
+ | |||
+ | Loki does not allow for placing semantic tags inside another tags like headers. So our title of the movie will be defined below in the list of information. | ||
+ | |||
+ | Now our page '' | ||
+ | |||
+ | <code loki> | ||
+ | ==== Raiders of the Lost Ark ==== | ||
+ | |||
+ | **Title**: [[title: | ||
+ | |||
+ | **Production Year**: [[production_year: | ||
+ | |||
+ | **Action time**: [[action_time: | ||
+ | |||
+ | **Action place**: [[action_place: | ||
+ | |||
+ | **Language**: | ||
+ | |||
+ | [[category: | ||
+ | </ | ||
+ | |||
+ | ===== Defining relations ===== | ||
+ | While attributes are immanent information on the subject of the page, relations are representing connection of one object to another. Unlike the attributes, relations create links to target objects (pages), so we can easily jump to it. The power of the relations will be used in the queries for information later. For now it is important to give every page some relations to another pages. | ||
+ | |||
+ | In the case of our movies example we can define many relations with persons involved in production, i.e. cast, director and screenplay writers. | ||
+ | |||
+ | Adding relation is simple. For '' | ||
+ | |||
+ | <code loki> | ||
+ | |||
+ | Usually the relation name should be stated as sort of connection like '' | ||
+ | |||
+ | Notice that the page used here as a value of the relation is from another namespace. It is good way of organizing our pages. In the '' | ||
+ | |||
+ | Another important note is that we can define one relation type many times. That way we will tell that the page is related in the same way with other pages. The second relation of the same name does not overwrite the value of the first. It adds another one. | ||
+ | |||
+ | The value of the relation should always be written as shown above. We can also write it as: | ||
+ | |||
+ | <code loki> | ||
+ | |||
+ | In that way DokuWiki will create the link to the page '' | ||
+ | |||
+ | Usage of '' | ||
+ | |||
+ | In the case of movies we will add more relations: | ||
+ | * Genre - from '' | ||
+ | * Production country - from '' | ||
+ | * screenplay - the author(s) of the screenplay | ||
+ | * directed_by - director | ||
+ | * main_character - from '' | ||
+ | * supporting_role - like main_role | ||
+ | * supporting_character - like main_character | ||
+ | * series - from namespace '' | ||
+ | |||
+ | Fully created code of the page '' | ||
+ | |||
+ | <code loki> | ||
+ | ==== Raiders of the Lost Ark ==== | ||
+ | |||
+ | **Title**: [[title: | ||
+ | |||
+ | **Genre**: [[genre:: | ||
+ | |||
+ | **Production Year**: [[production_year: | ||
+ | |||
+ | **Production country**: [[produced_in_country:: | ||
+ | |||
+ | **Screenplay**: | ||
+ | |||
+ | **Directed by**: [[directed_by:: | ||
+ | |||
+ | **Cast**: | ||
+ | |||
+ | [[main_role:: | ||
+ | [[main_character:: | ||
+ | |||
+ | [[supporting_role:: | ||
+ | [[supporting_character:: | ||
+ | |||
+ | [[supporting_role:: | ||
+ | [[supporting_character:: | ||
+ | |||
+ | **Action time**: [[action_time: | ||
+ | |||
+ | **Action place**: [[action_place: | ||
+ | |||
+ | **Series**: [[series:: | ||
+ | |||
+ | **Language**: | ||
+ | |||
+ | [[category: | ||
+ | </ | ||
+ | |||
+ | Our page is ready. Now we will create some other pages for actors or directors to show the power of the semantic queries. But before that we need to insert other three movies from the Indiana Jones series. Below you will find prepared text with semantic code for those pages. | ||
+ | |||
+ | **temple_of_doom** | ||
+ | |||
+ | <code loki> | ||
+ | ==== Indiana Jones and the Temple of Doom ==== | ||
+ | **Title**: [[title: | ||
+ | |||
+ | **Genre**: [[genre:: | ||
+ | |||
+ | **Production Year**: [[production_year: | ||
+ | |||
+ | **Production country**: [[produced_in_country:: | ||
+ | |||
+ | **Screenplay**: | ||
+ | |||
+ | **Directed by**: [[directed_by:: | ||
+ | |||
+ | **Cast**: | ||
+ | |||
+ | [[main_role:: | ||
+ | [[main_character:: | ||
+ | |||
+ | [[supporting_role:: | ||
+ | [[supporting_character:: | ||
+ | |||
+ | [[supporting_role:: | ||
+ | [[supporting_character:: | ||
+ | |||
+ | **Action time**: [[action_time: | ||
+ | |||
+ | **Series**: [[series:: | ||
+ | |||
+ | **Language**: | ||
+ | |||
+ | [[category: | ||
+ | </ | ||
+ | |||
+ | **last_crusade** | ||
+ | |||
+ | <code loki> | ||
+ | ==== Indiana Jones and the Last Crusade ==== | ||
+ | |||
+ | **Title**: [[title: | ||
+ | |||
+ | **Genre**: [[genre:: | ||
+ | |||
+ | **Production Year**: [[production_year: | ||
+ | |||
+ | **Production country**: [[produced_in_country:: | ||
+ | |||
+ | **Screenplay**: | ||
+ | |||
+ | **Directed by**: [[directed_by:: | ||
+ | |||
+ | **Cast**: | ||
+ | |||
+ | [[main_role:: | ||
+ | [[main_character:: | ||
+ | |||
+ | [[supporting_role:: | ||
+ | [[supporting_character:: | ||
+ | |||
+ | [[supporting_role:: | ||
+ | [[supporting_character:: | ||
+ | |||
+ | **Action time**: [[action_time: | ||
+ | |||
+ | **Series**: [[series:: | ||
+ | |||
+ | **Language**: | ||
+ | |||
+ | [[category: | ||
+ | </ | ||
+ | |||
+ | **kingdom_of_the_crystal_skull** | ||
+ | |||
+ | <code loki> | ||
+ | ==== Indiana Jones and the Kingdom of the Crystal Skull ==== | ||
+ | |||
+ | **Title**: [[title: | ||
+ | |||
+ | **Genre**: [[genre:: | ||
+ | |||
+ | **Production year**: [[production_year: | ||
+ | |||
+ | **Production country**: [[produced_in_country:: | ||
+ | |||
+ | **Screenplay**: | ||
+ | |||
+ | **Directed by**: [[directed_by:: | ||
+ | |||
+ | **Cast**: | ||
+ | |||
+ | [[main_role:: | ||
+ | [[main_character:: | ||
+ | |||
+ | [[supporting_role:: | ||
+ | [[supporting_character:: | ||
+ | |||
+ | [[supporting_role:: | ||
+ | [[supporting_character:: | ||
+ | |||
+ | **Action time**: [[action_time: | ||
+ | |||
+ | **Series**: [[series:: | ||
+ | |||
+ | **Language**: | ||
+ | |||
+ | [[category: | ||
+ | </ | ||
+ | |||
+ | ===== ASK semantic queries ===== | ||
+ | Since now we were creating pages that were containing some semantic information. But it is only the introduction to the most powerful feature of semantic wikis - Semantic Queries. Loki uses the ASK query syntax known from the Semantic Media Wiki. It allows us to ask for pages and information they contain by using special query code. | ||
+ | |||
+ | The simplest form of ASK query has form: | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: condition }} | ||
+ | </ | ||
+ | |||
+ | '' | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | </ | ||
+ | |||
+ | By placing this on the page in wiki we will get list of pages that have defined category '' | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | </ | ||
+ | |||
+ | That way we will get list of movies produced in 2008. In our case there should be '' | ||
+ | |||
+ | <code loki> | ||
+ | [[category: | ||
+ | |||
+ | Name: [[name: | ||
+ | |||
+ | Full Name: [[full_name: | ||
+ | |||
+ | Gender: [[gender: | ||
+ | |||
+ | Birth date: [[birth_date: | ||
+ | |||
+ | From: [[is_from:: | ||
+ | </ | ||
+ | |||
+ | Now we can add some ask queries at the end of the page (or wherever we want to in the text). Let's say we want list of the movies with him playing main role in: | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | </ | ||
+ | |||
+ | That code will do the work. If we would like to include movies where he played supporting role we will use OR keyword: | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | </ | ||
+ | |||
+ | But since we don't have such movie in the knowledge base we won't get any new movie on the list. We can also use OR with the same relation but different values and there is a shorter code possible here: | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | </ | ||
+ | |||
+ | Notice that Sean Connery is placed here as it is not as '' | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | </ | ||
+ | |||
+ | This will return no result, since in our knowledge base there is no information that Harrison Ford plays any main role. It is '' | ||
+ | |||
+ | ==== Subqueries ==== | ||
+ | We can put subqueries into the conditions. It is done by inserting them between the ''< | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | </ | ||
+ | |||
+ | This example will give us list of movies, where main_role was played by a singer if we have any person with that category and there is a movie where the person is the value of the relation '' | ||
+ | |||
+ | We can nest subqueries by inserting another one in the ''< | ||
+ | |||
+ | ==== Relation chains ==== | ||
+ | We can use chains of relations as a condition in our query. For example, we can ask for movies where actor who plays main role is from the USA: | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | </ | ||
+ | |||
+ | ==== Displaying results ==== | ||
+ | By default results are shown as a table with list of pages found as a result of the query. We can add columns to the table by placing additional attributes of the ASK query. Every attribute is separated with a '' | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | ? | ||
+ | }} | ||
+ | </ | ||
+ | |||
+ | We can also define the header of the column to get rid of '' | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | ? | ||
+ | }} | ||
+ | </ | ||
+ | |||
+ | We can check if the result belongs to given category: | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | ? | ||
+ | ? | ||
+ | }} | ||
+ | </ | ||
+ | |||
+ | In the result the last column will have '' | ||
+ | |||
+ | ==== Options for the ASK queries ==== | ||
+ | We can also add options to customize the output of the query results. The options should be placed after the list of the columns described above. Options never begin with ''?'' | ||
+ | |||
+ | ^ Option name ^ Allowed values ^ Description ^ | ||
+ | | format | list of formats is available below | The output format of the results - table by default | | ||
+ | | limit | positive number | Maximum number of displayed results | | ||
+ | | offset | positive number | Defines from which result page start the display. Results with smaller count won't be displayed | | ||
+ | | sort | names of shown attributes | Sorting columns. Can be more then one, but separated with comma | | ||
+ | | order | asc, ascending, desc, descending, reverse, random | Sorting order. If there are more then one sort attributes, separate it with comma. By default it is set to '' | ||
+ | | headers | show, hide | Show or hide headers of the result table. By default: show | | ||
+ | | mainlabel | text | Label of the main column containing list of returned pages. Empty by default. | | ||
+ | | link | all, subject, none | Defines which elements of the result are shown as a link. By default is set to '' | ||
+ | | default | text | Text shown when there are no results | | ||
+ | | intro | text | Text shown above the results | | ||
+ | | outro | text | Text shown below the results | | ||
+ | | sep | text | Only in '' | ||
+ | |||
+ | The list of formats contains: | ||
+ | * table - default one | ||
+ | * broadtable - table wide for the whole page | ||
+ | * list - list separated with commas (or another char defined by '' | ||
+ | * ol - ordered list. Additional columns shown in parentheses. | ||
+ | * ul - unordered list. Additional columns shown in parentheses. | ||
+ | * count - count of results | ||
+ | * csv - generates file on the server with results and shows the link to the file | ||
+ | * debug - shows query and goal in the Prolog code, list of column, options and count of found results | ||
+ | |||
+ | Let's look at the example. It will show the table with information on the movies where Harrison Ford played the main role: | ||
+ | |||
+ | <code loki> | ||
+ | {{#ask: [[category: | ||
+ | ?title | | ||
+ | ? | ||
+ | sort=production_year | ||
+ | }} | ||
+ | </ | ||
+ | |||
+ | As you can see the movies are ordered chronologically by the production year. | ||
+ | |||
+ | ===== Usage of Prolog code ===== | ||
+ | Under the mask Loki uses SWI Prolog environment to provide reasoning for DokuWiki. Features of categories, attributes, relations, queries are all just shortcuts to create knowledge base in Prolog. But what is the most powerful in Loki is possibility to insert knowledge manually in Prolog language. In that way any application written in Prolog can be used explicitly on the DokuWiki page and provide additional information into knowledge base. | ||
+ | |||
+ | To place your code in Prolog you can use ''< | ||
+ | |||
+ | <code prolog> | ||
+ | <pl> | ||
+ | woman(' | ||
+ | parent(' | ||
+ | mother(X,Y) :- | ||
+ | woman(X), | ||
+ | parent(X, | ||
+ | </pl> | ||
+ | </ | ||
+ | |||
+ | In that way you can provide additional knowledge into the base of Loki. But you can do even more. '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | If you want, you can assign that way categories, attributes and relations. You just need to use predicates: | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | |||
+ | ===== Caching ===== | ||
+ | By default Loki uses the cache for the pages. It may generate some problems. If you have page with ASK query, then its results will be loaded from cache. In that way, when you create new page that can be result of the query, it won't appear in the result. | ||
+ | |||
+ | If you want the query and all semantics on the given page to be processed then you should use NOCACHE directive: | ||
+ | |||
+ | <code loki> | ||
+ | ~~NOCACHE~~ | ||
+ | </ | ||
+ | |||
+ | It should be placed at the start of the chosen page. | ||
+ | |||
+ | ===== Creating pages for semantics ===== | ||
+ | There are two ways of creating special page. The first one is by clicking on the generated link in our article. But it works only for categories links. In the case of attributes and relations we need to create it's pages manually by creating pages with address: | ||
+ | |||
+ | < | ||
+ | |||
+ | Where '' | ||
+ | |||
+ | < | ||
+ | |||
+ | There' | ||
+ | |||
+ | Special pages of single attribute, category or relation are for describing the purpose of the given semantic parameter. Also once the page for one of those is created it generates the list of pages using it, which is useful for tracking the semantic data on pages. | ||
+ | |||
+ | Special pages '' | ||