configure(options)

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

  • [New in 1.45.0]activateDataIntegration (Boolean) – enables data integration support (placeholders, data widgets, details pages, etc.) if set to true. Default: false.
  • adoptUi (Boolean) – specifies whether editors should automatically use edit.scrivito.com. This option is only needed for 1.26.0 and earlier. Default: false.
  • [New in 1.31.0]apiKey (String | Object) – gives access to restricted content if a valid API key has been provided. Only available in Node.js.
    The option accepts either a Scrivito API key as a String - which can be generated in the Scrivito Dashboard.
    [New in 1.35.0]Or you can provide a personal API key as an object with the properties clientId: String and clientSecret: String. You can generate a personal API key in the Console.
  • [New in 1.38.0]autoConvertAttributes (Boolean) – if set to true, the SDK will migrate attribute values, regardless of the type the attribute had when it was saved. If set to false, most attributes will behave like an empty attribute if the provided type is changed. Default: false. See Automatic Type Conversions for details.
  • 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.
  • 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. See Constraints Validation Callback for an example.
  • [New in 1.28.0]contentTagsForEmptyAttributes (Boolean) – if set to false, Scrivito.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.
  • [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").
  • endpoint (String) – defines the API endpoint the SDK connects to. Default: api.scrivito.com.
  • [New in 1.35.0]extensionsUrl (String) – the entry point for custom editing functionality. Must be relative to the app origin or an absolute URL. Default: /_scrivito_extensions.html.
  • 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.
  • [New in 1.42.0 (BETA)]iamAuthLocation (String) – defines the path to a custom proxy location for IAM authentication requests. Defaults to /auth.
  • [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.
  • origin (String) – the origin of Scrivito.urlFor. This configuration is optional unless prerendering is enabled. The default is the origin of the current window location. See Setting the Origin for more details.
  • [New in 1.19.0]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.
  • routingBasePath (String) – prefix for all path-based routes handled by Scrivito. This configuration is optional. See Routing 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.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.
  • 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 for more details.
  • 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.
    With Scrivito SDK 1.41.0 and later, using this method this is no longer recommend. Instead, use Visitor Authentication with IAM.

Remarks

  • With visitorAuthentication turned on, Scrivito.preload ignores the dump data.
  • With 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.
  • With 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.
Usage details