Skip to main content

Frontend SDK

What is it?​

This Frontend SDK is used for building custom components and workflow steps for use in Dais UI Builder. If you are not familiar with Dais UI Builder, it is recommended that you familiarize yourself with the product first. Dais UI Builder provides hooks to allow custom components or workflow steps to be written for project-specific needs if the stock functionality does not suffice. This repo acts as a starting point to develop, publish and use your components and workflow steps within Dais UI Builder.

To make your life easier we've automated some parts of it.

Prerequisites​

How do you use it?​

There are four main cases you may want to achieve. Please find your case below and follow the instructions.

Main Topics​

Additional Topics​

Creating a Custom Component/Workflow Step from Scratch​

So, you want to create completely fresh component / workflow step to use in Dais UI Builder? This option also works in cases you'd like to use a 3rd party library as the basis of the component / workflow step, i.e., HighCharts Bar Chart.

Type: npm run wizard:init You will be asked to answer couple questions and then you're ready to roll. Here's the list of questions:

Setup information:

  1. Artifactory email.
  2. Artifactory API key.
  3. Dais project URL you may answer with full url or just domain, it's better to provide full name as it will extract project ID so you don't have to answer Q5).
  4. Dais Developer Key.
  5. Project ID (depends on the answer on Q3).
  6. Package name.
  7. Package version.

Component information:

  1. Do you want to load sample components? if you want to see some reference components select Y.
  2. Component name.
  3. Is this existing component answer N here.
  4. Do you want to add another component if you have more components answer Y.

Workflow information:

  1. Do you want to load sample workflows? if you want to see some reference workflow select Y.
  2. Workflow name.

Now in src/components/chosen_name you'll have three files:

  1. Connector - this is used to actually connect component to Dais, it consists of 3 sections (each section is documented inside and contains links with API docs):
    • Definition - contains properties how your component is seen in Dais
    • Schema - properties that associate to props that component receive
    • Register - it joins definition and schema into one
  2. Index - React component
  3. name.stories - Storybook stories of your component

And in src/workflows/chosen_name you'll have one file:

  1. Index.ts - contains connector and workflow function. What's connector? See: 8 lines above.

To preview component, see: Preview component with storybook

Best "preview" option for workflow steps is to write test for it: Testing code

To publish connector / workflow step to dais see: Publishing component to Dais

Using an Existing Component​

So, you already have some component (not built in Dais) that you'd like to use it in Dais UI Builder?

Type: npm run wizard:init Answer couple questions and you're ready to roll. Here's the list of questions:

Setup information:

  1. Artifactory email
  2. Artifactory API key
  3. Dais project URL you may answer with full url or just domain, it's better to provide full name as it will extract project ID so you don't have to answer Q5)
  4. Dais Developer Key
  5. Project ID (depends on the answer on Q3)
  6. Package name
  7. Package version

Component information:

  1. Component name.
  2. Is this existing component answer Y here.
  3. Where can I find your component artifact provide relative path to where you're putting your component artifact..
  4. Do you want to add another component.

Now in src/components/chosen_name you'll have one file:

  1. Connector - this is used to actually connect component to Dais, it consists of 3 sections (each section is documented inside and contains links with API docs)
    • Definition - contains properties how your component is seen in Dais.
    • Schema - properties that associate to props that component receive.
    • Register - it joins definition and schema into one.

And you should copy artifact to the position you've provided in Component information point 3.

To preview component, see: Preview component with storybook

To publish it to dais see: Publishing component to Dais

Working on a Component Created by Someone Else​

(Setting up an existing repo again)

So, your taking over after someone? Or you're continuing work on a new machine? Or maybe some of your credentials have changed?

If your credentials have changed start with npm run wizard:clean - this will remove old credentials.

Type: npm run wizard:init

Answer a couple of questions and you're ready to roll. The wizard will prepare the environment, so you'll be able to work with this project. Here's the list of questions:

Setup information:

  1. Artifactory email.
  2. Artifactory API key.
  3. Dais project URL you may answer with full url or just domain, it's better to provide full name as it will extract project ID so you don't have to answer Q5).
  4. Dais Developer Key.
  5. Project ID (depends on the answer on Q3).

Publishing your Component to Dais​

So, you've finished your work on the component and it's ready to go. Next step is to see it working in Dais UI Builder. To do this,

Type npm run publish

This will build your component (create publishable artifact) and then it will publish your component. In the console output you'll get Object looking similar to this (filled with your specific information):

{
    "name": "component-template-kw",
    "type": "modular",
    "common": false,
    "version": "2.0.0"
}

You will also receive url to which you should go to paste it, i.e.: https://creator.thesimulationgroup.com/app/xxhx0oy3iry7/admin/projectsetups\ At this page you should localize 'packages' key and put this code inside the array. Hit save and look for your component in your project.

Testing​

  • Tests are written in jest + react-testing-library.
  • Default test provided for your component checks if component returns expected text.
  • Default test provided for your workflow checks if handler simply returns a passed object.
  • To start tests, first look into your component folder, find the *.test.tsx file and run npm run test it will start test suite in watch mode, so any change you make will be automatically tested.

Don't know Jest? Find out more here: jest website
Don't know React testing library? Find out more here: react testing library website

Preview with Storybook​

Default test provided for your component is simply rendering the component without any properties.

To spin up storybook, look into your component folder, find the *.stories.tsx and run npm run preview it will start storybook and display stories you've just found.

Don't know storybook? Find out more here: storybook website