README.md 17.5 KB
Newer Older
Sylvain Le Bon's avatar
Sylvain Le Bon committed
1 2 3 4 5 6 7
## Synopsis

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.

## Code Example

8
All the examples can be found in `/examples/`
Sylvain Le Bon's avatar
Sylvain Le Bon committed
9

Alexandre's avatar
Alexandre committed
10
## Initialization
Sylvain Le Bon's avatar
Sylvain Le Bon committed
11

Alexandre's avatar
Alexandre committed
12
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:
Clément's avatar
Clément committed
13

Alexandre's avatar
Alexandre committed
14
```html
Clément's avatar
Clément committed
15 16 17 18
<script
  type="text/javascript"
  src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.20/webcomponents-loader.js"
></script>
19 20
<script type="module" src="https://unpkg.com/@startinblox/core"></script>
<script type="module" src="https://unpkg.com/@startinblox/router"></script>
Sylvain Le Bon's avatar
Sylvain Le Bon committed
21 22
```

23
Then you can use the new tags in your markup, for instance : `<solid-display>`. More details on each component in the following section.
Sylvain Le Bon's avatar
Sylvain Le Bon committed
24

Alexandre's avatar
Alexandre committed
25 26
## Components documentation

27
### `solid-display`
Alexandre's avatar
Alexandre committed
28

29
Receives the URL of a resource or of a container of resources via its `data-src` attribute, and displays it.
Clément's avatar
Clément committed
30 31
Each field of the displayed resources can be rendered by a specific widget, either custom or chosen from the default ones.
Filters and searching capabilities can be easily added to interact with the list of data being displayed.
Clément's avatar
Clément committed
32

Alexandre's avatar
Alexandre committed
33
```html
34
<solid-display
Clément's avatar
Clément committed
35 36 37
  id="list"
  data-src="http://localhost:8000/todos/"
  value-created="Created by:"
38
  fields="image, status(state), author(created, name), info(task, date), deadline"
39
  widget-image="solid-display-img"
Clément's avatar
Clément committed
40 41
  search-fields="name, author"
  next="detail"
42
></solid-display>
Alexandre's avatar
Alexandre committed
43
```
Alexandre's avatar
Alexandre committed
44

Alexandre's avatar
Alexandre committed
45 46
**Attributes:**

47
- **`data-src`**: The uri of the LDP resource you want to display.
48
  If this resource is a container, `<solid-display>` will create a child `<solid-display>` for each resource it contains, and `<solid-form>` will display a blank form with appropriate fields to create a new resource.
49
- **`value-xyz`**: To display a string not contained within the data.
50
- **`fields`**: The ordered list of fields to be displayed, separated by commas.
51

52
  By default, all the fields of the resource are displayed.
53

54
  To not show any fields, put an empty fields (eg. `<solid-display fields />)`
55 56 57

  To group fields within a `<div>` tag that will have the `name` attribute set up to `xyz`, enclose some fields in parenthesis. For example: `fields="xyz(first_name, last_name), email"`. You can customize the group widget, see the **[sets widgets](#set-widgets)** section below for more info.

58 59
  By default, all displayed fields are direct children of `<solid-display>`. Make sure you don't give your set the same name as a field as it would result in an infinite loop.
- **`widget-xyz`**: The widget to be used to display the `xyz` field. By default, the widget used is `<solid-display-div>`. Cf the **[Display widgets](#display-widgets)** section below for more info.
60
- **`default-widget`**: The widget to use for all the fields, except if a specific one is defined for a field.
61
- **`multiple-xyz`**: Show field `xyz` as multiple field containing one widget for each child. Multiple widget can be specified, example: `multiple-skills="my-custom-multiple-widget"`. If argument is used without value, default multiple widget is used. Cf the **[Multiple widgets](#multiple-widgets)** section below for more info.
Clément's avatar
Clément committed
62 63 64
  - **`each-label-xyz`**: Used with `multiple-xyz`, label of each child of multiple widget
  - **`each-class-xyz`**: Used with `multiple-xyz`, class of each child of multiple widget
  - **`each-range-xyz`**: Used with `multiple-xyz`, range value of each child of multiple widget
65 66
  - **`multiple-xyz-add-label`**: Used with `multiple-xyz`, text of the "+" button
  - **`multiple-xyz-remove-label`**: Used with `multiple-xyz`, text of the "×" button
67 68
- **`search-fields`**: It is possible to search/filter your list by choosing the fields you want to filter it with.
  To be able to filter my users by `name` for instance, I can set `search-fields="name"`. This will display a form with the appropriate inputs to filter the list.
69

Clément's avatar
Clément committed
70 71
  - **`search-value-xyz`**: The default value of the search field `xyz`
  - **`search-label-xyz`**: Set the label for the search field `xyz`
Clément's avatar
Clément committed
72 73
  - **`search-widget-xyz`**: The form widget of the search field `xyz`
  - **`search-range-xyz`**: The range of values of the search field `xyz`
74
- **`paginate-by`**: The list can also be split in pages, for example set `paginate-by="5"` to display pages of 5 elements, the prev/next buttons and the counter will be added automatically
75
- **`order-by`**: The name of the field you want to use to order the list. For example, `order-by="username"` will order the users list alphabetically based on the username.
76
- **`highlight-xyz`**: The resources to put at the top of the list. For example, `highlight-date="2019-05-20"` will display first all the resources which have a field date equal to "2019-05-20".
77
- **`group by`**: The resources will be grouped by the field you give as a parameter. For example, `group-by="date"` will render one `<div>` by date, and put the corresponding resources inside.
78
- **`next`**: `name` attribute of the `<solid-route>` that should be accessed when a `<solid-display>` element is clicked. See the documentation of `<solid-router>` for more details.
79
- **`action-xyz`**:
Clément's avatar
Clément committed
80
- **`label-xyz`**: Set the label for the field `xyz`
81
- **`placeholder-xyz`**: Set the placeholder for the field `xyz`
82
- **`editable-xyz`**: Add an "edit" button next to the `xyz` field to let the user edit it. The changes are saved as soon as the field loses focus.
83 84
  The editable attribute works with the following widgets: `solid-display-div`, `solid-display-labelled-div`, `solid-display-mailto` and `solid-display-tel`
- **`counter-template`**: To display the number of resources fetched by the `solid-display`.
85
  It takes a string in which you can use HTML tags, and the `counter` variable to add the number.
86
  i.e. `"<strong>${counter} results</strong>"`
87 88
- **`extra-context`**: The id of the `<script>` tag which contains the context you want to add for this component. An extra context looks like this:
  ```html
Clément's avatar
Clément committed
89 90 91
  <script id="custom-context" type="application/ld+json">
    { "user": "https://api.test-paris.happy-dev.fr/users/" }
  </script>
92 93
  ```
  If your `<script>` tag has the attribute `data-default-context`, this extra context will be applied on all the components which doesn't have an `extra-context` attribute.
94 95 96
- **`loader-id`**: Id of the loader element you want to display during the loading time.
- **`class-xyz`**: Class attribute added to the fields `xyz`.
- **`child-xyz`**: add attribute `xyz` to all children.
97 98 99
- **`nested-field`**: Name of the field of the requested resource to display.
  Useful when the source url is auto-generated (for instance, with the attribute `bind-resources`) but you need to display another field of this source.

100
- **`default-xyz`**: Value displayed for field `xyz` when it's empty or not defined
101 102
- **`empty-widget`**: Widget to display when there is no element in the container
- **`empty-value`**: To display a value in the empty widget. It can be accessed in the widget like this: `${value}`
Alexandre's avatar
Alexandre committed
103

104
**API:**
105
In Javascript, you have access to different variables and methods on a `solid-display` element:
106 107 108 109 110
- `sibDisplay.resource`: returns the Proxy of the current resource
  - `sibDisplay.resource.clearCache()` (async): clears the cache of the store for this resource
- `sibDisplay.resourceId`: returns the id of the current resource


111
### `solid-form`
Alexandre's avatar
Alexandre committed
112 113 114

Receives the URL of a ressource via its `data-src` attribute, and displays a form to edit the resource.
If given the URL of a container of ressources, and displays a creation form to add a resource to the container.
Clément's avatar
Clément committed
115

Alexandre's avatar
Alexandre committed
116
```html
117
<solid-form data-src="http://localhost:8000/todos/"></solid-form>
Alexandre's avatar
Alexandre committed
118
```
Clément's avatar
Clément committed
119

Alexandre's avatar
Alexandre committed
120 121
**Attributes:**

122 123
- **`label-xyz`**: When displaying a form, the default labels are the fields names of the model. If you want something fancier, you can set this attribute.
  i.e. `label-username="Your name"`
124 125
- **`naked`**: When the attribute is set, the submit button will be removed.
  It's particularly useful to prevent the nested forms to display their own submit button.
126
- **`upload-url-xyz`**: URL to upload file for field `xyz`, it automatically set `widget-xyz` to `solid-form-file` if net defined. 
127
  It's particularly useful with a dropdown field.
128
- **`submit-button`**: Text of the submit button of the form.
129
- **`range-xyz`**: URL of a container which list the accepted values for the field `xyz`.
130
  It's particularly useful with a dropdown field.
131
- **`partial`**: Add this attribute when the form does not include all the fields of the resource to update.
Alexandre's avatar
Alexandre committed
132

133
### `solid-ac-checker`
Alexandre's avatar
Alexandre committed
134 135

Hides an element from the page if the current user doesn't have the required permissions on it.
Clément's avatar
Clément committed
136

Alexandre's avatar
Alexandre committed
137
```html
138 139
<solid-ac-checker permission="acl:Write" bind-resources>
  <solid-route name="member-edit">
Clément's avatar
Clément committed
140
    <div>Edit</div>
141 142
  </solid-route>
</solid-ac-checker>
Alexandre's avatar
Alexandre committed
143 144 145
```

**Attributes :**
Clément's avatar
Clément committed
146

147 148 149 150 151 152 153 154
- **`permission`**: Displays the element if the user has the specified right
- **`no-permission`**: Displays the element if the user has not the specified right

Possible values:
- [acl:Read](https://github.com/solid/web-access-control-spec#aclread)
- [acl:Write](https://github.com/solid/web-access-control-spec#aclwrite)
- [acl:Append](https://github.com/solid/web-access-control-spec#aclappend)
- [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol)
Alexandre's avatar
Alexandre committed
155

156
### `solid-calendar`
157

158 159 160 161 162
Receives the URL of a resource or of a container of resources via its `data-src` attribute, and displays it in a **calendar**. Here is the list of fields needed to display the resources properly:

- `name`: name of the event displayed on the calendar
- `date`: date on which the resource will be displayed

163
Like for solid-display, filters and searching capabilities can be easily added to interact with the list of data being displayed.
164

165
### `solid-map`
166

167 168 169 170 171 172
Receives the URL of a resource or of a container of resources via its `data-src` attribute, and displays it on a **map**. Here is the list of fields needed to display the resources properly:

- `name`: name of the event displayed on the calendar
- `lat`: latitude on which the resource will be displayed
- `lng`: longitude on which the resource will be displayed

173
Like for solid-display, filters and searching capabilities can be easily added to interact with the list of data being displayed.
174

175
### `solid-widget`
Alexandre's avatar
Alexandre committed
176

Clément's avatar
Clément committed
177
Take a `name` as an attribute and a HTML template, and create an HTML custom element you can use as a widget. i.e.
178

179 180
```html
<!-- Your custom widget to display a customer... -->
181
<solid-widget name="my-custom-widget">
182 183 184
  <template>
    <h2>Customer name: ${value.name}</h2>
  </template>
185
</solid-widget>
186

187 188
<!-- ... used in a solid-display -->
<solid-display
189
  data-src="http://server/projects/"
Matthieu Fesselier's avatar
Matthieu Fesselier committed
190
  fields="name, customer"
Clément's avatar
Clément committed
191
  widget-customer="my-custom-widget"
192
></solid-display>
193 194
```

195
In a `solid-widget`, you have access to these values:
196 197 198 199 200 201

- **`id`**: id of the displayed resource
- **`value`**: all the values of the current resources
- **`name`**: name of the current field
- **`label`**: if defined, label of the current field
- **`range`**: if defined, range of the current field
202

203
> NB: Do not forget to define your custom template in a `<template>` tag. Otherwise, your widget will not be declared properly.
204

205
### `solid-delete`
Matthieu Fesselier's avatar
Matthieu Fesselier committed
206 207 208 209

Receives the URL of a resource or of a container of resources via its `data-src` attribute, and displays a button to delete it when clicked.

```html
210
<solid-delete data-src="http://localhost:8000/conversations/9/"></solid-delete>
Matthieu Fesselier's avatar
Matthieu Fesselier committed
211 212 213 214 215 216 217 218 219 220 221
```

**Attributes:**

- **`data-src`**: The uri of the LDP resource you want to delete.
- **`data-label`**: The text to display on the delete button.

**Events:**

- **`resourceDeleted`**: triggered when the resource is successfully deleted.

222

223 224 225 226
## Widgets

The following widgets are available:

227
### Display widgets
Clément's avatar
Clément committed
228

229 230 231 232 233 234 235 236 237 238 239
- **`solid-display-value`** (default): Displays the value.
- **`solid-display-div`**: Displays the `value` inside a `<div>` HTML tag.
- **`solid-display-labelled-div`**: Displays the `value` inside a `<div>` HTML tag, after the `label` contained in a `<label>` HTML tag
- **`solid-display-multiline`**:Displays the `value` inside a `<div>`, `\n` are replaced by `<br>`.
- **`solid-display-labelled-boolean`**: Displays the `label` inside a `<label>` HTML tag if the `value` is true
- **`solid-display-img`**: Inserts the `value` as the src attribute value of an `<img>` HTML tag.
- **`solid-display-mailto`**: Displays a link inside a `<a>` HTML tag with a `mailto:value` as path. If a label is defined for this field, it's displayed as the content of the link.
- **`solid-display-tel`**: Displays a link inside a `<a>` HTML tag with a `tel:value` as path
- **`solid-display-link`**: Displays a link inside a `<a>` HTML tag with the value as path, and the label as text content
- **`solid-display-date`**: Displays a date in the browser's default locale format
- **`solid-display-date-time`**: Displays a date and a time in the browser's default locale format
240

241
### Form widgets
Clément's avatar
Clément committed
242

243 244 245 246 247 248 249 250 251 252 253 254 255 256
- **`solid-form-label-text`**: Inserts an `<input/>` HTML tag of type "text", in a `<label>` HTML tag.
- **`solid-form-checkbox`**: Inserts an `<input/>` HTML tag of type "checkbox", in a `<label>` HTML tag.
- **`solid-form-date`**: Inserts an `<input/>` HTML tag of type "date", in a `<label>` HTML tag.
- **`solid-form-range-date`**:
- **`solid-form-json`**: Inserts an `<input/>` HTML tag of type "text", in a `<label>` HTML tag, and with its `value` converted from JSON to string
- **`solid-form-placeholder-text`**: Inserts an `<input/>` HTML tag of type "text", with the `label` as placeholder.
- **`solid-form-textarea`**: Inserts an `<textarea>` HTML tag in a `<label>` HTML tag.
- **`solid-form-dropdown`**: Inserts a `<select>` HTML tag to select a unique value from a list. The list is provided via the `range-xyz`, which expects a container's URL. **xyz** is the name of the field using the `solid-form-dropdown` widget.
- **`solid-form-placeholder-dropdown`**: Inserts a `<select>` HTML tag to select a unique value from a list. It has no label but a default disabled value as a label
- **`solid-form-auto-completion`**: Inserts a `<input />` HTML tag and load an autocomplete plugin. The list is provided via the `range-xyz`, which expects a container's URL. **xyz** is the name of the field using the `solid-form-auto-completion` widget.
- **`solid-form-number`**: Inserts an `<input/>` HTML tag of type "number", in a `<label>` HTML tag.
- **`solid-form-range-number`**:
- **`solid-form-file`**: Inserts an `<input/>` and an `<input type="file"/>`. when a file is selected it's uploaded, URL of file is returned by request and set as the `<input/>` value. The upload URL is provided via the `upload-url` attribute.
- **`solid-form-hidden`**: Inserts an `<input/>` HTML tag of type "hidden", in a `<label>` HTML tag.
257

258 259
### Multiple widgets

260 261 262
- **`solid-multiple`** (default for display): Inserts all the widgets in a `<solid-multiple>` tag.
- **`solid-multiple-form`** (default for forms): Inserts all the widgets in a `<solid-multiple-form>` tag, with a "remove" button for each widget, and an "add" button.
- **`solid-multiple-select`**: Inserts all the values as `<option>` in a `<select>` tag with a `multiple` attribute.
263 264

### Set widgets
265 266 267 268
- **`solid-set-default`** (default): Inserts content directly in the set tag.
- **`solid-set-div`**: Inserts content in a `<div/>` HTML tag
- **`solid-set-ul`**: Inserts content in a `<ul/>` HTML tag
- **`solid-set-fieldset`**: Inserts content in a `<fieldset/>` HTML tag
269

270
### Actions widgets
Clément's avatar
Clément committed
271

272
- **`solid-action`**: Displays a link inside a `<solid-link>` tag with `src` for the `data-src` attribute, `value` for the `next` attribute and `label` as text content
Clément's avatar
Clément committed
273

Clément's avatar
Clément committed
274 275
## Helpers fonctions

Clément's avatar
Clément committed
276 277 278 279 280 281
| Function             | Parameters            | Description                                                                                                                    |
| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `uniqID`             |                       | create an uniq ID, used for example to associate input with label                                                              |
| `stringToDom`        | `html`                | parse html string and return DOM fragment                                                                                      |
| `evalTemplateString` | `str, variables = {}` | eval a string as an es6 template string. example: `evalTemplateString('name: ${first} ${last}', {first: 'John', last: 'Doe'})` |
| `importCSS`          | `[...stylesheets]`    | add style in document if not present                                                                                           |
282

Sylvain Le Bon's avatar
Sylvain Le Bon committed
283 284
## Events

Clément's avatar
Clément committed
285 286
| Event name       | Fired by                                             | Fired when                                                                        |
| ---------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------- |
287 288 289
| `resourceSelect` | `solid-display`, `solid-calendar`, `solid-map`             | the user clicks an child in the list, with the resource as a detail of the event. |
| `populate`       | `solid-display`, `solid-form`, `solid-calendar`, `solid-map` | the component got and displayed all its datas.                                    |
| `save`           | `solid-form`                                           | the user validates the form.                                                      |
290

291
## Contribute
Clément's avatar
Clément committed
292

293 294
If you want to contribute to `sib-core`, you may be interested by the [developers documentation](doc/README-developers.md).

Sylvain Le Bon's avatar
Sylvain Le Bon committed
295 296
## License

297
Licence MIT
298