Commit 91bf9ed8 authored by Tobinsk's avatar Tobinsk
Browse files

Merge branch 'readme' into 'master'

Readme

See merge request !9
parents 25ab80c8 ff871041
# 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 histhub-net widget can display resources from [histhub linking services](https://histhub.ch/tag/geolinker/). You can integrate it into your site and enrich your content with links to other projects.
__The widget and the apis are in beta status. They may change in the future.__
## Partner
To use the webcomponent and the apiservice you have to be a partner of histhub. If you are interested, please send us a mail.
__The widget and the api's are in beta status. They may change in the future.__
## Webcomponent
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.
## Integration
Just have a look at the example folder. There you can find a set of working examples.
Just have a look at the [example folder](examlpe/index.html). There, you can find a set of working examples.
```html
<html>
<head>
......@@ -15,13 +20,13 @@ Just have a look at the example folder. There you can find a set of working exam
</html>
```
```html
<!-- add the component wehre you like to display the links -->
<!-- add the component where you like to display the links -->
<histhub-widget endpoint="ENDPOINT" resolver="RESOLVER" location="URL TO LOOK FOR"></histhub-widget>
```
## 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.
The endpoint defines the rest-api, where the widget fetches 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/
......@@ -29,42 +34,42 @@ The endpoint defines the restapi, where the widget makes the call to get the lin
* Geolinker https://api.geolinker.histhub.ch/v1-1/similarto/ (newer apis)
* Orgalinker https://api.orgalinker.histhub.ch/v1/sameas/
Choose one of the endpoint to get links for your resource
Choose one of the endpoints 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.
The endpoint uses different technologies to generate the links. Those technologies are called resolver. You need to define a resolver to get the links for your preferences.
__Tagcloud and Orgalinker__
For those two services we provide the `resolvermanual` . The links provided by this resolver are done by humans. See example 1 and example 2
For these two services we provide the `resolvermanual` . The links provided by this resolver are created by humans. See example 1 and example 2.
__Geolinker__
The geolinker provides for the `sameas` endpoint the `resolverneo4j` resolver. The links provided by this resolver are done semi-automatically. See example 3
The geolinker provides the [resolverneo4j](https://source.dodis.ch/histhub/resolver-elasticsearch) resolver for the [sameas](https://source.dodis.ch/histhub/resolver-neo4j) endpoint. The links provided by this resolver are done semi-automatically. See example 3.
For the `similarto` endpoint the geolinker provides a `elasticsearchresolver`. The data are guessed based on a matching algorithm. See example 4
For the `similarto` endpoint the geolinker provides an `elasticsearchresolver`. The data is 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
The location is an optional parameter. By default the widget uses the current `window.location.href` to make the request. You can specify the location url through the url parameter.
### Template
The `tempate` is an optional parameter. You can provide your own template to modify the structure and styles of the widget.
The `template` is an optional parameter. You can provide your own template to modify the structure and styles of the widget.
### language (beta)
The `language` parameter is optional (default=de) and let 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`.
The `language` parameter is optional (default=de) and lets you define the language of the provider. We resolve the name of the provider through the [url pattern](https://source.dodis.ch/histhub/url-resolver). Possible languages are `de`, `fr`, `it` and `en`.
### 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
The architecture of the `geolinker` waits for a certain timeout (default=2000) to find an answer to the query. If you often get 404, try setting a higher timeout.
### Link-target
By default the target of a link is `_blank`. If you wish to change this you can configure the zarget over the `link-target` attribute.
By default the target of a link is `_blank`. If you wish to change this you can configure the target over the `link-target` attribute.
## 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
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 and will not interfere with any other styles in your site. There are two options 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 almost 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
#### Credits
You can change the `credits` in the corresponding slot. Please make sure you mention our work. In the example
#### 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
[Slots](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots) provide the possibility to override some part of the webcomponent. The histhub-widget provides a `title`, a `credits` and a `default` slot.
#### Title (slot)
You can change the title 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 sites css rules apply for this element. Example #6 changes the color of the heading.
#### Credits (slot)
You can change the `credits` in the corresponding slot. Please make sure you mention our work. In the example #10 we changed this slot.
#### 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.
### 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](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).
To change basic visual aspects of the component you can define [css variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) and override default settings. You have the following options to change the styles of the [shadow dom](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).
```css
:root {
--histhub-h3-maring: 0 0 0 0.5rem;
......@@ -89,4 +94,9 @@ To change basic visual aspects of the component you can define css variables and
### 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.
## Compatibility
This is a modern approach to build custom web-elements. Not all browsers support this yet.
* Css-cars are supported only in modern browsers (ie-edge > 15)
* Webcomponents are supported only in modern browsers (ie-edge > 18, FF > 62)
......@@ -22,10 +22,15 @@
* example with css vars
*/
#vars {
margin-left: 150px;
background-color: #e7ecf5;
margin-top: 1em;
--histhub-li-display: inline-block;
--histhub-li-padding: 0 0.5rem 0 0;
--histhub-a-hover-color: blue;
--histhub-li-padding: 0 1rem 0 0;
--histhub-a-color: #009;
--histhub-a-hover-color: #03c;
--histhub-a-hover-text-decoration: none;
--histhub-ul-margin: 0;
}
</style>
</head>
......
......@@ -18,8 +18,13 @@
/** a **/
--histhub-a-display: inline-block;
--histhub-a-color: black;
--histhub-a-text-decoration: none;
--histhub-a-hover-color: grey;
--histhub-a-hover-text-decoration: underline;
/** credits **/
--histhub-credits-font-size: 75%;
--histhub-credits-margin: 0;
}
ul {
......@@ -38,6 +43,7 @@
a {
color: var(--histhub-a-color);
display: var(--histhub-a-display);
text-decoration: var(--histhub-a-text-decoration);
}
a:hover {
......@@ -51,13 +57,15 @@
color: var(--histhub-h3-color);
}
.credits {
font-size: 75%;
font-size: var(--histhub-credits-font-size);
margin: var(--histhub-credits-margin);
}
</style>
<slot name="title"><h3>Histhub Links</h3></slot>
<div id="links">Loading data...</div>
<slot name="credits"><p class="credits">Links powered by <a href="//histhub.ch" target="_blank" title="Histhub">histHub</a> - die Vernetzungsinitiative des Consortium Historicum</p></slot>
<slot name="credits">
<p class="credits">Links powered by <a href="//histhub.ch" target="_blank" title="Histhub">histHub</a> - die Vernetzungsinitiative des Consortium Historicum</p></slot>
<slot></slot>`;
class HisthubWidget extends HTMLElement {
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment