Input Control Development Guide - XMPieLab/uStore-NG GitHub Wiki

Prerequisite: Use node js version 16 and above.

To develop a custom input control (also known as DUC) follow these steps:

  1. Create a legacy custom DUC in your uStore server.

  2. Download the ng_duc_project_sample.zip.

  3. Extract the downloaded ZIP file into a new directory.

  4. In the new directory, run npm install

  5. In the new directory, rename Sample.duc.js (the name should start with a capital letter and end with the suffix .duc.js)

  6. Inside the file, do the following:

    • Change the class name (for examle NewNameOfDuc)
    • Locate these lines
    if (typeof window !== 'undefined') {
window.uStoreDucs = window.uStoreDucs || []
window.uStoreDucs.push({ name: 'Sample', component: Sample, displayName: 'Sample duc name' , configSample: {}})
}

export default Sample
    • Change name: 'Sample' to name: 'NewNameOfDuc' (the name should have no spaces)
    • Change component: Sample to component: NewClassName
    • Change displayName: 'Sample duc name' to displayName: 'New DUC display name'. The display name will be displayed in property edit beside the default DUCs.
    • Change export default Sample to export default NewNameOfDuc
    • Change configSample: {} to the JSON configuration you need for your custom DUC.
    • Change the thumbnail.png file to a new image with the sanme name that will be used as a thumbnail for the DUC in the uStore admin.

  7. In the terminal, run npm run build. When the script is done, you will find a ZIP file in the dist directory. The file should be named NewClassName.zip.

  8. Register the new DUC in uStore admin (Presets > Input Control Management).

  9. Create a new property in your product and select the new custom DUC.

  10. In the theme directory, start development by running npm start -- ducbuild=/path/to/duc/directory

  11. You can now modify the files inside the DUC's directory. Note that when you update, the DUC's files will be compiled but the application will not be reloaded in the browser; you will need to do it manually.

DUC development guidelines

  • A DUC should be treated as an independent component and should not expect libraries to be present. Install the packages you need to use.
  • DUC parameters provide only the data that is related to the DUC and not a global model from uStore.
  • For changes to take effect, you need to call this.props.onChange(newValue) or this.props.onBlur(this.props.id, newValue) in case of focus lost.
  • The DUC should take into account the readonly, required, disabled properties to behave correctly and be influenced by the form.
  • The DUC accepts the uiSchema and jsonschema parameters, that describe the configuration and validation of the DUC by the form. See json-schema.org to understand the format.