diff --git a/source/import_documentation/Components/SiB-Router.rst b/source/import_documentation/Components/SiB-Router.rst new file mode 100644 index 0000000000000000000000000000000000000000..9fbdea7e242b1573b8356b54cb69accdaa84bc92 --- /dev/null +++ b/source/import_documentation/Components/SiB-Router.rst @@ -0,0 +1,155 @@ +sib-router +========== + +This is a series of web component respecting both the web components +standards and the Linked Data Platform convention. They are aimed at +enabling anyone with little development skills to create their own web +application by placing these components in an HTML file. + +An full app example can be found in index.html: + +Initialization +-------------- + +You first need to load the webcomponents polyfill for the browsers that +have not implemented them yet, and import the components you want to use +in your HTML file: + +.. code:: html + + <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.20/webcomponents-loader.js"></script> + <script type="module" src="https://unpkg.com/@startinblox/router@latest"></script> + +Then you can use the new tags in your markup, for instance : +``<solid-router>``. More details on each component in the following +section. + +Usage +----- + +Displays a menu and handle the navigation for you. + +.. code:: html + + <solid-router + default-route="list" + route-prefix="my-app" + use-hash + > + <solid-route name="list">List</solid-route> + <solid-route name="form">Form</solid-route> + <solid-route name="detail">Details</solid-route> + </solid-router> + +``<solid-router>`` attributes: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **``default-route``**: The ``name`` attribute of the default + ``<solid-route>`` displayed. +- **``route-prefix``**: If you app is not run from the root of your + domain name, for instance ``www.your-domain.com/some-uri``, you + should set ``route-prefix`` to ``"some-uri"``. +- **``use-hash``**: If you can't rewrite the URLs on your server, you + might want to set this attribute to use ``location.hash`` instead of + ``location.pathname`` as URLs. + +``<solid-route>`` attributes: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **``use-id``**: indicates that the route takes an id. +- **``name``**: The name of the route. Must match the id of the view + that is to be displayed. The same name is used as a url identifier as + well. +- **``rdf-type``**: Can be used as an alternative of ``name``. The + route will be activated if a resource with the given type is passed + to the router. +- **``active``**: This attribute is present on route being displayed by + ``<solid-router>``. It is automatically added/removed by + ``<solid-router>`` and should not be tinkered manually. + +solid-link +---------- + +``<solid-link>`` accepts the following attributes: + +- **``next``**: The ``name`` attribute of the ``<solid-route>`` you + want to access. + +Example: + +.. code:: html + + <solid-link next="profile">See profile</solid-link> + +solid-analytics +--------------- + +Manage browsing statistics. + +Sign in on a web analytics service and set ``<sib-analytics>`` inside +``<body>``, at the begining for example. + +``<solid-analytics>`` accepts the following attributes: + +- **``type``**: the type of web analytics service used (currently + supports ``'matomo'``, ``'google'`` or ``'debug'``). +- **``url``**: URL of the service. For ``type="google"`` it is not + necessary to specify the url attribute. +- **``id``**: id of the website on the service. + +Type ``'debug'`` allow to test sib-analytics. It will display the route +on the console each time a navigation is triggered. + +Example : + +.. code:: html + + <sib-analytics type="matomo" url="https://matomo.example.com/" id="1234"></sib-analytics> + +Interacting with the router +--------------------------- + +bind-resources attribute +~~~~~~~~~~~~~~~~~~~~~~~~ + +To associate the currently displayed resource to a component, add the +``bind-resources`` attribute to it. It will set its ``data-src`` +attribute to the currently displayed resource's URL. + +Example: + +.. code:: html + + <sib-conversation bind-resources></sib-conversation> + +will result in: + +.. code:: html + + <sib-conversation data-src="https://your-domain/your-group-uri/3" bind-resources></sib-conversation> + +RequestNavigation +~~~~~~~~~~~~~~~~~ + +To trigger a route change through javascript, you can trigger a +RequestNavigation event anywhere on the DOM. + +The detail part must have at least one of these two parameters: - route: +the name of the route to activate - resource: a resource that will be +passed to all elements with the ``bind-resources`` attribute. If no +route name is given, the router tries to find a route that has a +``rdf-type`` that matches the type of the resource. + +Events +------ + +navigate +~~~~~~~~ + +This event is triggered whenever a route is activated, after the view is +displayed. + +License +------- + +Licence MIT