Custom code

With custom code you can extend your configurators capabilities in many ways. It allows you to write TypeScript which then runs in your configurator.

The following are just a few examples of the countless possibilities which open up with this feature:

• Extend functionalities for existing components and controls (see custom code utils)
• Extend functionalities for the viewer control (see 3d viewer)
• Add new controls like a date time picker etc.
• Fetch data from external services like real-time prices calculated on your servers or real-time inventory from your CMS etc.
• Send live analytics to external services like Google Tag Manager etc.

How to get started

1. Prepare your configurator

• Create a new configurator if you don't already have one.
• See if your configurator has 2 components named CustomJS and CustomJSCmps.
  If yes: You can skip the following steps and go to the next section.
• Create a resource component of type JavaScript named CustomJS and upload some dummy file to a resource named cfgr.
• Create a value component named CustomJSCmps and paste the following into the rule of the component:

  // In this component, you have to tell the server which components you're
  // accessing (reading or writing to) in your custom code.
  //
  // By default the server only sends the result value of the listed components to
  // the client. If more data like the list of all records etc. is needed, a "+"
  // needs to be prepended to the name.
  
  // Examples for how to use this. Replace with real cmp names...
  [
    #DefaultView.Name,
  
    // Retrieve all records of a component
    "+" + #MyRecords.Name
  ]
  
  // Why do we need this?
  //
  // In published configurators, the server optimizes the used network bandwidth
  // and only sends information about components to the client when actually
  // needed.
  //
  // Since the server has no way of knowing which components are used in custom JS,
  // we need to give him this information manually here so that he can optimize
  // properly.
  

  See What is the CustomJSCmps component down below for some more details.

2. Setup a TypeScript project

Theoretically you can upload any .js file to your configurator.

However, we provide a starter project which comes with our recommended configuration (build tools, config, pre-installed packages etc.) and gives you everything you need to get started quickly.

• Open a terminal (e.g. command line in windows) in the folder where you want to create your project
• Run npm create @combeenation/custom-code@latest
• Follow the instructions of the script to create a starter project using TypeScript

How to use it

Where to start writing code

The main starting point is usually the callback to CfgrUtils.onCfgrReady within src/index.ts in which you have the guarantee that you can safely access all components & controls.

You can either write all your TypeScript logic within this function or spread it over as many functions/modules/files as you like.

How to run & debug during development

There are 2 ways to run & debug your application during development:

• Debugging in Chrome dev tools:
  • Run npm run dev which will start a local dev server
  • Open the preview of your configurator draft
  • Click the "TS icon" in the upper right to connect to the local instance
    • As alternative you can also add the URI parameter &localcts=true manually
  • Debug in browser dev tools (F12)
• Debugging in VS Code:
  • Open the view "Run and debug" in VSCode & select "Start dev" in dropdown at the top (this is only needed once).
  • Press F5 to start debugging. This will automatically open a new Chrome window and run npm run dev in the background.
  • Open the preview of your configurator draft
  • Click the "TS icon" in the upper right to connect to the local instance
    • As alternative you can also add the URI parameter &localcts=true manually
  • Debug directly in VSCode

How to upload custom code to the configurator

Uploading your custom cod to the configurator is always required when you want to share your configurator with someone else or want to publish it.

• Run npm run build in your custom code project on your computer
• Upload the built file under dist/cfgr.js to your CustomJS component by clicking on the "edit" icon next to its cfgr resource

Retrieve configurator definitions file

• Open your configurator draft
• Expand the menu of the Components-list on the left
• Select Download custom code definitions
• Save/Replace the file in your code project

How to access components & controls

The custom code utils package is mandatory to interact between your custom code and the configurator.

It allows you to read values from components, write new input values to them and interact with the controls in your configurator and many other features.
To work with a component ensure that your "configurator definitions file" is up to date (see previous step).
This file basically represents your components list.
If you want to access a component simply import the variable which has the identical name as your component.
This variable then provides all the available functions and properties you need.

const myValue = await MyCmp.getValue();
MyCmp.setInput('myNewString');

See the utils API documentation for more details on how to use them.

The custom code utils come pre-installed with our TypeScript start project.

You can also install them manually using npm install @combeenation/custom-code-utils.

How to interact with the 3d viewer

Combeenation has built its own 3d viewer, which is used in the 3d viewer control.

If the functionality of this 3d viewer control and its SigSlos is not sufficient, it can be extended in custom code using the API of the 3d viewer package itself.

See 3d viewer control with custom JS for more details.

What is the CustomJSCmps component

In this component, you have to tell the server which components you're accessing (reading or writing to) in your custom code.

You'll get a warning in the configurator preview if you access components which are not listed in it. Always ensure that you list all required components as published configurators will fail silently if components are missing.

See this section above for an example of how the content of this component has to look like.