Configuration variable
Every time one of your customers uses your configurator or you try out a draft of it, a configuration is created. This configuration is used to automatically save the user's progress, it can be copied or edited at a later time, shared on social networks or put in a shopping cart.
You can interact with the currently active configuration via the configuration variable.
Properties
| name | description |
|---|---|
| id | the unique ID of this configuration |
| authToken | the authorization token for this configuration |
| isFinished | will be false for new configurations and true for configurations that have already been finished |
| isViewMode | will be true when the configuration is opened in a read-only mode |
| hasQuote | will be true if a quote is linked with this configuration, otherwise false |
| editUrl | a URL with which this configuration can be edited |
| copyUrl | a URL that will create a copy of this configuration |
| viewUrl | a URL for viewing this configuration in a read-only view mode |
| insightsUrl | a URL to the insights of this configuration |
| insightsOverviewUrl | a URL to the insights overview page of this configurator |
| quoteUrl | a URL to an already created quote of this configuration, otherwise empty |
| quoteOverviewUrl | a URL to the quotes overview page, includes the correct quote hub name if a quote has already been created |
Functions
| name | description |
|---|---|
| getParameter(name) | returns the value of a URL parameter |
| getImage(name) | returns the Image which was uploaded under the given name (or Empty if nothing was uploaded yet) |
| getFile(name) | returns the File which was uploaded under the given name (or Empty if nothing was uploaded yet) |
The Authorization Token (AuthToken)
Every configuration is protected with an authorization token. Only those that can provide this secret text are allowed to edit the configuration.
The AuthToken is part of the EditUrl of a configuration.
If you want to enable your users to continue a configuration at a later time or after they have put it into a shopping cart, we recommend you use the EditUrl of the configuration.
It should be pretty rare that you have to directly work with the AuthToken yourself.
isFinished
Once a configuration has been put into a shopping cart or, more generally speaking, has been completed (or "finished"), you may want it to behave slightly differently when edited again. For example, you may want to change the text of a button from "order now!" to "save changes" when a customer opens a configuration from his shopping cart.
You can use the configuration.isFinished property to this end, as it will return true when the current configuration has already been completed at some point in the past.
isViewMode
Configurations can be opened in a read-only mode that allows users to view the configuration, but not modify it in any way. Component values can be changed in this mode, but the changes will not be saved.
Certain actions like finish, share or uploading files are not allowed in view mode. If attempted, a warning dialog will be displayed that provides the option to create a copy of the configuration instead, which can then be edited.
Configurations on the Insights, Leads or Quotes pages will by default open in view mode.
Within a configurator, you can obtain the URL for viewing a configuration with configuration.viewUrl
You may rely on isViewMode as an indicator to display the configurator in a read-only state, e.g. hiding certain controls or optimizing the UI for viewing instead of editing.
If you would like to provide users with a way to continue editing, you can restart the configuration to create an editable copy of it.
getParameter(name)
When you embed your configurator in your website, you can add URL parameters to the embed URL. These parameters can then be used to alter how the configurator looks or works. For example, you could pass the SKU of a product, the current language of the website or shop-system specific information to your configurator.
In your configurator, you can obtain the value of an URL parameter with the getParameter function. This function will either return a text value or empty if the parameter has not been used:
// pass language by parameter, use "en" when parameter is not used
configuration.getParameter("language") or "en"
// pass ID of a shopping cart by parameter
// be sure to provide a fallback value if the parameter is not used (e.g. "")
// ToNumber() might also return Empty if the parameter is not a number
(configuration.getParameter("cartId") or "").toNumber() or 1