README.md

# Linked Data Browser

The toolkit for the production of a browser of the web of data.

## Repository structure

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

- `rdflib-types` contains the sources for the NPM package `@types/rdflib`.
  This package defines the typing stubs in Typescript for the [rdflib.js](https://github.com/linkeddata/rdflib.js/) library, i.e. `rdflib` on NPM.
  This package is defined here at this time, but the aim is to externalize it to the [`@types` organization](https://github.com/DefinitelyTyped/DefinitelyTyped).
- `librdf` contains the sources for the NPM package `@logilab/librdf`.
  This package defines some utility API for the manipulation of RDF datasets.
- `libview` contains the sources for the NPM package `@logilab/libview`.
  This package defines the common interface that has to be implemented by views for the web of data browser.
- `extension` contains the sources for the Chrome and Firefox web extension (`@logilab/ld-browser`) that really implements the browser for the web of data.
  To use the browser, this extension has to be deployed in a regular web browser.
- `views-*` contain the sources for specialized views that can be leveraged by the web of data browser.
  They mostly take the form of NPM projects.

## 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.

## How to use

The first step is to build all the artifacts in this repository:

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

Second, the contributed views (descriptors and implementations) have to be served by a web server so that the web extension may later refer to them.
To serve the views defined by a particular `views-xxx` package, go to the corresponding folder and execute:

```sh
npm run serve
```

This will launch a development web server that serves the views so that the it can be referred to by the browser.
For example, for serving the `dbpedia`-specific views:

```sh
cd views-dbpedia
npm run serve
```

The descriptors for the views can then be accessed at [http://localhost:8080/index.vd.json](http://localhost:8080/index.vd.json).
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.
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).
Then validate to register the source.
The corresponding views should then be automatically loaded and used when appropriate.

## 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.

## License

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.