Readme.md 4.35 KB
Newer Older
Tobias Steiner's avatar
Tobias Steiner committed
1
2
3
4
# Histhub-net widget
The histhub-net widget can display sameas resources from histhub linking services. You can integrate it into your site and display links to other providers.
 
 __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
32
33
34
35
36
37
* Orgalinker https://api.orgalinker.histhub.ch/v1/sameas/

Choose one of the endpoint to get links for your resource
### Resolver
The endpoint uses different technologies to generate the links. Those technologies calls resolver. You need to define a resolver to get the links for your preferences.

__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__

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

For the `similarto` endpoint the geolinker provides a `elasticsearchresolver`. The data are guessed based on a matching algorithm. See example 4

### 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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
### Template
The `tempate` is an optional parameter. You can provide your own template to modify the structure and styles of the widget.
## Styling
The webcomponent uses a shadow dom and encapsulate 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 option to override the component default styles
### Slots
Slots provides the possibility to override some part of the webcomponent. The histhub-widget provides a `title` and a `defaut` slot.
### Heading (slot)
You can change the Heading of the widget with the `title` slot. This slot will override the default title. In allmost all examples we use this slot to change the title. If you override a slot your site css rules applies for this element. Example #6 changes the color of the heading
#### Default Slot
If you want to display some 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
### Use css Variables
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.
```css
:root {
    --histhub-h3-maring: 0 0 0 0.5rem;
    --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
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 shadowdom and add or remove html elements. The example #8 uses a custom template.
Tobias Steiner's avatar
Tobias Steiner committed
83
84