Sets global options for a Scrivito-based web application.
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:
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.
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). This callback is only executed for the site whose siteId is “default” which is the only site in a single-site setup. It is not recommended to use this callback in a multi-site setup.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: falseconstraintsValidation (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. See below for an example.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.priority (String) – the priority of API calls with respect to rate limitation. Must be set to background for traffic caused by automated tasks such as prerendering and other scripts to not be counted against the rate limit to which the live site or the UI are subject. Default: foreground in a browser environment, background otherwise, e.g. with Node.js.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").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.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.contentTagsForEmptyAttributes (Boolean) – if set to false, ContentTag components with an empty attribute value are not rendered on the live site and in “Preview” mode. Default: true. See the remark below for details.apiKey(String) – gives access to restricted content if a valid REST API key has been provided. Only available in Node.js.Remarks
visitorAuthentication turned on, Scrivito.preload ignores the dump data.optimizedWidgetLoading set to true, every first obj.get("myWidgetlist") fetches the widget data of the object instance concerned (its content, and thus the value of myWidgetlist) from the backend instead of obtaining it from the preload dump (to which the widgets haven’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 outside of Scrivito.connect or Scrivito.load. So please make sure that all calls to Obj#get for widgetlist attributes are issued from within Scrivito.connect or Scrivito.load. For Widget#get calls, no precautions need to be taken.contentTagsForEmptyAttributes set to false, ContentTags with an empty attribute value are still rendered in “Edit” mode. In “Changes” mode, they are rendered (for comparison reasons) if an empty value was changed.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
The combination of the baseUrlForSite and siteForUrl callbacks configures a site mapping for multi-site support. By configuring a site mapping, you enable Scrivito to differentiate between multiple sites by their individual site IDs and URLs. Scrivito uses this mapping to determine the site the browser is currently displaying, for example. It is also used for cross-site-navigation, i.e. to generate the appropriate URL when a link on the current site points to a page on a different site.
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:
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:
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:
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 present, however, both functions must be provided (defining just one function is considered an error).
Also, an application cannot be configured for multi-site with origin or routingBasePath being specified as well because these option combinations are mutually exclusive.
Here is an example of how to specify the origin to be used for URLs returned by Scrivito.urlFor(target, options).
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:
However, there are some limitations when using the in-memory tenant:
inMemory tenant, your tests would have to set up content first.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: