Form Customization

Feature	Free plan	Basic edition	Professional edition	Dedicated edition
Custom components	Not supported	Not supported	Supported	Supported

1. Feature Overview

1.1 About Custom Components

Custom components let you build your own components. This improves the fit between components and your business needs, lowers development and maintenance costs, and increases reusability.

1.2 Use Cases

When the standard YiDA components do not meet your app’s business needs, build a component tailored to your scenario based on industry practices or requirements. Custom components can also be shared across the same organization, making them easy to reuse when you build similar apps later.

1.3 Component Structure

A component consists of a view and attributes. On the consumer side, you change a component’s attributes to render different views. The view divides further into a design view and a runtime view. In most cases, the two views can be reused. On the producer side, you build the view and the attributes separately.

2. Step-By-Step Guide

Walk through a small example that implements a text-copy feature with a custom component to experience the full flow: build, debug, install, and use.

2.1 Scenario

Use the custom component feature to extend YiDA’s built-in Text component with low-code, and implement a text-copy feature. Users can copy field content to the clipboard, which helps when they need to reuse the same values.

2.2 End Result

Figure 2.2-1 Text-copy demo

2.3 Steps

2.3.1 Step 1: Create a Custom Component

Configure the component’s name, type, identifier, and other attributes to create a component that fits your business needs at low cost. Steps:

YiDA app > App settings > Component management > Component center (see Figure 2.3-1).

Figure 2.3-1 Enter the component center

Add component > Fill in the component name, type, identifier, and other attributes > Confirm (see Figure 2.3-2).

Figure 2.3-2 Create the custom counter component

Regular components are typically used for display-only features and cannot store data. They do not support data submission. Confirm your business scenario before designing the component. If the component includes elements such as text input boxes, any data submitted by users will not be saved.

2.3.2 Step 2: Develop and Debug the Custom Component

Develop and debug the component to meet different business needs. This example implements a counter feature. Steps:

Component center > My components > Locate the component to debug > Develop (see Figure 2.3-3).

Figure 2.3-3 Entry point for developing and debugging a custom component

Step 1

As mentioned above, a component is built from a view and attributes. When developing a component, first abstract the attributes it needs. Start with the attributes: this component needs only one attribute for the text content. Go to Attribute configuration > Attribute definition, add a text content attribute named content, set the attribute type to text, and choose textSetter as the setter.

Step 2

Once the attributes are defined, build the component’s view. Drag the required standard YiDA components onto the canvas (this example uses two Text components, named “Text” and “Copy”) and configure their basic attributes. Bind the Text component’s content to a variable — the attribute props.content you just defined — so the passed-in value renders at runtime (see Figure 2.3-4).

Figure 2.3-4 Custom component layout

Configure an action on the Button component to implement the text-copy behavior. Select the “Copy” text > Create action > onCopyText on click (see Figure 2.3-5).

Figure 2.3-5 Configure the button action

Write the copy logic in the JS panel (see Figure 2.3-6).

Figure 2.3-6 Code for the “Copy” button action

export function onCopyText() {
  const input = document.createElement('input');
  input.setAttribute('readonly', 'readonly');
  // Access attributes via this.props.xxx
  input.setAttribute('value', this.props.content);
  document.body.appendChild(input);
  input.select();
  input.setSelectionRange(0, 9999);
  document.execCommand('copy');
  document.body.removeChild(input);
  this.utils.toast('Copied to clipboard');
}

Save > Preview the component

Publish > Fill in the version number and release notes > Confirm (see Figure 2.3-7).

Figure 2.3-7 Fill in the release information

A confirmation appears when the component is published (see Figure 2.3-8). In real development, once you save the component, you can install the development version (0.1.0) for live debugging. Publish an official version only after development is complete.

Figure 2.3-8 Publish success notification

2.3.3 Step 3: Install the Custom Component

Install the developed and debugged component into a page so you can use it when designing that page. During component installation, select a page type. The custom component appears only in the page designer of the page type you select. Steps:

Form design page > Component library > Custom components > Component management (see Figure 2.3-9).

Figure 2.3-9 Entry point to install a custom component

Component management page > Component list > Select the custom component to install > Install (see Figure 2.3-10).

Figure 2.3-10 Select the component to install

Choose the installation version and installation scope > Install (see Figure 2.3-11).

Figure 2.3-11 Install the component

To keep custom components stable in production, always install the official 1.x.x release when choosing a version.
To make a custom component available in the page designer, select the matching page type in the installation scope. The component appears only in the page designer for the page types you selected.
After the first installation, the component version supports “Update”.

2.3.4 Step 4: Use the Custom Component

After the steps above, the custom component appears under Custom components in the page’s component library. Use it as follows. Steps:

Form design page > Component library > Custom components > Select the desired component > Drag it onto the canvas (see Figure 2.3-12).

Figure 2.3-12 Use the custom component

2.3.5 Step 5: View or Edit Component Information

To update a component’s thumbnail, help document URL, or description while it is in use, follow the steps below. Steps

App settings > Component management > Component center (see Figure 2.3-13).

Figure 2.3-13 Enter the component center

Select the component to view or edit > Details (see Figure 2.3-14).

Figure 2.3-14 View component details

The component details page contains three sections: Basic information, Release information, and Admin (see Figure 2.3-15).

Basic information: Click “Edit” to update the custom component’s thumbnail, help document URL, and description. Other fields are set when the component is created and cannot be changed.
Release information: View the component’s iteration history, including versions and their release notes.
Admin (has permission to develop and debug the custom component; defaults to the component creator): Add or remove admins to manage permissions.
Installation information: View the component’s installation history, including the installed app, version, scope, installer, and installation time.

Figure 2.3-15 Component details page

3. Custom Component Attributes

Beyond extending existing YiDA components, the custom component feature lets you customize the attributes (propTypes) of the components you build. This makes custom components a better fit for developers’ daily scenarios and habits, and provides greater flexibility.

3.1 Entry Point for Configuring Custom Component Attributes

Path: Low-code component designer > Select the “low-code business component” on the canvas > Attributes on the right (see Figure 3.1-1). Figure 3.1-1 Entry point for configuring custom component attributes

3.2 Custom Component Attribute Configuration

Custom component attributes are organized into four sections: Dual-end design, Attribute definition (propTypes), Lifecycle, and Unique identifier.

Dual-end design: A toggle. When enabled, the PC and mobile designs are fully separated, so you can design each side independently to meet different requirements on both ends.
Attribute definition (propTypes): Customize basic attributes of the custom component, such as Title, Name, Type (data format), and Default. You can also bind events for Whether hidden (visibility state) and On change (value changes) to cover a wide range of business needs. For details, see Component attribute configuration.
Lifecycle: A custom component has four lifecycle hooks — component mounted (componentDidMount), component updated (componentDidUpdate), component caught error (componentDidCatch), and before component unmount (componentWillUnmount). Write logic in the appropriate hook to meet complex business needs.
Unique identifier: Like standard YiDA components, custom components have a unique identifier attribute that serves as the component’s ID. It is generated automatically and usually does not need to be changed. YiDA uses it for backend data storage, code binding, and so on.

Important:

A component’s unique identifier (fieldId) is the ID YiDA uses to reference the component. Changing it may affect formulas, data storage (data may even be lost), and JS function references that use the component. We strongly recommend that you do not change the unique identifier.
If you still change it (currently only possible via schema import), you acknowledge the consequences and accept sole responsibility for them. YiDA is not liable for the outcome. Thank you for your understanding.
The component alias works the same as the unique identifier (fieldId). Because fieldId is system-generated and hard to remember, use an alias to make the field name easier to reference in code and OpenAPI calls.

4. Appendix

4.1 Component Types

YiDA custom components come in three types: Regular component, Form component, and Portal component. The key differences are:

Regular components are typically used for display-only features and cannot store data. They are similar to the built-in “Rich text” and “Group” components.
Form components can submit data. They are more complex to develop than regular components and require additional metadata configuration.
Portal components are also used for display-only features and cannot store data. They are designed for use on portal pages.

4.2 Component Installation Types

YiDA page types include regular form page, workflow form page, report page, DataV dashboard, custom page, external link, and portal page. YiDA custom components (regular component type) can currently be installed on custom pages, regular forms, and workflow forms. When installing, select the matching page type — the component then appears in the page designer for that page type.

4.3 Component Versions

YiDA custom components have two versions: development and official. We added extra conventions on top of semantic versioning.

0.1.0 is the default development version. The development version stays in real-time sync with the component designer and is used for debugging.
1.x.x is the official released version. It locks the current functionality and ensures stability in production. For production apps, always install the 1.x.x official release.

5. FAQ

Q: Is deleting a component safe? Deleting and uninstalling components is now supported. Developers are responsible for ensuring backward compatibility. Q: How should I understand custom components? Refer to this link. Q: What is a component made of? A component consists of a view and attributes. On the consumer side, you change a component’s attributes to render different views. The view divides further into a design view and a runtime view. In most cases, the two views can be reused. On the producer side, you build the view and the attributes separately. Q: If an app that uses a custom component is distributed to another organization via app distribution, will it open correctly? Yes. After the app is distributed to another organization, that organization can use the component normally. If the distributed app has Edit Permission enabled, the target organization can also install components. Q: How do I read a custom component’s attribute on the page? Custom components behave like Basic components. Use this.$('fieldId').get('propName') to read an attribute. Q: How do I update a custom component’s attribute on the page? Custom components behave like Basic components. Use this.$('fieldId').set('propName', propValue) to update an attribute. You can also bind the attribute to a Data Source variable. Q: How does a component access and interact with other components on the page? Add a function-type attribute to the custom component — an event callback. On the page, use this callback to interact with other components. Inside the component, call this.props.xxx() at the appropriate time — for example, on a component event or in the component’s DidMount — to fire the callback. Tip: function-type attributes support a Default value and can be hidden. Q: Can custom components install third-party NPM packages? A: Not yet. Load CDN resources dynamically instead.

function loadScript(src, callback) {
  if (!src) {
    return;
  }
  const node = document.createElement('script');
  node.src = src;
  node.addEventListener('load', callback, false);
  document.head.appendChild(node);
}
function loadCss(url) {
  const linkElement = document.createElement('link');
  linkElement.rel = 'stylesheet';
  linkElement.href = url;
  document.body.appendChild(linkElement);
}
(function loadAssets() {
  loadCss('https://dev.g.alicdn.com/yida-platform/react-cropper/1.0.0/css/react-cropper.css');
  loadScript('https://dev.g.alicdn.com/yida-platform/react-cropper/1.0.0/js/react-cropper.js', () => {
    // your code
  });
})();

Q: I installed a component but do not see it in the panel. Why? A: Check the installation scope. Q: How can a custom component submit data in a form? A: YiDA custom components do not yet support the form component type. To submit data, populate an existing form component instead. For example, declare a “unique identifier” attribute, pass in the identifier of an existing form field when using the component, and, on the component side, use events to write the required data back to that form field. Q: How does component versioning work? Components have a development version and an official version. YiDA custom component versions follow additional rules on top of semantic versioning. 0.1.0 is the default development version. The development version stays in real-time sync with the component designer and is used for debugging. 1.x.x is the official released version. It locks the current functionality and ensures stability in production. For production apps, always install the 1.x.x official release. Q: I defined an attribute. How can the component react to changes in that attribute? In the component designer, locate the target component and the relevant attribute. Bind the attribute to a variable or a custom handler function, then use this.props.xxx to branch your logic. For example: Or Q: Can I set styles dynamically inside a component? Yes. Use a container component, add a “custom style class” to it, and bind the class to a variable. Q: Do custom components support parent-child or upstream-downstream organizations? A: Custom components do not yet support cross-organization use, including parent-child and upstream-downstream organizations.

Getting Started

Quick Start

Form Management

Workflow Design

Report Design

Aggregate Table Design

Portal Design

Custom Pages

Integration & Automation

Cool App

App Management

Platform Management

Internationalization

YiDA Dedicated

Developer Features

1. Feature Overview

1.1 About Custom Components

1.2 Use Cases

1.3 Component Structure

2. Step-By-Step Guide

2.1 Scenario

2.2 End Result

2.3 Steps

2.3.1 Step 1: Create a Custom Component

2.3.2 Step 2: Develop and Debug the Custom Component

2.3.3 Step 3: Install the Custom Component

2.3.4 Step 4: Use the Custom Component

2.3.5 Step 5: View or Edit Component Information

3. Custom Component Attributes

3.1 Entry Point for Configuring Custom Component Attributes

3.2 Custom Component Attribute Configuration

4. Appendix

4.1 Component Types

4.2 Component Installation Types

4.3 Component Versions

5. FAQ

​1. Feature Overview

​1.1 About Custom Components

​1.2 Use Cases

​1.3 Component Structure

​2. Step-By-Step Guide

​2.1 Scenario

​2.2 End Result

​2.3 Steps

​2.3.1 Step 1: Create a Custom Component

​2.3.2 Step 2: Develop and Debug the Custom Component

​2.3.3 Step 3: Install the Custom Component

​2.3.4 Step 4: Use the Custom Component

​2.3.5 Step 5: View or Edit Component Information

​3. Custom Component Attributes

​3.1 Entry Point for Configuring Custom Component Attributes

​3.2 Custom Component Attribute Configuration

​4. Appendix

​4.1 Component Types

​4.2 Component Installation Types

​4.3 Component Versions

​5. FAQ

1. Feature Overview

1.1 About Custom Components

1.2 Use Cases

1.3 Component Structure

2. Step-By-Step Guide

2.1 Scenario

2.2 End Result

2.3 Steps

2.3.1 Step 1: Create a Custom Component

2.3.2 Step 2: Develop and Debug the Custom Component

2.3.3 Step 3: Install the Custom Component

2.3.4 Step 4: Use the Custom Component

2.3.5 Step 5: View or Edit Component Information

3. Custom Component Attributes

3.1 Entry Point for Configuring Custom Component Attributes

3.2 Custom Component Attribute Configuration

4. Appendix

4.1 Component Types

4.2 Component Installation Types

4.3 Component Versions

5. FAQ