basicTutorial.html

---
layout: default
title: Basic Tutorial 1
section: basicTutorial
path: docs/basicTutorial.html
---

<h1 class="ui dividing header">
Basic Tutorial -- part 1: static configurations
</h1>

<h2>Before you start...</h2>
<p>
Before you start this tutorial, please make sure that you have followed the instructions on our <a href="quickstart.html"> Quick Start</a> page and have installed everything which is required for this tutorial.
</p>

<h2>What is it about?</h2>
<p>
In this tutorial, we will build a LD-R application on top of the <a href="http://wiki.dbpedia.org/">DBpedia</a> knowledge graph -- extracted structred information from Wikipedia.
The tutorial will show how the basic configurations in LD-R can be applied to view, edit and browse Linked Data.
</p>

<h2>Let's start!</h2>
Go to the directoy where you have installed your LD-R instance and open your favorite code editor (I usually use <a href="https://atom.io/">Atom editor</a> which brings a set of nice features for Web development and it per se is built with React technology. To launch the Atom editor, I simply run <code class="ui label">atom .</code> on my project directory.).
<p>
  In order to develop and see the results in parallel, run the <code class="ui label">npm run dev</code> command.
  * If you are a windows user, you might need to try <code class="ui label">npm run dev:windows</code> instead!
  This command will start the Node server and will watch your code for possible changes. It will thereby refresh the pages/components automatically without re-running the command or refrshing the browser page.
</p>
<p>
  Once the Node server is on, If you now go to the <a href="http://localhost:3000">http://localhost:3000</a> in your browser you should see the home page of the LD-R:
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t1.png" alt="t1" />
</div>
<p>
  If you click on the <span class="ui primary label">Datasets</span>, you should see the following message:
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t2.png" alt="t2" />
</div>
<p>
  This means you still haven't defined any datasets to view, edit or browse. OK, it is time now to add some configs in there!
  The first config you need to set is in the <code class="ui label">configs/server.js</code> in order to be able to connect to a SPARQL endpoint.
  The default server configuration looks like this:
</p>
<pre style="background:#002240;color:#fff"><span style="color:#ffee80">export</span> <span style="color:#ff9d00">default</span> {
    serverPort: [<span style="color:#ff628c">4000</span>],
    sparqlEndpoint: {
        <span style="color:#3ad900">'</span>generic<span style="color:#3ad900">'</span>: {
            host: <span style="color:#3ad900">'</span>localhost<span style="color:#3ad900">'</span>, port: <span style="color:#ff628c">8890</span>, path: <span style="color:#3ad900">'</span>/sparql<span style="color:#3ad900">'</span>, endpointType: <span style="color:#3ad900">'</span>virtuoso<span style="color:#3ad900">'</span>
        }
    },
    dbpediaLookupService: [
        { host: <span style="color:#3ad900">'</span>lookup.dbpedia.org<span style="color:#3ad900">'</span> }
    ]
}<span style="color:#e1efff">;</span>
</pre>
<p>
  There is always a 'generic' configuration for the SPARQL Endpoint which will be used in case no other configurations are defined.
  It means if you already have a triple store such as 'Virtuoso' installed/running on your localhost, you can use it right away.
  For our tutorial, let's add a new endpoint configuration for DBpedia:
</p>
<pre style="background:#002240;color:#fff"><span style="color:#ffee80">export</span> <span style="color:#ff9d00">default</span> {
    serverPort: [<span style="color:#ff628c">4000</span>],
    sparqlEndpoint: {
        <span style="color:#3ad900">'</span>generic<span style="color:#3ad900">'</span>: {
            host: <span style="color:#3ad900">'</span>localhost<span style="color:#3ad900">'</span>, port: <span style="color:#ff628c">8890</span>, path: <span style="color:#3ad900">'</span>/sparql<span style="color:#3ad900">'</span>, endpointType: <span style="color:#3ad900">'</span>virtuoso<span style="color:#3ad900">'</span>
        },
        <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>added a new endpoint</span>
        <span style="color:#3ad900">'</span>http://live.dbpedia.org/sparql<span style="color:#3ad900">'</span>: {
            host: <span style="color:#3ad900">'</span>live.dbpedia.org<span style="color:#3ad900">'</span>, port: <span style="color:#ff628c">80</span>, path: <span style="color:#3ad900">'</span>/sparql<span style="color:#3ad900">'</span>, graphName: <span style="color:#ff628c">'default'</span>, endpointType: <span style="color:#3ad900">'</span>virtuoso<span style="color:#3ad900">'</span>
        },
    },
    dbpediaLookupService: [
        { host: <span style="color:#3ad900">'</span>lookup.dbpedia.org<span style="color:#3ad900">'</span> }
    ]
}<span style="color:#e1efff">;</span>
</pre>
<p>
  I have chosen to use the live dbpedia endpoint for this tutorial but you can also use <a href="http://dbpedia.org/sparql">http://dbpedia.org/sparql</a> as well (if it is up and running!).
  The type of triple store is '<a href="http://virtuoso.openlinksw.com/">virtuoso</a>' and I will use the default graph for data. If you don't specify the default graph name, the identifier for the endpoint (in this case 'http://live.dbpedia.org/sparql') is used as the graph name.
  More info about the possible parameters and values for server config is available <a href="configServer.html">here</a>.
</p>
<div class="ui info message">
  <i class="ui big yellow info icon"></i>
  If you want to connect to a another type of triple store e.g. <a href="http://stardog.com/">Stardog</a>, You can use the following server configuration:
  <pre style="background:#002240;color:#fff">        'http<span style="color:#ff9d00">://</span>localhost<span style="color:#ff9d00">:</span><span style="color:#ff628c">5820</span><span style="color:#ff9d00">/</span>tutorial<span style="color:#ff9d00">/</span>query'<span style="color:#ff9d00">:</span> {
            host<span style="color:#ff9d00">:</span> 'localhost'<span style="color:#e1efff">,</span> port<span style="color:#ff9d00">:</span> <span style="color:#ff628c">5820</span><span style="color:#e1efff">,</span> path<span style="color:#ff9d00">:</span> '<span style="color:#ff9d00">/</span>tutorial<span style="color:#ff9d00">/</span>query'<span style="color:#e1efff">,</span> graphName<span style="color:#ff9d00">:</span> <span style="color:#ff628c">'default'</span><span style="color:#e1efff">,</span> <span style="color:#ff9d00">endpointType</span><span style="color:#ff9d00">:</span> 'stardog'
        }
  </pre>
 You would just need to use the correct port (if it is not 5820) and add your database name (replace the 'tutorial' with your own database name).
</div>
<p>
  It was all about connecting to the DBpedia triple store. Let's now add our first reactor configuration:
</p>
<p>
  Open the <code class="ui label">configs/reactor.js</code> file in your editor and add the placeholder for our DBpedia graph:
</p>
<pre style="background:#002240;color:#fff">        <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>---------depth 1------------</span>
        dataset: {
            <span style="color:#3ad900">'</span>generic<span style="color:#3ad900">'</span>: {
                resourceFocusType: [],
                <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>only allow to view data -> disable edit</span>
                readOnly: <span style="color:#ff628c">1</span>,
                <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>used for pagination in resource list</span>
                maxNumberOfResourcesOnPage: <span style="color:#ff628c">20</span>,
                datasetReactor: [<span style="color:#3ad900">'</span>Dataset<span style="color:#3ad900">'</span>]
            },
            <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>adding configs for dbpedia</span>
            <span style="color:#3ad900">'</span>http://live.dbpedia.org/sparql<span style="color:#3ad900">'</span>: {

            },
            <span style="color:#3ad900">'</span>http://ld-r.org/users<span style="color:#3ad900">'</span>: {
                readOnly: <span style="color:#ff628c">0</span>
            }
        },
</pre>
<p>
  LD-R supports configurations in different levels. With the above lines, we set the configs for datasets.
  Now, if you visit <a href="http://localhost:3000/datasets">http://localhost:3000/datasets</a>, you should already see the DBpedia graph listed there:
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t3.png" alt="t3" />
</div>
<p>
  and by clicking on the dataset, you should already get a long list of all resources on DBpedia:
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t4.png" alt="t4" />
</div>
<p>
  you can also click on the resources and see their data displayed by the basic LD-R rendering.
</p>
<p>
  Let's tell the LD-R to only list the resources of a certain type e.g. "University". To enable this, add a config in the <code class="ui label">configs/reactor.js</code> for the 'resourceFocusType' property:
</p>
<pre style="background:#002240;color:#fff">            <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>added focus on a specific entity type</span>
            <span style="color:#3ad900">'</span>http://live.dbpedia.org/sparql<span style="color:#3ad900">'</span>: {
                resourceFocusType: [<span style="color:#3ad900">'</span>http://dbpedia.org/ontology/University<span style="color:#3ad900">'</span>],
            },
</pre>
<p>
  This will tell the default Dataset viewer to only display the resources of type dbpedia:University .
  As a result, you will now only get the list of universities from DBpedia:
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t5.png" alt="t5" />
</div>
<p>
  You can also provide multiple focus types if needed. For instance to also list the resources of type dbpedia:EducationalInstitution :
</p>
<pre style="background:#002240;color:#fff">            <span style="color:#3ad900">'</span>http://live.dbpedia.org/sparql<span style="color:#3ad900">'</span>: {
                resourceFocusType: [<span style="color:#3ad900">'</span>http://dbpedia.org/ontology/University<span style="color:#3ad900">'</span>, <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/EducationalInstitution<span style="color:#3ad900">'</span>],
            },
</pre>
<p>This will result in more resources to be dispaled:</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t6.png" alt="t6" />
</div>
<p>
  The above example was about basic viewing in the dataset level. Another component which can be used to explore data in the dataset level is the faceted browser.
  In order to activate the faceted browser, you need to set the config in <code class="ui label">configs/facets.js</code> file.
  Let's add some facets on the DBpedia dataset:
</p>
<pre style="background:#002240;color:#fff"><span style="color:#ffee80">export</span> <span style="color:#ff9d00">default</span> {
    facets: {
        <span style="color:#3ad900">'</span>generic<span style="color:#3ad900">'</span>: {
            list: [
                <span style="color:#3ad900">'</span>http://www.w3.org/1999/02/22-rdf-syntax-ns#type<span style="color:#3ad900">'</span>
            ],
            config: {

            }
        },
        <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>adding facets for dbpedia</span>
        <span style="color:#3ad900">'</span>http://live.dbpedia.org/sparql<span style="color:#3ad900">'</span>: {
            list: [
                <span style="color:#3ad900">'</span>http://www.w3.org/1999/02/22-rdf-syntax-ns#type<span style="color:#3ad900">'</span>, <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/country<span style="color:#3ad900">'</span>, <span style="color:#3ad900">'</span>http://dbpedia.org/property/established<span style="color:#3ad900">'</span>, <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/numberOfStudents<span style="color:#3ad900">'</span>
            ],
            config: {

            }
        },

    }
}<span style="color:#e1efff">;</span>

</pre>
<p>
  Here you need to give a list of properties on which you want to create the facets.
  After adding the facets, you should now see the <button class="ui button">browse</button> button next to the dataset's name:
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t7.png" alt="t7" />
</div>
<p>After clicking on the browse button, you should get a list of facets to explore the dataset:</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t8.png" alt="t8" />
</div>
<p>Depending on the size of data and the performance of your triple store, the speed of rendering the selected facets may vary.</p>
<h2>Let's do some config in the Resource level...</h2>
<p>
  The previous configs were employing the LD-R Dataset reactor.
  We can also have configs on the way resources are rendered on the page.
  For example, we can categorize the properties listed for a resource for better readability and understanding.
  Going back to our DBpedia example, Let's say we want to present two categories of properties namely 'General' and 'Specific'.
  To apply this, you need to open <code class="ui label">configs/reactor.js</code> and add the resource config as following:
</p>
<pre style="background:#002240;color:#fff">        resource: {
            <span style="color:#3ad900">'</span>generic<span style="color:#3ad900">'</span>: {
                <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>if enabled, will categorize properties in different tabs based on property categories</span>
                usePropertyCategories: <span style="color:#ff628c">0</span>,
                propertyCategories: [],
                <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>used when creating random resources</span>
                dynamicResourceDomain: [<span style="color:#3ad900">'</span>http://example.org<span style="color:#3ad900">'</span>],
                resourceReactor: [<span style="color:#3ad900">'</span>Resource<span style="color:#3ad900">'</span>]
            },
            <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>added categories for resource properties</span>
            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/EducationalInstitution<span style="color:#3ad900">'</span>: {
                treatAsResourceType: <span style="color:#ff628c">1</span>,
                usePropertyCategories: <span style="color:#ff628c">1</span>,
                propertyCategories: [<span style="color:#3ad900">'</span>General<span style="color:#3ad900">'</span>, <span style="color:#3ad900">'</span>Specific<span style="color:#3ad900">'</span>]
            },
        },
</pre>
<p>
  As you see, similar to dataset's config, here you get a generic config for resources which is used when no specific config for resources is defined.
  There are two ways to config resources: specify the resource by its URI or use the rdf:type property of the resource to apply configs to all resources of that specific type.
  In our case, we apply the config to all resources of type dbpedia:EducationalInstitution .
  We enable using property categories and add two possible values for property categories.
  Now, if you look at an example resource of EducationalInstitution, you will get two different tabs for property categories, but still with empty values.
  That is because you need to specify which properties should go under which categories.
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t9.png" alt="t9" />
</div>
<h2>Let's do some config in the Property level...</h2>
<p>
  Similar to the Dataset and Resource configurations, we can customize the way properties of a resource are rendered on the page.
  To do this, you need to go to <code class="ui label">configs/reactor.js</code> and in the part related to properties, add your changes:
</p>
<pre style="background:#002240;color:#fff">        property: {
            <span style="color:#3ad900">'</span>generic<span style="color:#3ad900">'</span>: {
                propertyReactor: [<span style="color:#3ad900">'</span>IndividualProperty<span style="color:#3ad900">'</span>],
                <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>following are object-based scope:</span>
                objectReactor: [<span style="color:#3ad900">'</span>IndividualObject<span style="color:#3ad900">'</span>],
                <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>to view/edit individual object values</span>
                objectIViewer: [<span style="color:#3ad900">'</span>BasicIndividualView<span style="color:#3ad900">'</span>],
                objectIEditor: [<span style="color:#3ad900">'</span>BasicIndividualInput<span style="color:#3ad900">'</span>],
                extendedOEditor: [<span style="color:#3ad900">'</span>BasicIndividualDetailEdit<span style="color:#3ad900">'</span>],
                extendedOViewer: [<span style="color:#3ad900">'</span>BasicIndividualDetailView<span style="color:#3ad900">'</span>],
                shortenURI: <span style="color:#ff628c">1</span>
            },
            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/abstract<span style="color:#3ad900">'</span>: {
                category: [<span style="color:#3ad900">'</span>General<span style="color:#3ad900">'</span>],
                label: [<span style="color:#3ad900">'</span>Description<span style="color:#3ad900">'</span>]
            },
            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/address<span style="color:#3ad900">'</span>: {
                category: [<span style="color:#3ad900">'</span>General<span style="color:#3ad900">'</span>],
                label: [<span style="color:#3ad900">'</span>Address<span style="color:#3ad900">'</span>]
            },
            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/country<span style="color:#3ad900">'</span>: {
                category: [<span style="color:#3ad900">'</span>General<span style="color:#3ad900">'</span>],
                label: [<span style="color:#3ad900">'</span>Country<span style="color:#3ad900">'</span>]
            },
            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/foundingYear<span style="color:#3ad900">'</span>: {
                category: [<span style="color:#3ad900">'</span>Specific<span style="color:#3ad900">'</span>],
                label: [<span style="color:#3ad900">'</span>Funding Year<span style="color:#3ad900">'</span>]
            },
            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/numberOfStudents<span style="color:#3ad900">'</span>: {
                category: [<span style="color:#3ad900">'</span>Specific<span style="color:#3ad900">'</span>],
                label: [<span style="color:#3ad900">'</span>Number of Students<span style="color:#3ad900">'</span>]
            },
            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/numberOfGraduateStudents<span style="color:#3ad900">'</span>: {
                category: [<span style="color:#3ad900">'</span>Specific<span style="color:#3ad900">'</span>],
                label: [<span style="color:#3ad900">'</span>Number of Graduate Students<span style="color:#3ad900">'</span>]
            }
        },
</pre>
<p>
  This will move some properties (identified by their URIs) to their corresponding category.
  We can also change the label in which the property name is displayed. For exmaple, use 'Description' instead of 'abstract'.
  Now if you view the previous resource again, you will see the properties (if any) with their values under the correct category:
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t10.png" alt="t10" />
</div>
<p>
  To make the properties and their values more descriptive, we can add a hint next to the property name:
</p>
<pre style="background:#002240;color:#fff">            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/numberOfStudents<span style="color:#3ad900">'</span>: {
                category: [<span style="color:#3ad900">'</span>Specific<span style="color:#3ad900">'</span>],
                label: [<span style="color:#3ad900">'</span>Number of Students<span style="color:#3ad900">'</span>],
                hint: [<span style="color:#3ad900">'</span>This property returns the current number of students...<span style="color:#3ad900">'</span>]
            },
</pre>
<p>The result will look like this:</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t11.png" alt="t11" />
</div>
<div class="ui info message">
  <i class="ui big yellow info icon"></i>
  The configurations in this tutorial, only address the depth 1.
  LD-R also allows you to create more specific configuration e.g. customize a certain property appearing in a certain resource of a certain dataset.
  To know more about these advanced features, have a look at <a href="configReactors.html">reactors config page</a>.
</div>
<h2>It is not only about viewing data, you can also edit Linked Data...</h2>
<p>
  One of the cool features of LD-R is to allow users to edit Linked Data.
  By default, the content on LD-R is read-only. To enable editing of a dataset, you need to add the following config in <code class="ui label">configs/reactor.js</code>:
</p>
<pre style="background:#002240;color:#fff">            <span style="color:#08f;font-style:italic"><span style="color:#e1efff">//</span>allow editing of resources</span>
            <span style="color:#3ad900">'</span>http://live.dbpedia.org/sparql<span style="color:#3ad900">'</span>: {
                readOnly: <span style="color:#ff628c">0</span>,
                resourceFocusType: [<span style="color:#3ad900">'</span>http://dbpedia.org/ontology/University<span style="color:#3ad900">'</span>, <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/EducationalInstitution<span style="color:#3ad900">'</span>],
            },
</pre>
<p>
  Now, if you go to a resource, you will see the edit button next to the value fields:
</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t12.png" alt="t12" />
</div>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t13.png" alt="t13" />
</div>
<p>
  Of course, to be able to save the changes, your SPARQL endpoint should support UPDATE queries.
  In this case, DBpedia would not be a good example if you try to edit the DBpedia property values (It is worth a try though ;) )!
</p>
<h2>What if I want to use my custom components to view/edit Linked Data?</h2>
<p>
  That is a good question! LD-R is based on React components therefore it allows you to write your own components (or reuse existing ones) to view/edit/browse Linked Data.
Let me show you a quick example:
</p>
<p>
  Let's say we want to use a TextArea component instead of default component to edit the value of abstracts in our example dataset.
  In order to enable this, you just need to specify it in the config for that property:
</p>
<pre style="background:#002240;color:#fff">            <span style="color:#3ad900">'</span>http://dbpedia.org/ontology/abstract<span style="color:#3ad900">'</span>: {
                category: [<span style="color:#3ad900">'</span>General<span style="color:#3ad900">'</span>],
                label: [<span style="color:#3ad900">'</span>Description<span style="color:#3ad900">'</span>],
                objectIEditor: [<span style="color:#3ad900">'</span>BasicTextareaInput<span style="color:#3ad900">'</span>]
            },
</pre>
<p>In the above example, you just specify a built-in object editor component for all dbpedia:abstract property values. The result will look like this:</p>
<div>
    <img class="ui centered image" src="/assets/img/basicTutorial/t14.png" alt="t14" />
</div>
<div class="ui info message">
  <i class="ui big yellow info icon"></i>
  LD-R allows viewing/editing/browsing content in both individual and aggregate modes.
  Aggregate viwers/editors, for example, allow batch viewing/editing of values.
  To know more about these advanced features, have a look at available <a href="componentsReactors.html">LD-R components</a>.
</div>
<h2>Time to build the app...</h2>
<p>
  After you have finished configuring your LD-R app, you should exit the dev mode and build your app for the production.
  To build the app, simply run <code class="ui label">npm run build</code> command and check the final app at <a href="http://localhost:4000">http://localhost:4000</a>.
  Windows user might need to try <code class="ui label">npm run build:windows</code> for that purpose.
  The final app, concatenates and minifies all the client-side code for better performance in the Web browser.
</p>
<h2>Summary</h2>
<p>
  This tutorial aimed to only give you a taste of how LD-R framework works.
  There are much more features in LD-R than what you just experienced.
  To know more about LD-R, read <a href="http://research.ld-r.org/adaptive-linked-data-driven-web-components">this paper</a> and spend some time on the documentation pages.
  <a href="http://demo.ld-r.org">Demo</a> section lists some example datasets to browse.
</p>
<div class="ui info message">
  <i class="ui big yellow info icon"></i>
   The new version of LD-R allows dynamic configuration of apps using the LD-R UIs (i.e. you don't need anymore to statically change the content of reactor.js and facets.js and server.js files!). Please follow the <a href="http://ld-r.org/docs/basicTutorial2.html">basic tutorial 2</a> to understand how this feature works.
</div>