Test Enterprise-Class Web CMS Scrivito Free for 30 Days
Test Scrivito Free for 30 Days

configure(options)

Sets global options for Scrivito.

Before you can start using any of the Scrivito API calls, you must configure the connected Scrivito CMS instance. The tenant ID can be found on your dashboard at my.scrivito.com. Use the SCRIVITO_TENANT value from the “Settings” tab and pass it to Scrivito.configure:

src/config/scrivito.js
Scrivito.configure({ tenant: "0123456789abcdef0123456789abcdef" });

You can also configure the mapping between browser URLs and pages in the CMS. If your homepage is not the default root page, you can specify a different page using a callback. For further details regarding the routing, see Customizing the Routing.

Scrivito.configure({
  homepage: () => Scrivito.Obj.getByPath("/en"),
  routingBasePath: "/js",
  tenant: "0123456789abcdef0123456789abcdef"
});

Options

  • tenant (String) – the ID of the tenant to use. This configuration key must be provided. The tenant ID is shown on your dashboard at my.scrivito.com. Use the value of SCRIVITO_TENANT from the “Settings” tab. To run your application without connecting it to your tenant and thus the content of your website, you can enable the in-memory tenant by specifying inMemory as the tenant ID. Please see In-memory tenant below for more details.
  • homepage (Function) – a callback that returns a CMS Obj representing the page at the root URI /. Default: Scrivito.Obj.root()
  • origin (String) – the origin of Scrivito.urlFor(target, options). This configuration is optional unless pre-rendering is enabled. The default is the origin of the current window location. The origin needs to be a valid domain with a schema, a host and, optionally, a port. Providing a path is not allowed. See below for an example.
  • routingBasePath (String) – prefix for all path-based routes handled by Scrivito. This configuration is optional.
  • visitorAuthentication (Boolean) – allow access to restricted content. Specify true if the visitor is known to be signed in, and a token will be made available (see setVisitorIdToken). See also: Authenticating Visitors and Displaying Restricted Content. Default: false
  • constraintsValidation (Function) – defines a callback for having an attribute validated by a third-party library, based on constraints. The underlying function receives a constraints object and returns an attribute validation callback. This configuration is optional.
  • endpoint (String) – defines the API endpoint the SDK connects to. Default: api.scrivito.com.
  • adoptUi (Boolean) – specifies whether editors should automatically use edit.scrivito.com. Default: false.
  • baseUrlForSite (Function) – receives a site ID and should return the base URL of this site if it exists. See multi-site configuration for more details.
  • siteForUrl (Function) – receives a URL and should return the site ID and the base URL of the site to which the URL belongs. See multi-site configuration for more details.
  • [New in 1.19.0]priority (String) – the rate limitation to be applied to API calls. Must be set to background for automated tasks such as prerendering and other scripts to not impact the live site and the UI. Default: foreground in a browser environment, background otherwise (e.g. with Node.js).
  • [New in 1.24.0]editorLanguage (String) – causes the Scrivito UI to always appear in a particular language, regardless of the user preferences or browser settings. The currently supported languages are English (value "en") and German (value "de").
  • [New in 1.24.0]optimizedWidgetLoading (Boolean) – improves the performance of Scrivito-based apps by retrieving widget data on demand and thereby reducing the bandwidth, memory and CPU footprint of page loading and pre-rendering. Setting this option to true is recommended for all applications, however, see the remark below.
  • [New in 1.24.0]strictSearchOperators (Boolean) – enables strict mode for the Obj.where and ObjSearch.and methods. If set to true, the contains and containsPrefix full-text search operators cannot be used with these query methods.

    Remarks
  • With visitorAuthentication turned on, Scrivito.preload ignores the dump data.
  • With optimizedWidgetLoading set to true, every first widget.get("attributename") fetches the data of the widget instance concerned (its content, and thus the value of attributename) from the backend instead of obtaining it from the preload dump (to which the widget hasn’t been added, in this case). This may cause Content not yet loaded errors with applications that were developed prior to version 1.24.0 of the SDK if widgetlist attributes are accessed directly using Obj#get or Widget#get outside of Scrivito.connect or Scrivito.load. So please make sure that all calls to Obj#get or Widget#get for widgetlist attributes are issued from within Scrivito.connect or Scrivito.load.

Routing

Scrivito uses path-based routing: the “routing path” is stored in the URI path. These URIs look like typical web server URIs.

www.mysite.com/
www.mysite.com/myPermalink
www.mysite.com/someSlug-2cd1ca3e2080c7f0

The optional routingBasePath allows you to “mount” the Scrivito application onto a sub-path. If, for example, routingBasePath is set to /docs/guides, the URIs would look like this:

www.mysite.com/docs/guides/
www.mysite.com/docs/guides/myPermalink
www.mysite.com/docs/guides/someSlug-2cd1ca3e2080c7f0

Multi-site configuration

The combination of the callbacks baseUrlForSite and siteForUrl configures a site mapping for multi-site support. By configuring a site mapping, you inform Scrivito that your CMS may contain multiple sites. The site mapping tells Scrivito the URLs that your sites should use. Scrivito uses this mapping to recognize which site the browser is currently displaying, for example. It is also used for cross-site-navigation, e.g. to generate the appropriate URL when a link on the current site points to a page on another site.

function baseUrlForSite(siteId) {
  // ...
}

function siteForUrl(url) {
  // ...
}

Scrivito.configure({
  baseUrlForSite: baseUrlForSite,
  siteForUrl: siteForUrl,
});

The baseUrlForSite function receives a site ID and should return the base URL of this site if it exists.

The “base URL” is the URL where a specific Scrivito website starts. Depending on your deployment structure, it may or may not include a path. Examples:

// When using one domain per site:

baseUrlForSite(englishSiteId); 
// => "https://mysite.co.uk"
baseUrlForSite(germanSiteId);
// => "https://mysite.de"

// When using a single domain for all sites, with a path prefix:

baseUrlForSite(englishSiteId);
// => "https://mysite.net/en"
baseUrlForSite(germanSiteId);
// => "https://mysite.net/de"

The siteForUrl function receives a URL and should return an object containing the site ID under the property siteId and the base URL of the site to which the URL belongs under the property baseUrl:

siteForUrl("https://mysite.net/en/contact");
// => { siteId: englishSiteId, baseUrl: "https://mysite.net/en" }

siteForUrl("https://mysite.net/de/kontakt");
// => { siteId: germanSiteId, baseUrl: "https://mysite.net/de" }

Scrivito always calls your siteForUrl function with an absolute URL, i.e. including host, protocol etc. Similarly, your baseUrlForSite callback is expected to always return an absolute URL as well.

If siteForUrl is invoked with a URL that is not part of your application, your function must return undefined, to indicate to Scrivito, that this is an external URL.

In the example above, the callback returns a valid site ID for "mysite.net/de" and "mysite.net/en", but if invoked with "mysite.net/some_dummy_value" it would probably return undefined to signal to Scrivito that this URL does not denote a valid site. Scrivito treats this as “site not found”, meaning that it is not responsible for rendering this URL, i.e. both Scrivito.currentPage and Scrivito.currentSiteId will return null, and neither Scrivito.CurrentPage nor Scrivito.NotFoundErrorPage will render anything.

Here is a simple example in which Scrivito recognizes only two sites:

function baseUrlForSite(siteId) {
  if (id === ENGLISH_SITE_ID) {
    return "https://mysite.com";
  }

  if (id === FRENCH_SITE_ID) {
    return "https://mysite.fr";
  }
}

function siteForUrl(url) {
  if (url.startsWith("https://www.mysite.com")) {
    return {
      siteId: ENGLISH_SITE_ID,
      baseUrl: "https://mysite.com",
    };
  }

  if (url.startsWith("https://www.mysite.fr")) {
    return {
      siteId: FRENCH_SITE_ID,
      baseUrl: "https://mysite.fr",
    };
  }
}

Scrivito.configure({
  baseUrlForSite: baseUrlForSite,
  siteForUrl: siteForUrl,
});

Please note that providing the mapping is optional. If no mapping is given, Scrivito assumes that your CMS is not multi-site, i.e. that it handles just one site. If the mapping is given, however, both functions must be provided (providing just one function is considered an error).

Note also that an application cannot be configured for multi-site, while also providing origin or routingBasePath because these option combinations are mutually exclusive.

Setting the origin of Scrivito.urlFor() URLs

Here is an example of how to specify the origin to be used for URLs returned by Scrivito.urlFor(target, options).

Scrivito.configure({
  tenant: '0123456789abcdef0123456789abcdef',
  origin: 'https://example.com',
});

In-memory tenant

In order to run your application without any connection to the content of your website, you can enable the in-memory tenant by setting the value of tenant to inMemory (string). This is handy if you are running tests for your code that are reading and writing Scrivito content. In this case you don’t want the tests to affect the content displayed on your actual website. Furthermore, in most cases you don’t want the test code to communicate via the network at all.

The in-memory tenant allows exactly that:

  • You can change Scrivito content without the changes being propagated to your production environment.
  • The changes are stored in memory, so making them doesn’t require a network connection.
  • Once the process died, all changed content disappears.
Scrivito.configure({
  tenant: "inMemory"
});

However, there are some limitations when using the in-memory tenant:

  • An in-memory tenant is empty by default, so each time you start a process using the inMemory tenant, your tests would have to set up content first.
  • The search APIs are not available.
  • Everything related to binaries is not available.
  • Everything related to navigation and routing is not available.

Constraints validation callback

In order to have a third-party library validate an attribute based on constraints, a constraintsValidation callback can be provided. The underlying function receives a constraints object and returns an attribute validation callback. Here’s an example for using Validate.js:

import { validate } from "validate.js";

Scrivito.configure({
  tenant: "123456789123456789",

  constraintsValidation: constraints => {
    return (name, { value }) => {
      return validate(
        { [name]: value },
        { [name]: constraints },
        { format: "flat" }
      );
    };
  }
});