README.md 3.31 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

 - **default-route**: The `name` attribute of the default `<sib-route>` displayed.
Clément's avatar
Clément committed
39
 - **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"`. 
Alexandre's avatar
Alexandre committed
40
 - **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 44 45 46
### `<sib-route>` attributes:

 - **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.
Alexandre's avatar
Alexandre committed
47 48 49
 - **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.


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 54

 - **next**: The `name` attribute of the `<sib-route>` you want to access.

Alexandre's avatar
Alexandre 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

Sylvain Le Bon's avatar
Sylvain Le Bon committed
60 61
## Interacting with the router

Alexandre's avatar
Alexandre committed
62 63
### bind-resources attribute
To associate the currently displayed resource to a component, add the `bind-resources` attribute to it.
Alexandre's avatar
Alexandre committed
64
It will set its `data-src` attribute to the currently displayed resource's URL. 
Alexandre's avatar
Alexandre committed
65 66 67 68 69 70 71 72 73 74

Example:
```html
<sib-conversation bind-resources></sib-conversation>
```
will result in :
```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
75 76 77 78 79 80 81
### 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
82

Sylvain Le Bon's avatar
Sylvain Le Bon committed
83 84
## Events

Sylvain Le Bon's avatar
Sylvain Le Bon committed
85
### navigate
Sylvain Le Bon's avatar
Sylvain Le Bon committed
86

Sylvain Le Bon's avatar
Sylvain Le Bon committed
87
This event is triggered whenever a route is activated, after the view is displayed.
Sylvain Le Bon's avatar
Sylvain Le Bon committed
88 89 90

## License

Sylvain Le Bon's avatar
Sylvain Le Bon committed
91
Licence MIT
Sylvain Le Bon's avatar
Sylvain Le Bon committed
92 93 94