README.md 3.72 KB
Newer Older
Sylvain Le Bon's avatar
Sylvain Le Bon committed
1
# sib-router
Sylvain Le Bon's avatar
Sylvain Le Bon committed
2 3 4 5 6 7 8 9 10 11 12

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:
```html
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.20/webcomponents-loader.js"></script>
13
<script type="module" src="https://unpkg.com/@startinblox/router@latest"></script>
Sylvain Le Bon's avatar
Sylvain Le Bon committed
14 15
```

Alexandre's avatar
Alexandre committed
16 17
Then you can use the new tags in your markup, for instance : `<sib-router>`. 
More details on each component in the following section. 
Sylvain Le Bon's avatar
Sylvain Le Bon committed
18

Sylvain Le Bon's avatar
Sylvain Le Bon committed
19
## Usage
Sylvain Le Bon's avatar
Sylvain Le Bon committed
20

Alexandre's avatar
Alexandre committed
21
Displays a menu and handle the navigation for you.
Sylvain Le Bon's avatar
Sylvain Le Bon committed
22 23

```html
Alexandre's avatar
Alexandre committed
24
<sib-router 
Sylvain Le Bon's avatar
Sylvain Le Bon committed
25 26
    default-route="list"
    route-prefix="my-app"
Alexandre's avatar
Alexandre committed
27
    use-hash
Sylvain Le Bon's avatar
Sylvain Le Bon committed
28
>
Alexandre's avatar
Alexandre committed
29 30 31 32
    <sib-route name="list">List</sib-route>
    <sib-route name="form">Form</sib-route>
    <sib-route name="detail">Details</sib-route>
</sib-router>
Sylvain Le Bon's avatar
Sylvain Le Bon committed
33 34 35

```

Sylvain Le Bon's avatar
Sylvain Le Bon committed
36
### `<sib-router>` attributes:
Alexandre's avatar
Alexandre committed
37

38 39 40
 - **`default-route`**: The `name` attribute of the default `<sib-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.
Alexandre's avatar
Alexandre committed
41 42
 

Sylvain Le Bon's avatar
Sylvain Le Bon committed
43
### `<sib-route>` attributes:
44 45 46 47
 - **`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 `<sib-router>`. It is automatically added/removed by `<sib-router>` and should not be tinkered manually.
Alexandre's avatar
Alexandre committed
48 49


Sylvain Le Bon's avatar
Sylvain Le Bon committed
50
## sib-link
Alexandre's avatar
Alexandre committed
51
`<sib-link>` accepts the following attributes:
Alexandre's avatar
Alexandre committed
52

53
 - **`next`**: The `name` attribute of the `<sib-route>` you want to access.
Alexandre's avatar
Alexandre committed
54

Clément's avatar
Clément committed
55
Example:
Alexandre's avatar
Alexandre committed
56 57
```html
<sib-link next="profile">See profile</sib-link>
Alexandre's avatar
Alexandre committed
58
```
Alexandre's avatar
Alexandre committed
59

Clément's avatar
Clément committed
60 61
## sib-analytics

Clément's avatar
Clément committed
62 63
Manage browsing statistics.

Benoit Alessandroni's avatar
Benoit Alessandroni committed
64
`<sib-analytics>` accepts the following attributes:
Clément's avatar
Clément committed
65 66
 
 - **`type`**: the type of web analytics service used (currently supports `'matomo'` or `'google'`).
67
 - **`url`**: URL of the service. for `type="google"` it is not necessary to specify the url attribute.
Clément's avatar
Clément committed
68
 - **`id`**: id of the website on the service.
Clément's avatar
Clément committed
69

Sylvain Le Bon's avatar
Sylvain Le Bon committed
70 71
## Interacting with the router

Alexandre's avatar
Alexandre committed
72 73
### bind-resources attribute
To associate the currently displayed resource to a component, add the `bind-resources` attribute to it.
Alexandre's avatar
Alexandre committed
74
It will set its `data-src` attribute to the currently displayed resource's URL. 
Alexandre's avatar
Alexandre committed
75 76 77 78 79

Example:
```html
<sib-conversation bind-resources></sib-conversation>
```
Clément's avatar
Clément committed
80
will result in:
Alexandre's avatar
Alexandre committed
81 82 83 84
```html
<sib-conversation data-src="https://your-domain/your-group-uri/3" bind-resources></sib-conversation>
```

Sylvain Le Bon's avatar
Sylvain Le Bon committed
85 86 87 88 89 90 91
### 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.
Alexandre's avatar
Alexandre committed
92

Sylvain Le Bon's avatar
Sylvain Le Bon committed
93 94
## Events

Sylvain Le Bon's avatar
Sylvain Le Bon committed
95
### navigate
Sylvain Le Bon's avatar
Sylvain Le Bon committed
96

Sylvain Le Bon's avatar
Sylvain Le Bon committed
97
This event is triggered whenever a route is activated, after the view is displayed.
Sylvain Le Bon's avatar
Sylvain Le Bon committed
98 99 100

## License

Sylvain Le Bon's avatar
Sylvain Le Bon committed
101
Licence MIT
Sylvain Le Bon's avatar
Sylvain Le Bon committed
102 103 104