HowToCreateUiComponents

How to create UI components

When developing applications with the Open Pioneer Trails client framework, React (opens in a new tab) can be used to create UI components. We can also use pre-defined components from the Chakra UI (opens in a new tab) framework.

Documentation

React’s official documentation (opens in a new tab)
Chakra’s component overview (opens in a new tab) (with lots of examples)

Getting started

In this tutorial, we will take the empty app (src/apps/empty) as a starting point.

Start your dev server (by running pnpm dev) and open the empty app in your browser (usually at http://localhost:5173/sites/empty/ (opens in a new tab)).

The app’s main entry point (app.ts) creates and defines a custom element class (from the Web Component standard, see MDN (opens in a new tab)), including the app’s user interface:

1
import { createCustomElement } from "@open-pioneer/runtime";
2
import * as appMetadata from "open-pioneer:app";
3
import { AppUI } from "./AppUI"; // (1)
4

5
const Element = createCustomElement({
6
    component: AppUI, // (2)
7
    appMetadata
8
});
9

10
customElements.define("empty-app", Element);

(1) Imports AppUI (a React component) from the given module.
(2) Specifies AppUI as the application’s UI. Any kind of React component can be used in this place.

When the application is instantiated, the AppUI component will be rendered automatically.

React components are typically developed in .jsx or .tsx files, which are JavaScript/TypeScript modules with JSX (opens in a new tab) syntax extensions. In this case, the app’s entire UI is defined in AppUI.tsx:

1
// (1)
2
import { Container, Heading, Text, chakra } from "@chakra-ui/react";
3
import { useIntl, useService } from "open-pioneer:react-hooks";
4
import { Greeter, SimpleUiComponent } from "sample-package";
5

6
// (2)
7
export function AppUI() {
8
    const intl = useIntl();
9
    const greeter = useService<Greeter>("sample-package.Greeter");
10
    // (3)
11
    return (
12
        <Container>
13
            <Heading as="h1" size="lg">
14
                {intl.formatMessage({ id: "heading" })}
15
            </Heading>
16
            <Text pt={5}>{intl.formatMessage({ id: "text" })}</Text>
17
            <Text pt={5}>
18
                This messages comes from the sample package{"'"}s greeter service: {greeter.greet()}
19
            </Text>
20
            <chakra.div mt={5}>
21
                <SimpleUiComponent textToShow="This text is rendered inside the sample UI-Component 'SimpleUiComponent'"></SimpleUiComponent>
22
            </chakra.div>
23
        </Container>
24
    );
25
}

(1) Imports Chakra components used by the app’s UI. Remember to use @open-pioneer/chakra-snippets for imports of chakra snippets (not used in this example).
(2) Defines a React component called AppUI. (Almost) all React components should be defined as functions (either function ComponentName ... or const ComponentName = ...);
(3) This defines the content of the component. In this case, Chakra components (e.g. Container, Text) are used. You can also use plain html elements, like div or p.

The intl object here is used to translate messages into multiple languages (see How to translate an App). We will not dive into internationalization (i18n) in this tutorial and use static strings instead.

Defining new UI components

Defining a new React component is as simple as creating a new function. For this example, we will create a button that has a label and tracks the number of times it has been clicked:

1
import { Container, Heading, Text, chakra, Button } from "@chakra-ui/react";
2
import { useState } from "react";
3

4
// export function AppUI ...
5

6
interface ClickableButtonProps {
7
    label: string;
8
}
9

10
// (1)
11
function ClickableButton({ label }: ClickableButtonProps) {
12
    // (2)
13
    const [clickCount, setClickCount] = useState(0);
14
    const incrementClickCount = () => {
15
        setClickCount(clickCount + 1);
16
    };
17

18
    // (3)
19
    const clickText = clickCount === 0 ? "" : `(${clickCount})`;
20
    return (
21
        <Button onClick={incrementClickCount}>
22
            {label} {clickText}
23
        </Button>
24
    );
25
}

(1) Defines the new component. React components should start with an uppercase letter and take a single parameter (called props); in this case props can contain a label property.

Note In simple (local) components like this, you could also inline the type definition of ClickableButtonProps. If you have many properties, or intend to share your components across modules or packages, using a separate type is strongly recommended.
(2) Uses the useState (opens in a new tab) hook to remember the number of types the button has been clicked.
(3) Renders the button with the appropriate text and wires up the onClick handler.

Now, use the new button from the AppUI component:

1
import { Container, Button, VStack } from "@chakra-ui/react";
2
import { useState } from "react";
3

4
export function AppUI() {
5
    return (
6
        <Container>
7
            <VStack>
8
                <ClickableButton label="First" />
9
                <ClickableButton label="Second" />
10
            </VStack>
11
        </Container>
12
    );
13
}
14

15
// interface ClickableButtonProps ...

The final result looks like this (after a clicking a few times):

Buttons with click count

Embedding images

Images or other static resources from your app or package can usually be imported directly into your source code. For example, to embed an image called my-image.png from the same directory as your React component:

1
import { Image } from "@chakra-ui/react";
2

3
// Import image as URL
4
import myImageUrl from "./my-image.png";
5

6
// Later, use the URL in your code
7
<Image src={myImageUrl} />;

This approach works well if you only care about the assets data, and not its file name or location. It relies on Vite’s support for static assets (opens in a new tab), which will automatically bundle the referenced files as assets of your application.

For different approaches and more details, see Including static assets.

Defining a UI Component in a different module

Since react components are simple functions (or sometimes classes), they can be simply be moved into another file in combination with the usual import and export keywords.

Moving a component into a shared package is just as simple: just export the component (and its props type, if using TypeScript) from the package, for example from the index.ts[x].

Interacting with the rest of the system

React props are a powerful system that can handle arbitrary values such as strings (like in the example above), but also functions (e.g. event handlers or render props (opens in a new tab)). However, props work only from parent to child, which can be tedious with deeply nested component trees.

React has a second system (the Context API (opens in a new tab)) that can be used to inherit values into all children (and their children etc.) of a certain component. This can be extremely powerful but also makes components harder to understand.

We have implemented hooks such as useService and useIntl (built on top of the context API) to allow React components to interact with the rest of the framework (see How to use a service and How to translate an app).

It is best to compose a UI from a set of simple, reusable React components that mostly rely on props and hooks. This makes them easier to understand, to reuse and to test in isolation. More powerful mechanisms should only be used when those simple approaches are not sufficient anymore.

Keeping shared state

Like mentioned above, simple state can often be managed through props and component-local state.

Plain services (together with events) can be used to keep state that is used in multiple places (components, services) of the application.

To manage more complex state, React developers usually reach for a state management library (e.g. Redux or Zustand). We have implemented a custom state management solution based on signals (see Reactivity-API (opens in a new tab), Trails bindings for React (opens in a new tab)). This API is used for reactive interfaces provided by Trails packages and will probably fit your needs as well. A relatively complete example is available here (opens in a new tab).

Other third party libraries that work well, too: