@@ -63,42 +63,46 @@ _Boolean_. Controls whether the in-document highlights are shown by default.
...
@@ -63,42 +63,46 @@ _Boolean_. Controls whether the in-document highlights are shown by default.
### Annotation services
### Annotation services
These settings configure which annotation services the client connects to and where
The `services` setting configures which annotation services the client
it loads assets from. By default, the client will connect to the public
connects to (for example to login, retrieve annotations, and save annotations).
Hypothesis service at [hypothes.is](https://hypothes.is).
By default, if no `services` setting is given, the client connects to the
public Hypothesis service at [hypothes.is](https://hypothes.is).
#### `assetRoot`
_String_. The URL from which client assets are loaded.
#### `sidebarAppUrl`
_String_. The URL for the sidebar application which displays annotations
(Default: _https://hypothes.is/app.html_).
#### `services`
#### `services`
_Array_. A list of additional annotation services which the client should
_Array_. A list of alternative annotation services which the client should
retrieve annotations from, optionally including information about the identity
connect to instead of connecting the the public Hypothesis service at
of the user on that service. This list is in addition to the public
[hypothes.is](https://hypothes.is/).
[Hypothesis](https://hypothes.is/) service.
May optionally include information (in the form of a grant token) about the
identity of the user accounts that the client is logged in to on those
services.
**N.B.** Currently only one additional annotation service is supported - only
**N.B.** These settings are currently still experimental and may change without
the first item in this `services` array is used, and any further items in the
warning.
array are ignored.
Each item in the array should be an object describing an annotation service,
**N.B.** Currently only one alternative annotation service at a time is
with the following keys:
supported - only the first item in this `services` array is used, and any
further items in the array are ignored.
*`authority` _String_. The domain name which the annotation service is associated with.
Each item in the `services` array should be an object describing an annotation
service, with the following keys:
*`grantToken` _String|null_. An OAuth grant token which the client can exchange for an access token in order to make authenticated requests to the service. If _null_, the user will only be able to read rather than create or modify annotations. (Default: _null_)
*`authority` _String_. The domain name which the annotation service is
associated with.
*`icon` _String|null_. The URL to an image for the annotation service. This image will appear to the left of the name of the currently selected group. The image should be suitable for display at 16x16px and the recommended format is SVG.
*`grantToken` _String|null_. An OAuth 2 grant token which the client can
exchange for an access token in order to make authenticated requests to the
service. If _null_, the user will be able to read but not create or modify
annotations. (Default: _null_)
*`onLoginRequest` _function_. A JavaScript function that the Hypothesis client
*`icon` _String|null_. The URL to an image for the annotation service. This
will call in order to login (for example, when the user clicks a login button
image will appear to the left of the name of the currently selected group.
in the Hypothesis client's sidebar).
The image should be suitable for display at 16x16px and the recommended
format is SVG.
*`onLoginRequest` _function_. A JavaScript function that the client will
call in order to login (for example, when the user clicks a login button in
the Hypothesis client's sidebar).
This setting can only be [set using window.hypothesisConfig](#configuring-the-client-using-javascript).
This setting can only be [set using window.hypothesisConfig](#configuring-the-client-using-javascript).
...
@@ -108,8 +112,30 @@ with the following keys:
...
@@ -108,8 +112,30 @@ with the following keys:
No arguments are passed to the `onLoginRequest` function.
No arguments are passed to the `onLoginRequest` function.
The `onLoginRequest` function should cause a login procedure for the hosting
The `onLoginRequest` function should cause a login procedure for the hosting page
page to be performed - for example by redirecting to a login page, or by
to be performed - for example by redirecting to a login page, or by opening
opening a popup login window. After a successful login the hosting page
a popup login window. After a successful login the hosting page should
should reload the original page with a non-null `grantToken` for the
reload the original page with a non-null `grantToken` for the logged-in user
logged-in user in the `services` configuration setting.
in the `services` configuration setting.
### Asset and sidebar app location
These settings configure where the client's assets are loaded from.
**N.B.** These settings are currently still experimental and may change without
warning.
#### `assetRoot`
_String_. The root URL from which assets are loaded. This should be set to the
URL where the contents of the `hypothesis` package are hosted, including the
trailing slash. (Default: For production builds:
_https://cdn.hypothes.is/hypothesis/X.Y.Z/_, for development builds:
_http://localhost:3001/hypothesis/X.Y.Z/_. _X.Y.Z_ is the package version from
`package.json`)
#### `sidebarAppUrl`
_String_. The URL for the sidebar application which displays annotations
(Default: _https://hypothes.is/app.html_ . If the `H_SERVICE_URL` env var is
