Skip to main content
Skip table of contents

Create a User Component (UC)

Overview

The User Component (UC) is an essential and valuable component for developing your robot module by Dr.Dart-IDE.

This guide shows you how to create your User Component (UC) besides the existing components provided by default in Dart-IDE.

This article assumes you're already familiar with Dart-IDE. If you aren't, we suggest you retake a look at Dr.Dart-IDE.

Create a new User Component Project

Create a new project for building a User Component in Dart-IDE.

In the main menu, select File ‣ New Project.

  • Step 3: In the dialog that appears, select the User Component option.

  • Step 4: Select the Blank item and click Next button.

  • Step 5: In the dialog that appears, fill up all necessary information, then click the Finish button.

Title

Description

1

Name

The name of the new project.

2

Package Name

The package name of the new project.

3

Save Location

The folder where you save the new project on your local PC.

4

User Component Version

The version that you have made this User Component.

5

DART SDK Version

The Dr.Dart-SDK version of the new project.
If you want to change the SDK version while coding, you must change the information on the manifest.js file. For more information, please refer to Dart-SDK | How-to-change-the-Dart-SDK-version?

6

Icon

The icon to represent your User Component when you upload it to Dart-Store.

  • Step 6: Once the new project is created successfully, you can check its structure in the Explorer panel.

  • Step 7: Open the index.tsx file included in the assets folder of src folder to design your UC.

Understanding the UC project structure

The chart below describes the project source structure of a UC project.

The main parts of a UC project are:

  • lib: Library folder

  • src: Package source folder

  • src/assets: Package resources folder with Images, Styles, and Language resources

  • index.tsx: UC implementation file

  • index.d.ts: UC API definition file

  • manifest.json: Package information definition file

Prepare the API definition file

You can declare the necessary APIs used for your project in the index.d.tsfile.

This file should be located under the src package.

Below is an example of an index.d.ts file.

Click here to expand...
CODE
import { BusinessUiComponentProps } from "dart-api";

export interface ServoSwitchAPI {
    /**
     *
     * Get the entered name.
     *
     * @return Return a name which has been entered in the input field.
     * @type in
     */
    getEnteredName(): string;

    /**
     * Set a callback to get a name when it has been changed.
     *
     * @param callback A callback to get a name
     * @type out
     */
    setOnNameChanged(callback: (name: string) => void): void;
}

export interface ServoSwitchProps extends BusinessUiComponentProps <ServoSwitchAPI> {
    /**
     * Props to set a default name on the Name field.
     * @type in
     */
    defaultName?: string;
}

declare const ServoSwitch: ((props: ServoSwitchProps) => JSX.Element);
export default ServoSwitch

This index.d.ts file is created automatically after successfully creating the Business Component project.

Prepare the UC implementation file

You can implement the logic for your UC in the index.tsx file. This is the most important file you need to prepare for your Business Component project.

This file is also located under the src package.

Below is an example of an index.tsx file.

Click here to expand...
CODE
import { ServoSwitchAPI, ServoSwitchProps } from "./index.d";
...

export default class ServoSwitch extends BusinessUiComponent <ServoSwitchProps, ServoSwitchAPI> implements ServoSwitchAPI {
    ...

    constructor(props: ServoSwitchProps) {
        super(props);
        ...

        // UC 개발자가 사전의 정의한 인터페이스 (ServoSwitchProps) 에 맞춰 props 객체를 통해서 Client로 부터 데이터를 넘겨 받을 수 있다.
        logger.log(`Client set default name to ${props.defaultName} through props.`)
    }

    getEnteredName(): string {
        return (this.refInputField.current) ? this.refInputField.current.value : "";
    }

    setOnNameChanged = (callback: (name: string) => void) => {
        this.callbackOnNameField = callback;
        return true;
    };

    ...
    render() {
        return (
            <ThemeProvider theme={this.systemTheme}>
                <Translation>
                    {
                        t =>
                            <div>
                               ...
                            </div>
                    }
                </Translation>
            </ThemeProvider>
        );
    }                
  }

This index.tsx file is created automatically after successfully creating the Business Component project.

Use Resource Files

You can use the necessary Images, Themes/Styles, and Language Resources for your Business Component project.

  • Image Resources

Click here to expand...

Type

Good

Bad (Not support)

img

import MyIcon from “./assets/images/icon.png";

<img src={MyIcon} />

<img src=”./assets/images/icon.png” />

IconButton (MUI)

import MyIcon from “./assets/images/icon.png";

<IconButton>
<img src={MyIcon} />
</IconButton>

<IconButton>
<img src=”./assets/images/icon.png” />
</IconButton>

(s)css

// styles.scss

.my-icon {
background: url("../images/pressure.png") no-repeat center;
}

  • System Themes, System & User Style Resources

Click here to expand...
  1. System theme
    Example of using system theme:

    CODE
    // index.tsx
    
    import { ThemeProvider } from "@mui/material/styles";
    ...
    class MainScreen extends ModuleScreen {
        ...
        render(){
            return(
                <ThemeProvider theme={this.systemTheme}>
                    ....
                </ThemeProvider>
            )
        }
    }

    In the above sample, when rendering ModuleScreen, system theme object information is passed to ModuleScreen through props.

  2. System styles
    Example of using system styles:

    CODE
    // index.tsx
    
    import { ThemeProvider } from "@mui/material/styles";
    ...
    class MainScreen extends ModuleScreen {
        ...
        render(){
            return(
                <ThemeProvider theme={this.systemTheme}>
                    <section className={this.systemStyles["wrapper"]}>
                          ...
                    </section>
                </ThemeProvider>
            )
        }
    }

    In the above sample, when rendering ModuleScreen, the system styles object information is passed to ModuleScreen through props.

  3. User styles
    First, create assets/styles/{style-file-name}.(s)css file and define styles.
    For example:

    CODE
    // assets/styles/styles.scss
    
    .container_servo-switch {
      display: flex;
      flex-direction: column;
      gap: 10px;
    }

Dart-App projects force CSS Modules through Webpack settings at build time to avoid duplicate style names between systems and apps.

Second, use user styles in the index.tsx file.
For example:

CODE
// index.tsx 

import { ThemeProvider } from "@mui/material/styles";
import styles from "./assets/styles/styles.scss";
...
class MainScreen extends ModuleScreen {
    ...
    render(){
        return(
            <ThemeProvider theme={this.systemTheme}>
                <section className={styles["container_servo-switch"]}>
                <section className="container_servo-switch">
                      ...
                </section>
            </ThemeProvider>
        )
    }
}
  • Language Resources

Click here to expand...

1. Define language resources

Item

Description

src/assets/langs

index.ts

(Mandatory)

It is a file for multilingual resource file (json) that exists under the langs package.

You can define and export stringResources as follows.

CODE
import en from "./en.json";
import ko from "./ko.json";

const stringResources = {
    en,
    ko
};

export default stringResources;

{language_code-REGION}.json

(i.e.) en.json

Resources for each language should be defined as key:value pair under the package name tag of the app as shown below.

CODE
{
  "{app_package_name}": {
    "app_name": "Utility",
  }
}

2. Use language resources in the index.tsx file

  • Use in Class type React component
    Example:

CODE
// index.tsx 

import { ThemeProvider } from "@mui/material/styles";
import { Translation } from "react-i18next";
...
class MainScreen extends ModuleScreen {
    ...
    render(){
        return(
            <ThemeProvider theme={this.systemTheme}>
                <Translation>
                     t =>
                          <section className={styles["container_servo-switch"]}>
                              <h3>{t("app_name", { ns: this.moduleContext.packageName })}</h3> // Use App's language resource
                              <h3>{t("app_name")}</h3> // Use System (Dart-Platform)'s resources
                          </section>
                <Translation>
            </ThemeProvider>
        )
    }
}
  • Use in Function type React component
    Example:

CODE
// index.tsx 

import { ThemeProvider } from "@mui/material/styles";
import { useTranslation } from "react-i18next";
...
class MainScreen extends ModuleScreen {
    ...
    render(){
        return(
            <ThemeProvider theme={this.systemTheme}>
                <AppName />
            </ThemeProvider>
        )
    }
}

function AppName(props: { moduleContext: ModuleContext }) {
    const { moduleContext } = props;
    const { packageName } = moduleContext;
    const { t } = useTranslation();

    return (
        <div>
           <h3>{t("app_name", { ns: packageName })}</h3>// Use App's language resource
           <h3>{t("app_name")}</h3> // Use System (Dart-Platform)'s resources
        </div>
    );
}

Update Package Information Definition File

The manifest.json included in the UC project source should have the following package information defined in JSON format.

Click here to expand...

Key

Description

Naming conventions

name

Module Name

N/A

packageName

Module Unique ID

  • Consist of two or more segments separated by dots (.)

  • Each segment must consist of lowercase letters [a-z] only.

(i.e.) com.dra.jogplus (O), Com.dra.Jogplus (x), .com.dra.jogplus (x), com.dra (x)

version

A number to determine if the package is up to date

Written according to the rules Semantic Versioning.

(i.e.) 1.12.3

sdkVersion

The version of Dart-SDK that you used to build the package.

Positive integer

main

Relative path to the entry script file, built (bundled) via webpack.config.js

index.js

(Cannot be changed)

requiredPermissions

Permission information required for package operation, if '@permission' is used in the declared Dart-API, the corresponding permission information must be listed.

If you are developing a Dart-App with any UC package, the permission information defined in the manifest.json - requiredPermissions of the UC you used must be defined in the manifest.json - usesPermissions of that app.

Note the I/F definition of Permission in the Manifest class in dart-api.ts

supportedLanguages

About the list of languages supported by the package

Format: language_code-REGION (according to FAQ - i18next documentation)

(i.e.). en, en-GB, ko

api

API definition file path for UC package development

index.d.ts

(Cannot be changed)

Below is an example of a manifest.json file.

Document - Guides - Advanced User Guide - Create a BUC - Project manifest

manifest.json file example

Build

After preparing the above necessary files, you can now build your UC project to the *.d/buc file.

Step 1: Click on the Build button on the top right of the screen.

Document - Guides - Advanced User Guide - Create a BUC - Build button

Click on the Build button

Step 2: Check the build result.

Dart-IDE will process the code line until it brings you a specific outcome.

Once done, there will be a notification [INFO] Build successfully with a download link in the OUTPUT panel of Dart-IDE, then you can download the .uc file from that link for later use.

*.dbuc File Structure

(D: directory, F: file, M: mandatory, O: optional)

Entry

M/O

Description

F {package_name}.dbuc

M

UC project source build (bundling), compressed and encrypted files

  • dbuc (Dart User Component)

D assets

O

Resource file folders not included in index.bundle.js

D uc/{package_name}/src

O

When various UCs are included in Dart-App, a folder to avoid duplicating the resources of the UC

  • webpack.config.js auto-generated by assets/resources settings

D images

F {file_name}.png

O

Image Resources Folder

  • Only resources referenced by import(), require() in the source are included in build (bundling)

  • In addition to image resources, resources referenced by the source are included in the .dbuc file

D raws

F {raw_file_name}.*

O

Raws Resources folder

  • Even if the resource is not referenced in the source, it is included in the build .dbuc file

F index.js

M

Package source files

  • styles, langs, and tsx files are built into one file

F index.d.ts

M

API definition file for client (Dart-App)

F manifest.json

M

Package Information Definition File

In case failed, there will be a notification [ERROR] Build failed in the OUTPUT panel of Dart-IDE.

Also, in the OUTPUT panel, you will see the details of the errors. Here, Dart-IDE will point you to where the error is, allowing the user to correct it.

If any errors happen, you should rebuild the project. Dart-IDE will provide the detail of the code editor to adjust or delete unnecessary lines to ensure it runs as you wish.

  • Once you have the .ucfile, you can import it to Dart-IDE to use for your robot application.
    See User Components | Import-BUC-(Upcoming) for more information.

  • Dart-IDE provides option to allow you to open code of UC to public when build it. But code of UC will be hidden when you set the open public code as false.
    Once you publish your UC, you can also selling your UC to Dart-Store. Check Distribute User Component for more details.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.