README.md 6.06 KB
Newer Older
1
# CubicWeb Linked Data Browser
Laurent Wouters's avatar
Laurent Wouters committed
2

3
The toolkit for the production of a browser of the web of data.
Laurent Wouters's avatar
Laurent Wouters committed
4

5
6
7
8
## Repository structure

This repository contains multiple packages. It is structured as follow:

9
- `libview` contains the sources for the NPM package `@logilab/libview`.
10
  This package defines the common interface that has to be implemented by views for the web of data browser.
11
- `extension` contains the sources for the Chrome and Firefox web extension (`@logilab/ld-browser`) that really implements the browser for the web of data.
12
  To use the browser, this extension has to be deployed in a regular web browser.
13
- `views-*` contain the sources for specialized views that can be leveraged by the web of data browser.
14
  They mostly take the form of NPM projects.
Laurent Wouters's avatar
Laurent Wouters committed
15
  - `views-logilab` contains the sources for the Person and Book views.
16
17
18
19
20
21
22
23
24
25
26
27
28

## General concepts

The general idea for this browser of the web of data is to provide uniform views for data regardless of their providers.
Views could be specialized according to the types of data by should be uniform across providers.

In this project, the browser for the web of data is implemented as an extension to a web browser.
The views themselves are designed to be defined externally and can be externally defined and dynamically loaded by the browser so that it is possible to contribute new views without having to modify the browser.

A view itself is defined by two artifacts: a descriptor (JSON object) and an implementation (Javascript module).
For the browser to detect and use the view, a corresponding source has to be added in the browser's configuration, pointing to the location of the descriptor.
The descriptor then points to the location of the Javascript file containing the implementation that can be dynamically loaded by the browser.

29
30
## How to build

31
32
33
34
This project uses a build environment defined as a Docker image in the `.releng` folder.
You will need Docker to build.
If not already present, the Docker image for the build environment will be automatically built, by executing `./.releng/build-env.sh`.
You can manually run this command if you wish to refresh the build environment.
35

36
To build the project, run:
37
38
39
40
41

```sh
./build.sh
```

42
Alternatively, to locally build the project without using the provided environment, run:
Laurent Wouters's avatar
Laurent Wouters committed
43
44

```sh
45
./build-src.sh
Laurent Wouters's avatar
Laurent Wouters committed
46
```
47

48
49
50
51
52
Doing so, the minimal working versions of node.js and npm are:

* `node --version`: `v8.10.0`
* `npm --version`: `3.5.2`

53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
## Access to build environment

The build environment can be invoked using the `cmd` script at the repository's root by passing the wanted command as a parameter to it.
The sources repository is mapped to the `/src` folder in the build environment.
For example, to execute the `build-src.sh` script in the context of the specified build environment (instead of the local host):

```sh
./cmd /src/build-src.sh
```

The `cmd` script tries to lookup the current folder relative to the repository's root in order to execute the requested command within the same folder.
It is then possible to execute:

```sh
cd extension
../cmd npm install
```

71
72
## Run linters

73
74
75
Linters for the components are called during the normal process.
It is also possible to manually invoke the configured linter as follow:

76
77
78
79
80
```sh
cd extension
../cmd run linter
```

81
82
83
84
85
## How to use

This project contains a set of contributed views that must be served (by a web server) in order to be used.
In order to use this project, the definition of a runtime environment is provided in the form of a `docker-compose.yml` file.
Once the project has been built, simply execute:
86
87

```sh
88
docker-compose up -d
89
90
```

91
Run `docker-compose down` to terminate the environment.
92

93
94
This environment launches a web server (Apache), accessible at [http://localhost/](http://localhost/), that serves the contributed views.
The descriptors for the views can then be accessed at [http://localhost/index.vd.json](http://localhost/index.vd.json).
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
This is the URI that can be defined as a source of views for the browser.

Then, the web extension implemented in the `extension` repository has to be deployed into a compatible web browser such as Firefox or Chrome.
The web extension is made into the `build` directory and can be deployed as an unpacked extension in Chrome or Firefox for debuggin pruposes.

In Chrome, go to [chrome://extensions/](chrome://extensions/) and activate the developer mode (toggle un upper-right corner).
Then click on the appearing `Load Unpacked` button and select the `build/` directory in this repository (after build).

![Chrome developer mode](https://developer.chrome.com/static/images/get_started/load_extension.png)

In Firefox, go to [about:debugging](about:debugging), click "Load Temporary Add-on" and open the extension's directory and select the `build/manifest.json` file. Details at [Mozilla MDN](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox).

Once this is done, go to a web page with data attached to it, such as [dbpedia Claude Debussy](http://dbpedia.org/page/Claude_Debussy).
The extension icon shall lit up whenever data has been detected for the page.

To register custom views, click on the extension's icon, then on the gear in the appearing popup.
There should be two fields available to add add a new source of views.
112
Simply enters the name (can be anything) for the source and the targer URI, for example [http://localhost:8080/index.vd.json](http://localhost:8080/index.vd.json).
113
114
115
Then validate to register the source.
The corresponding views should then be automatically loaded and used when appropriate.

116
117
118
119
120
121
122
123
## How can I contribute?

The simplest way to contribute is to:

- Fork this repository.
- Fix [some issue](https://www.logilab.org/project/cweb) or implement a new feature.
- Create a pull request and subimit it.

124
## License
125

126
127
128
129
130
131
132
This software is licenced under the Lesser General Public License (LGPL) v3.
Refers to the `LICENSE.md` file at the root of the repository for the full text, or to [the online version](http://www.gnu.org/licenses/lgpl-3.0.html).

## Acknowledgements

This work is financed by [Logilab](https://www.logilab.fr/), France.
Copyright 2003-2018 LOGILAB S.A. (Paris, FRANCE), all rights reserved.