Readme.md 5.3 KB
Newer Older
Tobias Steiner's avatar
Tobias Steiner committed
1
# Histhub-net widget
Lena Heizmann's avatar
Lena Heizmann committed
2
The histHub-net widget can display sameas resources from [histhub](histhub.ch) linking services. histHub-net connects identical entities from different sources. This widget makes those links (concordances) visible. You can integrate it into your site and display links to other providers.
Tobias Steiner's avatar
Tobias Steiner committed
3 4
 
 __The widget and the api's are in beta status. They may change in the future.__
Tobias Steiner's avatar
Tobias Steiner committed
5
## Webcomponent
Tobias Steiner's avatar
Tobias Steiner committed
6
The widget itself is a [webcomponent](https://en.wikipedia.org/wiki/Web_Components). It integrates smoothly into an existing website. You just need to add some markup and load a javascript file.
Tobias Steiner's avatar
Tobias Steiner committed
7
## Integration
Tobias Steiner's avatar
Tobias Steiner committed
8
Just have a look at the example folder. There you can find a set of working examples.
Tobias Steiner's avatar
Tobias Steiner committed
9 10 11 12
```html
<html>
<head>
    <!-- load the script in your header -->
Tobias Steiner's avatar
Typo  
Tobias Steiner committed
13
    <script src="./src/histhub-widget.js"></script>
Tobias Steiner's avatar
Tobias Steiner committed
14 15 16 17 18 19 20
</head>
</html>
```
```html
<!-- add the component wehre you like to display the links -->
<histhub-widget endpoint="ENDPOINT" resolver="RESOLVER" location="URL TO LOOK FOR"></histhub-widget>
```
Tobias Steiner's avatar
Tobias Steiner committed
21

Tobias Steiner's avatar
Tobias Steiner committed
22 23 24 25 26 27
## API
### Endpoint
The endpoint defines the restapi, where the widget makes the call to get the links. Currently we provide three endpoints for different resource types.
* Tagcloud https://api.tagcloud.histhub.ch/v1/sameas/
* Geolinker https://api.geolinker.histhub.ch/v1/sameas/
* Geolinker https://api.geolinker.histhub.ch/v1/similarto/
28 29
* Geolinker https://api.geolinker.histhub.ch/v1-1/sameas/ (newer apis)
* Geolinker https://api.geolinker.histhub.ch/v1-1/similarto/ (newer apis)
Tobias Steiner's avatar
Tobias Steiner committed
30 31
* Orgalinker https://api.orgalinker.histhub.ch/v1/sameas/

Lena Heizmann's avatar
Lena Heizmann committed
32
Choose one of these endpoint to get links for your resource
Tobias Steiner's avatar
Tobias Steiner committed
33
### Resolver
Lena Heizmann's avatar
Lena Heizmann committed
34
The endpoint uses different technologies to generate the links. Those technologies call a resolver. You need to define a resolver to get the links for your preferences.
Tobias Steiner's avatar
Tobias Steiner committed
35 36 37

__Tagcloud and Orgalinker__

Tobias Steiner's avatar
Tobias Steiner committed
38
For those two services we provide the `resolvermanual` . The links provided by this resolver are done by humans. See example 1 and example 2
Tobias Steiner's avatar
Tobias Steiner committed
39 40 41

__Geolinker__

Lena Heizmann's avatar
Lena Heizmann committed
42
The geolinker provides the  `resolverneo4j` resolver for the `sameas` endpoint. The links provided by this resolver are done semi-automatically. See example 3
Tobias Steiner's avatar
Tobias Steiner committed
43

Lena Heizmann's avatar
Lena Heizmann committed
44
For the `similarto` endpoint the geolinker provides an `elasticsearchresolver`. The data are guessed based on a matching algorithm. See example 4
Tobias Steiner's avatar
Tobias Steiner committed
45 46 47

### Location
The location is an optional parameter. By default the widget uses the current window.location.href to make the request. You can specify the url to look for over the url parameter
Tobias Steiner's avatar
Tobias Steiner committed
48
### Template
Lena Heizmann's avatar
Lena Heizmann committed
49
The `template` is an optional parameter. You can provide your own template to modify the structure and styles of the widget.
50
### language (beta)
Lena Heizmann's avatar
Lena Heizmann committed
51
The `language` parameter is optional (default=de) and lets you define the language of the provider. We resolve the name of the provider over the url pattern. Possible languages are `de`, `fr`, `it` and `en`.
52 53
### Timeout
The architecture of the `geolinker` waits for a certain timeout (default=2000) for the microservices to find an answer to the query. You can define that timeout. If you often get 404 try to set a higher timeout 
54
### Link-target
Lena Heizmann's avatar
Lena Heizmann committed
55
By default the target of a link is `_blank`. If you wish to change this you can configure the target with the `link-target` attribute.
Tobias Steiner's avatar
Tobias Steiner committed
56
## Styling
Lena Heizmann's avatar
Lena Heizmann committed
57
The webcomponent uses a [shadow dom](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) and encapsulates the styles. So it will not use your sites default css styles but also not change any other styles in your site. There are two options to override the components default styles:
Tobias Steiner's avatar
Tobias Steiner committed
58
### Slots
Lena Heizmann's avatar
Lena Heizmann committed
59
Slots provide the possibility to override some parts of the webcomponent. The histhub-widget provides a `title` and a `defaut` slot.
60
#### Heading (slot)
Lena Heizmann's avatar
Lena Heizmann committed
61
You can change the heading of the widget with the `title` slot. This slot will override the default title. In almost all examples we use this slot to change the title. If you override a slot, your site css rules apply for this element. Example #6 changes the color of the heading
Tobias Steiner's avatar
Tobias Steiner committed
62
#### Credits
Lena Heizmann's avatar
Lena Heizmann committed
63
You can change the `credits` in the corresponding slot. Please make sure you mention our work. In the example #10 you can see how credits are added
Tobias Steiner's avatar
Tobias Steiner committed
64
#### Default Slot
Lena Heizmann's avatar
Lena Heizmann committed
65
If you want to display additional text beneath the links you can use the default slot. Just put the content inside the histhub-widget element. Example #7 adds additional information under the links
66
### Css Variables
Lena Heizmann's avatar
Lena Heizmann committed
67
To change basic visual aspects of the component you can define css variables and override default settings. You have the following options to change the styles of the shadow dom.
Tobias Steiner's avatar
Tobias Steiner committed
68 69
```css
:root {
Lena Heizmann's avatar
Lena Heizmann committed
70
    --histhub-h3-margin: 0 0 0 0.5rem;
Tobias Steiner's avatar
Tobias Steiner committed
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
    --histhub-h3-color: #000;
    --histhub-h3-size: 120%;
    /** ul element **/
    --histhub-ul-padding: 0;
    --histhub-ul-margin: 1rem 0 0 0;
    --histhub-ul-display: block;
    --histhub-ul-list-style: circle inside;
    /** li element **/
    --histhub-li-display: list-item;
    --histhub-li-padding: 0;
    --histhub-li-margin: 0;
    /** a Element **/
    --histhub-a-display: inline-block;
    --histhub-a-color: black;
    --histhub-a-hover-color: grey;
    --histhub-a-hover-text-decoration: underline;
}
```
### Provide a template
Lena Heizmann's avatar
Lena Heizmann committed
90
You can provide your own template with your own styles. This will give you the power to modify every visual aspect of the webcomponent. You can define your own styles for the shadow dom and add or remove html elements. The example #8 uses a custom template.
Tobias Steiner's avatar
Tobias Steiner committed
91 92