DsClient - Documentation

new DsClient(service_urlnon-null, in_settingsopt, non-null)

DsClient provides a layer of abstraction between GUI code and session-/protocol-handling.

The configurator system is stateful. Session state is shared between server and client, this is a source of complexity and can hopefully be removed at some point in the future. DsClient provides synchronization of session state between server and client by centralizing management of the shared state inside this class.

Member functions are stateful if the member function name begins with "session". Other member functions are state- and session-less and can be called at any time, in any order.

Most session dependent functions also require a loaded configuration. Preconditions should be documented for each member function in this class.

The configurator system can be simplified as the following three phases: A. The user finds the configurator application on the web or in the showroom. B. The user choose and change the product components (called items) until the user is satisfied or leaved the application. C. The user saves the configuration for a later time or choose to place an order or request a sales contact for the built configuration.

Technical usage example 1, Starting a new configuration session and interacting with the user. (Step-by-step example of phase B):

Construct an instance of spv.ds.Client
Call sessionInit
Call getIntroPage to retrieve the available start configurations
Generate images for the start configurations using getConfigImage
Display the available start configuration images to the user using the appropriate techniques for the GUI implementation.
The user chooses a start configuration
Send that start configuration to sessionLoadConfig
On success, call sessionGetRootMenuItems and sessionGetImage
Populate the GUI root menu with menu items and wait for the image response
On image success, load and display the configuration image
The user makes a choice about which menu to open
Call sessionToggleItem for the user chosen MenuItem (both menus and product components are MenuItems)
On success, call sessionGetStateUpdate to populate the currently open menu with menu items.
The user clicks an item in the currently open menu, send that MenuItem to sessionToggleItem and handle response.
On success, update the currently open menu with new MenuItems (most menu items will usually be unchanged, but some may change state and some may disappear while others may be added). Call sessionGetImage to get the new configuration image and wait for response.
On image success, load and display the configuration image
The user clicks a new item and the sessionToggleItem cycle continues until the user closes the application or decides to place an order for the built configuration. (this step is customized action for each configurator application, eg. cars and bathroom products require different types of shopping cart solutions)

Source:

ds/DsClient.js, line 106

Parameters:

Name	Type	Attributes	Description
`service_url`	`string`
`in_settings`	`spv.ds.DsClientSettings`	<optional>

Members

(protected) _protocol :spv.ds.impl.IDsProtocol

Source:

ds/DsClient.js, line 122

Type:

spv.ds.impl.IDsProtocol

(protected) _session_state :spv.ds.impl.SessionState

Source:

ds/DsClient.js, line 149

Type:

spv.ds.impl.SessionState

(inner, non-null) settings :spv.ds.DsClientSettings

Source:

ds/DsClient.js, line 114

Type:

spv.ds.DsClientSettings

Methods

(protected) assertInitializedSession()

Throw exception if session is not initialized.

Source:

ds/DsClient.js, line 2810

(protected) assertInitializedSessionWithConfig()

Throw exception if session is not initialized or is missing a configuration.

Source:

ds/DsClient.js, line 2826

constructDefaultImageParams() → {spv.ds.ImageParams}

Create a ImageParams instance with default values, however, defaults are likely not good enough for most contexts.

Preconditions: None.

Source:

ds/DsClient.js, line 222

Returns:

Type:: spv.ds.ImageParams

(protected) constructFailureWrapperForQueue(wrap_me) → {function}

Constructs the standard failure callback wrapper for queued session requests

Source:

ds/DsClient.js, line 2726

Parameters:

Name	Type	Description
`wrap_me`	`function`	The outer failure handler to wrap

Returns:

Type:: function

(protected) errorHandler(on_failure) → {function}

Source:

ds/DsClient.js, line 2850

Parameters:

Name	Type	Description
`on_failure`	`function`

Returns:

Type:: function

generatePublicConfig(on_success, on_failure)

Save the current configuration for the logged in user as a public config. The generated name is returned as a string to the on_success function.

Preconditions: Initialized session, loaded configuration, logged in user.

Source:

ds/DsClient.js, line 1478

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

getConfigImage(conf, img_params, on_success, on_failure)

Requests an image for a serialized configuration.

Preconditions: None.

Source:

ds/DsClient.js, line 241

Parameters:

Name	Type	Description
`conf`	`spv.ds.Config`
`img_params`	`spv.ds.ImageParams`
`on_success`	`function`
`on_failure`	`function`

getFreshConfigs(limit, scale_width, scale_height, on_success, on_failure)

Requests the most recently built car configurations.

Source:

ds/DsClient.js, line 913

Parameters:

Name	Type	Description
`limit`	`number`	Max number of configs in result
`scale_width`	`number`
`scale_height`	`number`
`on_success`	`function`
`on_failure`	`function`

getIntroPage(on_success, on_failure)

Requests the "Intro page" data including available start-configurations, typically one config for each car model.

Preconditions: None.

Source:

ds/DsClient.js, line 271

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

getItemResources(item_ids, category, model, language, on_success, on_failure)

Source:

ds/DsClient.js, line 317

Parameters:

Name	Type	Description
`item_ids`	`Array.<string>`
`category`	`string`
`model`	`string`
`language`	`string`
`on_success`	`function`
`on_failure`	`function`

getLanguage() → {string}

Source:

ds/DsClient.js, line 1983

Returns:

Type:: string

getReadMore(item_id, model, category, on_success, on_failure)

Source:

ds/DsClient.js, line 290

Parameters:

Name	Type	Description
`item_id`	`string`
`model`	`string`
`category`	`string`
`on_success`	`function`
`on_failure`	`function`

getSessionId() → {string}

Get the session id or throw if null

Source:

ds/DsClient.js, line 201

Returns:

Type:: string

getUserConfigList(username, on_success, on_failure)

Gets all configurations stored in the database by the given username. This is a heavy operation and is included here for utility purposes.

Source:

ds/DsClient.js, line 347

Parameters:

Name	Type	Description
`username`	`string`
`on_success`	`function`
`on_failure`	`function`

publicConfigV2Load(public_config_id, on_success, on_failure, on_coc)

Source:

ds/DsClient.js, line 2451

Parameters:

Name	Type	Description
`public_config_id`	`string`
`on_success`	`function`
`on_failure`	`function`
`on_coc`	`function`	(optional)

publicConfigV2Save(description, config_storage_aux, on_success, on_failure)

Source:

ds/DsClient.js, line 2518

Parameters:

Name	Type	Description
`description`	`string`
`config_storage_aux`	`Object.<string, string>`
`on_success`	`function`
`on_failure`	`function`

resetPassword(token, new_password, on_success, on_failure)

Resets user password.

Token is retrieved via email, sent by sessionSendResetPasswordMail.

Source:

ds/DsClient.js, line 1805

Parameters:

Name	Type	Description
`token`	`string`
`new_password`	`string`
`on_success`	`function`
`on_failure`	`function`

sessionAddGuiGroupSubscriptions(group_ids, on_success, on_failure)

Source:

ds/DsClient.js, line 369

Parameters:

Name	Type	Description
`group_ids`	`Array.<string>`
`on_success`	`function`
`on_failure`	`function`

sessionApplySuggestion(suggestion, on_success, on_failure)

Apply a configuration change suggestion on the current configuration.

Preconditions: Initialized session, loaded configuration, caller code has a valid instance of spv.ds.Suggestion retrieved by calling sessionToggleItem, no requests that modify the session configuration has been dispatched between suggestion construction and the call to this function.

Source:

ds/DsClient.js, line 451

Parameters:

Name	Type	Description
`suggestion`	`spv.ds.Suggestion`	The suggestion to be applied to the current configuration.
`on_success`	`function`	Called when the suggestion has been successfully applied.
`on_failure`	`function`	Called on any kind of failure.

(protected) sessionAutomaticHeartbeat(on_heartbeat, on_failure)

Source:

ds/DsClient.js, line 2567

Parameters:

Name	Type	Description
`on_heartbeat`	`function`
`on_failure`	`function`

sessionClearGuiGroupSubscriptions(on_success, on_failure)

Source:

ds/DsClient.js, line 405

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

sessionCreateUser(user_name, password, on_success, on_failure)

Create a new user in the user database.

May not be required to create a user, depending on backend settings.

Source:

ds/DsClient.js, line 1650

Parameters:

Name	Type	Description
`user_name`	`string`
`password`	`string`
`on_success`	`function`
`on_failure`	`function`

(protected) sessionDequeueNextRequest()

Session requests that require synchronization must use this function This function is not allowed to throw exceptions.

Source:

ds/DsClient.js, line 2753

(protected) sessionEnqueueRequest(request)

Session requests that require synchronization must use this function

Source:

ds/DsClient.js, line 2774

Parameters:

Name	Type	Description
`request`	`function`

sessionGeneratePdf(on_success, on_failure)

Create a pdf using current session state and returns the pdf url through a callback if a pdf was generated successfully.

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 506

Parameters:

Name	Type	Description
`on_success`	`function`	Callback taking the generated pdf url
`on_failure`	`function`

(protected) sessionGetAuxiliaryData() → {Object.<string, Object>}

Returns the auxiliary data arriving with the latest bop.

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 1051

Returns:

Type:: Object.<string, Object>

sessionGetConfig(encoding, on_success, on_failure)

Requests the current session config

Available encodings are: "" : internal encoding, only for debug

Preconditions: Initialized session, loaded config.

Source:

ds/DsClient.js, line 572

Parameters:

Name	Type	Description
`encoding`	`string`
`on_success`	`function`
`on_failure`	`function`

sessionGetConfigNames(on_success, on_failure)

Get the saved configs for the logged in user

Preconditions: Initialized session, logged in user.

Source:

ds/DsClient.js, line 625

Parameters:

Name	Type	Description
`on_success`	`function`	A callback taking an array of names of saved configurations. The configuration names can be used to remove or load configs for the logged in user by sessionRemoveConfigByName and sessionLoadConfigByName.
`on_failure`	`function`

sessionGetFacebookShareData(on_success, on_failure)

Requests the text, images etc used for facebook sharing.

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 887

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

sessionGetFreshConfigs(limit, scale_width, scale_height, on_success, on_failure)

Requests the most recently built car configurations.

Deprecated:

Source:

ds/DsClient.js, line 947

Parameters:

Name	Type	Description
`limit`	`number`	Max number of configs in result
`scale_width`	`number`
`scale_height`	`number`
`on_success`	`function`
`on_failure`	`function`

sessionGetImage(img_params, on_success, on_failure)

Builds an image for the current configuration state in this session.

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 981

Parameters:

Name	Type	Description
`img_params`	`spv.ds.ImageParams`
`on_success`	`function`
`on_failure`	`function`

sessionGetImageSerieInfos() → {Array.<spv.ds.ImageSerieInfo>}

Get image serie info for the current configuration

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 790

Returns:

Type:: Array.<spv.ds.ImageSerieInfo>

sessionGetInitialConsequenceOfChange(on_success, on_failure)

Source:

ds/DsClient.js, line 2084

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

sessionGetIntroDisclaimer() → {spv.ds.Disclaimer}

Gets the disclaimer to be displayed when the configurator is started.

Source:

ds/DsClient.js, line 736

Returns:

Type:: spv.ds.Disclaimer

sessionGetItemInfo(item_ids, on_success, on_failure)

Get complete item info for items by item id

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 809

Parameters:

Name	Type	Description
`item_ids`	`Array.<string>`
`on_success`	`function`
`on_failure`	`function`

sessionGetLongText(item_id) → {string}

Get 'long_text' text for item_id or empty string on failure

Texts are configuration dependent. In practice updating texts is only needed after loading a configuration, not when simply toggling an item in the configuration.

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 720

Parameters:

Name	Type	Description
`item_id`	`string`

Returns:

Type:: string

sessionGetMediaKit(serie_index, frame_index, file_type, separate_background, separate_shadow, all_frames, use_hd, image_width, image_height, on_success, on_failure)

Gets an URL to a zipfile containing the images.

Source:

ds/DsClient.js, line 844

Parameters:

Name	Type	Description
`serie_index`	`number`
`frame_index`	`number`
`file_type`	`string`
`separate_background`	`boolean`
`separate_shadow`	`boolean`
`all_frames`	`boolean`
`use_hd`	`boolean`
`image_width`	`number`
`image_height`	`number`
`on_success`	`function`
`on_failure`	`function`

sessionGetMediumText(item_id) → {string}

Get 'medium_text' text for item_id or empty string on failure

Texts are configuration dependent. In practice updating texts is only needed after loading a configuration, not when simply toggling an item in the configuration.

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 697

Parameters:

Name	Type	Description
`item_id`	`string`

Returns:

Type:: string

sessionGetModelDisclaimer(model_idopt) → {spv.ds.Disclaimer}

Get the disclaimer specific for a model.

If no model id is passed, it'll default to the active configuration's model.

Source:

ds/DsClient.js, line 755

Parameters:

Name	Type	Attributes	Description
`model_id`	`string`	<optional>

Returns:

Type:: spv.ds.Disclaimer

sessionGetPresentationStructure(filter_name, query, on_success, on_failure)

Source:

ds/DsClient.js, line 1136

Parameters:

Name	Type	Description
`filter_name`	`string`
`query`	`spv.ds.PresentationStructureQuery`
`on_success`	`function`
`on_failure`	`function`

sessionGetRootMenuItems() → {Array.<spv.ds.MenuItem>}

Get the root menu items for the current configuration

Preconditions: Initialized session, loaded config.

Source:

ds/DsClient.js, line 550

Returns:

Type:: Array.<spv.ds.MenuItem>

sessionGetShortText(item_id) → {string}

Get 'short_text' text for item_id or empty string on failure

Texts are configuration dependent. In practice updating texts is only needed after loading a configuration, not when simply toggling an item in the configuration.

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 674

Parameters:

Name	Type	Description
`item_id`	`string`

Returns:

Type:: string

sessionGetStateUpdate() → {spv.ds.SessionStateUpdate}

Get the last state update. Call this function on successful load of configs or on successful sessionToggleItem.

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 1069

Returns:

Type:: spv.ds.SessionStateUpdate

sessionGetSummary(on_success, on_failure)

Get the summary for the current session and configuration

Preconditions: Initialized session, loaded configuration.

Source:

ds/DsClient.js, line 1029

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

sessionGetUrlSettings() → {spv.ds.UrlSettings}

Get base urls needed for most HTTP GET paths to images

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 773

Returns:

Type:: spv.ds.UrlSettings

sessionGetUserConfigImage(config_name, img_params, on_success, on_failure)

Requests an image for a saved configuration

Preconditions: Initialized session, logged in user.

Source:

ds/DsClient.js, line 1089

Parameters:

Name	Type	Description
`config_name`	`string`
`img_params`	`spv.ds.ImageParams`
`on_success`	`function`
`on_failure`	`function`

sessionHasLoggedInUser(on_success, on_failure)

Check with backend if the session has a logged in user.

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 1702

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

sessionInit(menu_query, readmore_mode, on_success, on_failure)

Initialize session. This must be called before calling any other member function with "session". For most other session calls a configuration needs to be loaded as well.

This is not done in the constructor in order to allow state-/session-less calls without initializing a session.

Preconditions: None.

Source:

ds/DsClient.js, line 1186

Parameters:

Name	Type	Description
`menu_query`	`string`
`readmore_mode`	`spv.ds.ipprot_nova.input.BopReadMoreMode`
`on_success`	`function`
`on_failure`	`function`

sessionLoadConfig(config, on_success, on_failure)

Loads a configuration into the current session and replaces to current configuration state.

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 1310

Parameters:

Name	Type	Description
`config`	`spv.ds.Config`
`on_success`	`function`
`on_failure`	`function`

sessionLoadConfigByName(config_name, on_success, on_failure)

Loads a configuration into the current session and replaces to current configuration state. The config is referenced by it's name retrieved from sessionGetConfigNames.

Preconditions: Initialized session, logged in user.

Source:

ds/DsClient.js, line 1367

Parameters:

Name	Type	Description
`config_name`	`string`
`on_success`	`function`
`on_failure`	`function`

sessionLoadPublicConfig(public_config_id, on_success, on_failure)

Loads a configuration from the "public" database into the current session replacing the current configuration state.

"Public Configs" are anonymous configurations saved without any user information that can be loaded by a unique key.

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 1425

Parameters:

Name	Type	Description
`public_config_id`	`string`
`on_success`	`function`
`on_failure`	`function`

sessionLogin(user_name, password_or_success, success_or_failure, failureopt)

User login Password may be required depending on backend settings.

May create the user if it doesn't exist, depending on backend settings.

success and failure callbacks are always at the end.

sessionLogin( session_id, name, password, success, failure ); sessionLogin( session_id, name, success, failure );

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 1531

Parameters:

Name	Type	Attributes
`user_name`	`string`
`password_or_success`	`string` \| `function`
`success_or_failure`	`function` \| `function`
`failure`	`function`	<optional>

sessionLogout(on_success, on_failure)

Logout the user from the session.

Source:

ds/DsClient.js, line 1603

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

sessionRemoveConfigByName(config_name, on_success, on_failure)

Remove a saved configuration for the logged in user

Preconditions: Initialized session, logged in user.

Source:

ds/DsClient.js, line 1831

Parameters:

Name	Type	Description
`config_name`	`string`	Name retrieved by sessionGetConfigNames
`on_success`	`function`
`on_failure`	`function`

(protected) sessionResetRequestQueue()

Resets session request queue

Source:

ds/DsClient.js, line 2792

sessionResume(session_id, on_success, on_failure)

Initialize with existing session. Used instead of sessionInit.

Preconditions: Client not initialized.

Source:

ds/DsClient.js, line 1246

Parameters:

Name	Type	Description
`session_id`	`string`
`on_success`	`function`
`on_failure`	`function`

sessionSaveConfigByName(config_name, allow_overwrite, on_success, on_failure)

Save the current configuration for the logged in user

Preconditions: Initialized session, loaded configuration, logged in user.

Source:

ds/DsClient.js, line 1880

Parameters:

Name	Type	Description
`config_name`	`string`
`allow_overwrite`	`boolean`
`on_success`	`function`
`on_failure`	`function`

sessionSendHeartBeat(on_success, on_failure)

Call this function to keep the session alive

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 2121

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

sessionSendResetPasswordMail(password_form_url, user_name, language, on_success, on_failure)

Precondition: Initialized session

Source:

ds/DsClient.js, line 1750

Parameters:

Name	Type	Description
`password_form_url`	`string`
`user_name`	`string`
`language`	`string`
`on_success`	`function`
`on_failure`	`function`

sessionSetPriceLocalization(price_localization_id, on_success, on_failure)

Choose which collection of price rules to use for the current session

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 1930

Parameters:

Name	Type	Description
`price_localization_id`	`string`
`on_success`	`function`
`on_failure`	`function`

sessionToggleItem(menu_item, on_success, on_suggestions, on_failure)

Try to change item state for one item in the current configuration. An item has two states, On or Off, eg. an item is part of the current configuration or it is not. The result of this operation can only be determined by the server. Any call to this function may result in suggestions being returned through the callback on_suggestions. If suggestions

Use DsClient.setLanguage in order to specify language. Leaving it undefined will cause the backend to resolve a preferred instead.

Preconditions: Initialized session, loaded configuration, caller code has a valid instance of spv.ds.MenuItem.

Source:

ds/DsClient.js, line 2022

Parameters:

Name	Type	Description
`menu_item`	`spv.ds.MenuItem`	Menu item to toggle on or off. User code should not modify or construct instances of MenuItem, only pass MenuItem instances returned by this class.
`on_success`	`function`	Will be called on toggle success if toggle has no important side effects. Caller code should call sessionGetStateUpdate on this object to get the latest session state update.
`on_suggestions`	`function`	Will be called if item toggle has important side effects or if relevant alternative configuration states has been found.
`on_failure`	`function`	Called on any kind of failure.

(protected) sessionUpdateBop(on_success, on_failure)

Requests a fresh bop and stores the new state in the client.

Source:

ds/DsClient.js, line 2685

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

setLanguage(language, on_success, on_failure)

Source:

ds/DsClient.js, line 1973

Parameters:

Name	Type	Description
`language`	`string`
`on_success`	`function`
`on_failure`	`function`

startAutomaticHeartbeat(interval, on_heartbeat, on_failure)

Starts the automatic heartbeat for the session. Don't forget to call stopAutomaticHeartbeat if you attempt to destroy or replace the DsClient object. If you don't, there'll be an orphaned DsClient object heartbeating forever. (Well, until the browser session ends. )

Source:

ds/DsClient.js, line 2608

Parameters:

Name	Type	Description
`interval`	`number`	How often the heartbeat is triggered, in milliseconds.
`on_heartbeat`	`function`	This callback is called for every heartbeat.
`on_failure`	`function`

stopAutomaticHeartbeat()

Source:

ds/DsClient.js, line 2624

userConfigV2Delete(config_id, on_success, on_failure)

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 2280

Parameters:

Name	Type	Description
`config_id`	`number`
`on_success`	`function`
`on_failure`	`function`

userConfigV2List(on_success, on_failure)

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 2328

Parameters:

Name	Type	Description
`on_success`	`function`
`on_failure`	`function`

userConfigV2Load(config_id, on_success, on_failure, on_coc)

Preconditions: Initialized session.

The callback on_coc is optional. If provided, it will be called independently of on_success and on_failure. I.e. if there is coc and the load was successful, both on_success and on_coc will be called.

Source:

ds/DsClient.js, line 2383

Parameters:

Name	Type	Description
`config_id`	`number`
`on_success`	`function`
`on_failure`	`function`
`on_coc`	`function`	(optional)

userConfigV2Save(config_id, config_description, user_config_aux, config_storage_aux, on_success, on_failure)

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 2167

Parameters:

Name	Type	Description
`config_id`	`number`
`config_description`	`string`
`user_config_aux`	`Object.<string, string>`
`config_storage_aux`	`Object.<string, string>`
`on_success`	`function`
`on_failure`	`function`

userConfigV2SaveAs(config_name, config_description, user_config_aux, config_storage_aux, on_success, on_failure)

Preconditions: Initialized session.

Source:

ds/DsClient.js, line 2225

Parameters:

Name	Type	Description
`config_name`	`string`
`config_description`	`string`
`user_config_aux`	`Object.<string, string>`
`config_storage_aux`	`Object.<string, string>`
`on_success`	`function`
`on_failure`	`function`