Commit 5183eed4 authored by Laurent Wouters's avatar Laurent Wouters
Browse files

[doc] Configuration for readthedocs.org

parent a0e4f1ad4de1
......@@ -3,7 +3,9 @@
from subprocess import call
exclude_patterns = ['**/node_modules/**']
source_suffix = ['.rst']
html_static_path = ['libview/build/docs']
master_doc = 'index'
project = 'CubicWeb Linked Data Browser'
author = 'Laurent Wouters <lwouters@cenotelie.fr>'
......
......@@ -14,7 +14,9 @@ that compiles to it) that implements a simple interface.
There are a few other requirements, as listed below:
- The view implementation must conform to the
`ViewImplementation` interface.
`ViewImplementation
<../_static/interfaces/_view_impl_.viewimplementation.html>`_
interface.
- The Javascript resource containing the implementation must contain
an entrypoint for the browser.
- The view implementation must be referred to by a endpoint serving
......@@ -41,8 +43,11 @@ First, add this library as a dependency in your project:
npm install @logilab/libview
The next step is to start the implementation of the main
interface to provide: `ViewImplementation`.
This interface is located in the `implementation` namespace within
interface to provide: `ViewImplementation
<../_static/interfaces/_view_impl_.viewimplementation.html>`_.
This interface is located in the
`implementation <../_static/modules/_view_impl_.html>`_
namespace within
`@logilab/libview`. A good starting point is (in Typescript):
.. code:: typescript
......@@ -74,9 +79,13 @@ This interface is located in the `implementation` namespace within
This interface is basically three members:
- `descriptor` is a public attribute that must contain
- `descriptor
<../_static/interfaces/_view_impl_.viewimplementation.html#descriptor>`_
is a public attribute that must contain
the descriptor (metadata for the view).
- `priorityFor` is a method that, given a RDF dataset and a target resource
- `priorityFor
<../_static/interfaces/_view_impl_.viewimplementation.html#priorityfor>`_
is a method that, given a RDF dataset and a target resource
(URI) to be rendered, must return the self-evaluated priority of the view.
This value is used by the browser to select an appropriate view for the
dataset. A higher (positive) number indicates a higher priority.
......@@ -84,33 +93,47 @@ This interface is basically three members:
selected by the browser. As of this writing, the browser primarily relies
on these self-evaluation by the views, unless the user explicitely select
a particular view.
- `render` is the single entrypoint for the view implementation used by the
- `render
<../_static/interfaces/_view_impl_.viewimplementation.html#render>`_
is the single entrypoint for the view implementation used by the
browser. Given a rendered, a contact and a target resource (URI) to be
endered, it must return a rendering that may or may not include an HTML
DOM sub-tree.
The basic idea for a view implementation is for the browser to specify the RDF
dataset and the main resource to render and for the view to provide an HTML DOM tree.
How the DOM tree is produced is left to the discretion of the view implementation.
Any framework may be used, such as React, Angular, Vue, etc.; or no framework at all.
dataset and the main resource to render and for the view to provide an HTML DOM
tree.
How the DOM tree is produced is left to the discretion of the view
implementation.
Any framework may be used, such as React, Angular, Vue, etc.; or no
framework at all.
Descriptor
==========
The view descriptor is an object that conform the `ViewDescriptor` interface.
The view descriptor is an object that conform the
`ViewDescriptor <../_static/interfaces/_view_def_.viewdescriptor.html>`_
interface.
It *must* have the following fields:
- `identifier`, a unique identifier for the view.
- `name`, a short human-readable name for the view.
- `description`, a more lengthier description for the view. It may expands of
- `identifier <../_static/interfaces/_view_def_.viewdescriptor.html#identifier>`_,
a unique identifier for the view.
- `name <../_static/interfaces/_view_def_.viewdescriptor.html#name>`_,
a short human-readable name for the view.
- `description <../_static/interfaces/_view_def_.viewdescriptor.html#description>`_,
a more lengthier description for the view. It may expands of
the kind of RDF data that the view is able to handle.
- `entrypoint`, the name of an exported variable that contains an instance of
- `entrypoint <../_static/interfaces/_view_def_.viewdescriptor.html#entrypoint>`_,
the name of an exported variable that contains an instance of
the view implemention. See Step 2.
- `resourceCss`, an array of potentially remote CSS resources that should be
- `resourceCss <../_static/interfaces/_view_def_.viewdescriptor.html#resourcecss>`_,
an array of potentially remote CSS resources that should be
loaded by the browser for this view.
- `resourceJs`, an array of potentially remote additional Javascript resources
- `resourceJs <../_static/interfaces/_view_def_.viewdescriptor.html#resourcejs>`_,
an array of potentially remote additional Javascript resources
that should be loaded by the browser for this view.
- `resourceMain`, points to the potentially remote Javascript resource that
- `resourceMain <../_static/interfaces/_view_def_.viewdescriptor.html#resourcemain>`_,
points to the potentially remote Javascript resource that
contains the view implementation.
Example:
......@@ -142,14 +165,18 @@ Priority evaluation
===================
When computing the priority of a view, the raw and complete RDF dataset is
passed to the `priorityFor` method of the view implementation, along with
passed to the `priorityFor
<../_static/interfaces/_view_impl_.viewimplementation.html#priorityfor>`_
method of the view implementation, along with
the target of rendering, i.e. the primary entity to be rendered by this view.
It is the responsability of the view implementation to determine its priority
regarding the dataset and the target entity.
For example, a view specific to books *should* try to detect the type of the
target resource and *should* deactivate itself if it does not look like a book.
In the case the view desires to deactivate itself, the
`VIEW_PRIORITY_INAPPROPRIATE` constant can be returned.
`VIEW_PRIORITY_INAPPROPRIATE
<../_static/modules/_view_impl_.html#view_priority_inappropriate>`_
constant can be returned.
The strategy to be used to determine whether the view is appropriate and what
is its priority is left to the view itself.
......@@ -194,8 +221,9 @@ Rendering
=========
Once a view has been selected, it can be rendered by the browser,
by calling the `render` method on the view implementation.
This method takes 3 parameters:
by calling the `render
<../_static/interfaces/_view_impl_.viewimplementation.html#render>`_
method on the view implementation. This method takes 3 parameters:
- `renderer`, an object that can be used to interact
with the rendering process.
......@@ -204,7 +232,8 @@ This method takes 3 parameters:
- `target`, the target RDF resource (URI) to be used
as the primary entity to be rendered.
The renderer, of type `ViewRenderer` makes available a few methods
The renderer, of type `ViewRenderer
<../_static/interfaces/_application_.viewrenderer.html>`_ makes available a few methods
for the view implementation to interact with the rendering process.
.. code:: typescript
......@@ -229,18 +258,24 @@ for the view implementation to interact with the rendering process.
}
- The `getLanguagesFor` method can be used to compute the list of languages,
- The `getLanguagesFor
<../_static/interfaces/_application_.viewrenderer.html#getlanguagesfor>`_
method can be used to compute the list of languages,
from the highest priority down, that should be used for a specific RDF
resource.
The methods takes into account the user preferences in the form of the
rendering context.
- Moreover, the `render` method can be used by a view implementation to
- Moreover, the `render
<../_static/interfaces/_application_.viewrenderer.html#render>`_ method
can be used by a view implementation to
recursively perform the rendering of (probably another) RDF resource,
so that it can be included into its own rendering.
This mechanism can be used by a view to include snippets about other
resources as rendered by other view implementations.
The rendering context, of type `RenderingContext`, holds various data
The rendering context, of type `RenderingContext
<../_static/interfaces/_application_.renderingcontext.html>`_,
holds various data
related to the rendering.
......@@ -273,24 +308,39 @@ related to the rendering.
}
- Most notable, the `store` field gives access to the current RDF dataset.
- The `root` field is set to the root RDF resource that is being rendered.
- The `options` field is a dictionary that holds the preferences
- Most notable, the `store
<../_static/interfaces/_application_.renderingcontext.html#store>`_
field gives access to the current RDF dataset.
- The `root
<../_static/interfaces/_application_.renderingcontext.html#root>`_
field is set to the root RDF resource that is being rendered.
- The `options
<../_static/interfaces/_application_.renderingcontext.html#options>`_
field is a dictionary that holds the preferences
(view, language, etc.) selected by the user for various RDF resources.
- The `browserLanguage` field simply holds the language that has been
- The `browserLanguage
<../_static/interfaces/_application_.renderingcontext.html#browserlanguage>`_
field simply holds the language that has been
detected for the browser.
- The `events` field contains an object that holds methods that can be
- The `events
<../_static/interfaces/_application_.renderingcontext.html#events>`_
field contains an object that holds methods that can be
invoked for certain events related to the user interection with the
rendered view.
The `onRequestNavigateTo` method can be used to trigger the navigation
The `onRequestNavigateTo
<../_static/interfaces/_application_.renderingcontext.html#onRequestnavigateTo>`_
method can be used to trigger the navigation
of the browser to a RDF resource when a user click on a link to another
resource in the rendered view.
The `onSelectAsPrimaryTopic` method can be used to update the primary
The `onSelectAsPrimaryTopic
<../_static/interfaces/_application_.renderingcontext.html#onselectasprimarytopic>`_
method can be used to update the primary
topic (root resource) of the current dataset.
This method is notably used by the built-in RDF triples view to enable
the user to select the primary topic.
In the end, the view implementation *must* produce a `RenderingResult`
In the end, the view implementation *must* produce a `RenderingResult
<../_static/interfaces/_application_.renderingresult.html>`_
object to be returned.
.. code:: typescript
......@@ -323,10 +373,12 @@ object to be returned.
This object contains the rendering itself as a DOM tree with the field
`dom`, as well as some metadata.
`dom <../_static/interfaces/_application_.renderingresult.html#dom>`_,
as well as some metadata.
Note that returning a rendering object without a DOM tree can be used
to indicate a failure to render.
The second field of interest is `suggestedResources`.
The second field of interest is `suggestedResources
<../_static/interfaces/_application_.renderingresult.html#suggestedresources>`_.
This is a list of RDF resources that have been identifier of importance
by the view implementation (probably because they are linked to by
the resource being rendered).
......@@ -337,7 +389,8 @@ Resource A links to resource B, but the data about B is not in the same dataset.
The view implementation can suggest B so that data about it can be loaded.
When the browser finally loads data about B, a second rendering pass is invoked.
This time the view implementation can use the data about B, for example to render a user-friendly label instead of just an URI.
The `RenderingResult` object possesses other fields, such as the identifier of the view implementation that produced the rendering.
The `RenderingResult <../_static/interfaces/_application_.renderingresult.html>`_
object possesses other fields, such as the identifier of the view implementation that produced the rendering.
Those are automatically re-written by the renderer (so that they cannot be faked) ans therefore can be safely let empty.
Facilities to manipulate RDF data
......@@ -347,12 +400,18 @@ Although view implements can rely on the raw dataset for rendering, `libview`
also provides a few abstraction layers that can ease the manipulation of the
dataset.
The first step is to use the `RdfEntityStore`, which enables the manipulation
of RDF resources in an object-oriented fashion as `RdfEntity`.
A `RdfEntity` simply abstract a RDF resources and provides accessors for
The first step is to use the `RdfEntityStore
<../_static/classes/_rdf_entities_.rdfentitystore.html>`_,
which enables the manipulation
of RDF resources in an object-oriented fashion as `RdfEntity
<../_static/classes/_rdf_entities_.rdfentity.html>`_.
A `RdfEntity <../_static/classes/_rdf_entities_.rdfentity.html>`_
simply abstract a RDF resources and provides accessors for
assertions about the entity, for example finding out the values for a
property, or the entities referred to through a property.
In addition, the `RdfEntityStore` handles aliases for entities, meaning
In addition, the `RdfEntityStore
<../_static/classes/_rdf_entities_.rdfentitystore.html>`_
handles aliases for entities, meaning
it automatically handles equivalent RDF resources asserted using the
`owl:sameAs` property.
......@@ -371,7 +430,10 @@ by the browser, it needs to known what is the main object that represents
the actual view implementation.
This entity is the entrypoint.
It usually is a simple constant that holds an instance of the view
implementation object that implements the `ViewImplementation` interface.
implementation object that implements the
`ViewImplementation
<../_static/interfaces/_view_impl_.viewimplementation.html>`_
interface.
Continuing on the example, the entrypoint may be defined as follow:
.. code:: typescript
......
......@@ -12,3 +12,9 @@ The toolkit for the production of a browser of the web of data.
docs/Repository
docs/ServerLDCompliance
docs/WritingNewViews
-----------------
API Documentation
-----------------
- `API documentation <_static/index.html>`_
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment