Configuring the Client¶

This page documents the configuration settings that you can use to configure the Hypothesis client once it’s embedded in your website.

Configuring the Client Using JSON¶

The Hypothesis client can be configured by providing a JSON config object in the body of the hosting page:

<script type="application/json" class="js-hypothesis-config">
  {
    "openSidebar": true
  }
</script>
<script async src="https://hypothes.is/embed.js"></script>

Not all configuration settings can be set in this way, some must be set using JavaScript (see below).

Note

The body of the .js-hypothesis-config tag must be valid JSON, invalid JSON will cause the entire config object to be ignored.

Configuring the Client Using JavaScript¶

window.hypothesisConfig()¶

Alternatively, the Hypothesis client can be configured from the hosting page by providing a JavaScript function named window.hypothesisConfig() that returns a configuration object. Some configuration settings (for example settings that register callback or event handler functions) can only be set from JavaScript:

window.hypothesisConfig = function () {
  return {
    "openSidebar": true
  };
};

Config Settings¶

Client Behavior¶

These settings configure the behavior and initial state of the client when it loads.

openSidebar¶: Boolean. Controls whether the sidebar opens automatically on startup. (Default: false.)

showHighlights¶

String|Boolean. Controls whether the in-document highlights are shown by default. (Default: "always").

true or "always" - Highlights are always shown by default.

false or "never" - Highlights are never shown by default, the user must explicitly enable them.

"whenSidebarOpen" - Highlights are only shown when the sidebar is open.

Warning

The “always”, “never” and “whenSidebarOpen” values are currently still experimental and may change in future. true and false values are the stable API.

theme¶

String. Controls the overall look of the sidebar.(Default: classic).

"classic" - Enables the card view for annotations, the bucket bar, the sidebar minimize button, the highlights button and the new note button in the toolbar. It also disables the close button in the toolbar. The classic theme is enabled by default.

"clean" - Enables the clean view for annotations in the sidebar, disables the bucket bar, the sidebar minimize button, the highlights button and the new note button in the toolbar and enables the close button in the toolbar. It will also show a cleaner and more minimal onboarding tutorial.

enableExperimentalNewNoteButton¶

Boolean - Controls whether the experimental New Note button should be shown in the notes tab in the sidebar. (Default: false).

true - The button is shown.

false - The button is not shown.

usernameUrl¶

String. This allows you to specify a URL to direct a user to, in a new tab when they click on the annotation author link in the header of an annotation. The username is appended to the end of usernameUrl.

For example:

window.hypothesisConfig = function () {
  return {
    usernameUrl: 'https://partner.org/user/',
  };
};

services¶

Array. A list of alternative annotation services which the client should connect to instead of connecting to the public Hypothesis service at hypothes.is. May optionally include information (in the form of grant tokens) about user accounts that the client is logged in to on those services.

For example:

window.hypothesisConfig = function () {
  return {
    services: [{
      apiUrl: 'https://hypothes.is/api/',
      authority: 'partner.org',
      grantToken: '***',
      icon: 'https://openclipart.org/download/272629/sihouette-animaux-10.svg'
    }],
  };
};

By default, if no services setting is given, the client connects to the public Hypothesis service at hypothes.is.

Warning

The services setting is currently still experimental and may change in the future.

Note

Currently only one additional annotation service is supported - only the first item in this services array is used, and any further items in the array are ignored.

Each item in the services array should be an object describing an annotation service, with the following keys:

apiUrl¶: String. The base URL of the service API.

authority¶: String. The domain name which the annotation service is associated with.

grantToken¶: String|null. An OAuth 2 grant token which the client can send to the service in order to get an access token for making authenticated requests to the service. If null, the user will not be logged in and will only be able to read rather than create or modify annotations. (Default: null)

See also

Generating authorization grant tokens for how to generate grant tokens for the hypothes.is service.

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.

onLoginRequest¶

function. A JavaScript function that the Hypothesis client will call in order to log in (for example, when the user clicks a log in button in the Hypothesis client’s sidebar).

This setting can only be set using window.hypothesisConfig().

If the hosting page provides an onLoginRequest function then the Hypothesis client will call this function instead of doing its usual procedure for logging in to the public service at hypothes.is.

No arguments are passed to the onLoginRequest function.

The onLoginRequest function should cause a log in procedure for the hosting page to be performed - for example by redirecting to a log in page, or by opening a popup log in window. After a successful log in the hosting page should reload the original page with a non-null grantToken for the logged-in user in the services configuration setting.

onLogoutRequest¶

function. A JavaScript function that the Hypothesis client will call in order to log out (for example, when the user clicks a log out button in the Hypothesis client’s sidebar).

This setting can only be set using window.hypothesisConfig().

If the hosting page provides an onLogoutRequest function then the Hypothesis client will call this function instead of doing its usual procedure for logging out of the public service at hypothes.is.

No arguments are passed to the onLogoutRequest function.

The onLogoutRequest function should cause a log out procedure for the hosting page to be performed. After a successful log out the hosting page should reload the original page with no grantToken in the services configuration setting.

onSignupRequest¶

function. A JavaScript function that will be called when the user clicks the “Sign up” link in the sidebar. No arguments are passed and the return value is unused.

This setting can only be set using window.hypothesisConfig().

onProfileRequest¶

function. A JavaScript function that will be called when the user clicks the user profile (user name) link in the sidebar. No arguments are passed and the return value is unused.

This setting can only be set using window.hypothesisConfig().

onHelpRequest¶

function. A JavaScript function that will be called when the user clicks the “Help” link in the sidebar. No arguments are passed and the return value is unused.

This setting can only be set using window.hypothesisConfig().

branding¶

Branding lets you adjust certain aspects of the sidebar’s look and feel to better fit your site’s own look.

Object. The key-value pairings used to identify how the brandable elements in the sidebar should be presented. The allowed keys will be described below. The values will be directly mapped to the css styles for the elements which it affects. That means any valid css property for the specified type will work. For example, if the value type is a Color, you can specify any browser supported color value (hex, rgb, rgba, etc.).

For example:

window.hypothesisConfig = function () {
  return {
    branding: {
      appBackgroundColor: 'white',
      ctaBackgroundColor: 'rgba(3, 11, 16, 1)',
      ctaTextColor: '#eee',
      selectionFontFamily: 'helvetica, arial, sans serif'
    }
  };
};

The following keys are supported in the branding object. You will also see what value type we are expecting.

Warning

The branding setting is currently still experimental and may change in the future.

accentColor¶: Color. We have several areas in our client that have pops of color that are secondary to the primary call to action elements. Things such as the “more” and “less” links to expand and collapse large annotation bodies.

appBackgroundColor¶: Color. This will update the main background color of our app.

ctaBackgroundColor¶: Color. This will update the main call-to-action button backgrounds. A call-to-action button example would be our “Post to {Group Name}” button when making an annotation.

ctaTextColor¶: Color. This will update the text color inside of the call-to-action buttons.

selectionFontFamily¶: Font Family. The selection text is the part of the annotation card that reflects what the user highlighted when they made the annotation. This value will update the font-family of that text.

annotationFontFamily¶: Font Family. The annotation text is the actual annotation value that the user writes about the page or selection. This value will set the font-family of that text when it is being viewed as well as the font-family of the editor as the annotation is being written.

onLayoutChange¶

function. This function will be a registered callback to be invoked when the sidebar layout changes. Changes to the layout occur on load, when the sidebar is toggled to show and hide, and when the user adjusts the sidebar manually.

This setting can only be set using window.hypothesisConfig().

When a layout change happens the registered onLayoutChange function will receive a single Object as it’s argument. This object details the layout parameters after the change.

Layout object available fields:

expanded¶: Boolean. If the sidebar is open, this value will be true.

height¶: Number. The current visible height of the sidebar.

width¶: Number. The current visible width of the sidebar.

Asset and Sidebar App Location¶

These settings configure where the client’s assets are loaded from.

Warning

These settings are currently still experimental and may change in the future.

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").