Updated on 2025-09-04 GMT+08:00

Procedure of Customizing Standard Page Widgets

Step 1: Obtain the Widget Template Package

Obtain and use the workCards.zip template package to customize widgets. Learn the structure and definition specifications of the template package first.

  1. Click here to obtain workCards.zip.
  2. Unzip the workCards.zip package and learn its structure and definition specifications.

    Figure 1 Structure of workCards.zip
    Table 1 Directories and files in the workCards.zip template package

    Directory and File

    Description

    build

    Stores the widget packaging script.

    dist

    Stores widget packaging files. The files are generated in this directory after being packaged.

    preview

    Widget preview folder.

    src

    Main folder. The widget content is stored in this folder.

    In this practice, you only need to modify the content in the src\components\workCards directory. For details, see Table 2.

    .gitignore

    Ignored files of Git.

    .npmrc

    Sets the installation source of the dependency package in package.json.

    package.json

    Dependency file of the project.

    package-lock.json

    Used to lock the installation version number of the dependency file.

    README.md

    Project prompt file, which is used to describe the widget.

    vite.config.js

    Configuration file of Vite.

    Figure 2 src\components\workCards directory structure
    Table 2 src\components\workCards directory structure

    Directory and File

    Description

    design-time

    Directory of widget files in the development environment.

    static

    Static file directory.

    cube.svg/workCards.svg

    Icon used in a service.

    index.js

    Main entry file of the widget.

    workCards.json

    Widget description file, which is used to customize the widget configuration panel. It helps verify and compile the panel's settings. The workCards.json file must follow JSON Schema specifications to integrate with mainstream editors such as Visual Studio Code (VS Code), Atom, Sublime Text, and WebStorm.

    The workCards.json file can be modified during plugin package development or after compilation. Before compilation, it is stored in the src\components\workCards directory (as shown in Figure 3). After compilation, it is stored in the dist\components\workCards directory (as shown in Table 3).

    workCards.vue

    Main file of a widget.

    Figure 3 Location of the workCards.json file before compilation
    Figure 4 Location of the workCards.json file after compilation
    Table 3 workCards.json parameters

    Parameter

    Description

    name

    Widget name. The name is used for storing and parsing metadata on the backend.

    • The name can contain up to 64 characters. It must start with a letter and can contain only letters, digits, underscores (_), and hyphens (-). It is recommended that the name be in the format of Vendor name_Widget name_Version number, for example, aaa_img-button_1.1.1.
    • The widget name is stored in the type of the UI metadata, for example, type: my-component1.
    • The name of the ZIP package must be the same as the value of name. For example, if name is set to imgbutton, the ZIP package name must be imgbutton.zip.

    title

    In the left-hand widget tab, the alias appears beneath each custom widget. Keep it short and descriptive.

    Value: 1–100 characters.

    description

    Widget description. The description that appears when you hover over the widget.

    Value: 1–200 characters.

    category

    Widget category. Assign your widget to one of the platform's predefined categories to keep the UI builder consistent. For details, see Table 4.

    icon

    Widget icon. There are two PNG icons (unselected and selected status), each no larger than 16 KB.

    other

    Defines the package size. The compiled widget package must be 1 MB or smaller.

    Table 4 Weight categories

    Category

    Description

    navigation

    Navigation widgets, such as menus, toolbars, or sidebars.

    data

    Data widgets, which can be used to view and edit data in applications, such as forms, tables, and lists.

    common

    Common widgets, such as labels, images, titles, and paragraphs.

    container

    Container widgets, which are used to hold and organize other widgets such as grids, rows, and columns.

    input

    Displays and edits entity properties, such as text boxes and date selectors.

    file

    File processing widgets, which include file upload and download, image browsing, and PDF preview.

    button

    Buttons that trigger actions, such as the save button and page redirection button.

    report

    Aggregation widgets which display data in tables or charts, such as chart and pivot table widgets.

    widget

    Service card.

    add-on

    Extended widgets.

Step 2: Customize the imgButton Widget

In this practice, the imgButton widget is a frontend widget built with Node.js. Unless otherwise specified, this practice uses the imgButton widget as the model for VS Code-based customization.

  1. Unzip the template package obtained in Step 1: Obtain the Widget Template Package and rename the resulting folder to imgButton.
  2. Modify the widget description file workCards.json, change name to imgButton, save the file, and exit.

    {
      "name": "imgButton",
      "private": true,
      "version": "1.0.2",
      "type": "module",
      "scripts": {
        "dev": "vite",
        "build": "node ./build/build.mjs",
        "format": "prettier --write src/",
        "preview": "vite preview"
      },
      "dependencies": {
        "element-plus": "^2.4.2",
        "vue": "^3.3.4"
      },
      "devDependencies": {
        "@vitejs/plugin-vue": "^4.6.2",
        "jszip": "^3.10.1",
        "kolorist": "^1.8.0",
        "sass": "^1.69.5",
        "unplugin-element-plus": "^0.8.0",
        "unplugin-vue-components": "^0.25.1",
        "vite": "^4.4.5",
        "vue-style-loader": "^4.1.3"
      }
    }

  3. Modify the name and components parameters in the manifest.json file in the src folder to imgButton, save the file, and exit.

    {
      "name": "imgButton",
      "version": "1.0.10",
      "type": "uiPackage",
      "package": {
        "components": [
          "components/imgButton/imgButton.json"
        ]
      },
      "images": {
        "default": "./static/package-default.png",
        "previews": [
          "./static/package-preview1.png",
          "./static/package-preview2.png"
        ]
      },
      "publisher": "l84182839",
      "license": "MIT",
      "keywords": [
        "UI Component"
      ],
      "categories": [
        "ui:components"
      ],
      "bugs:url": "",
      "repository:url": "",
      "dependencies": []
    }

  4. Modify the name of the src\components folder and the file name in the folder from workCards to imgButton.

    Figure 5 Modifying the folder name
    Figure 6 Modifying the file names in the folder

  5. Replace the widget icon of the custom widget. The icon is the thumbnail of the custom widget displayed in the page builder.

    In src\components\imgButton\static, replace default.png (normal status) and hover.png (mouse-over highlight).

  6. Modify the definition file imgButton.json in src\components\imgButton.

    • Modify the basic properties of the widget definition file.

      In the imgButton.json file, set name, title, and description to imgButton, and restrict properties to height, width, and text. The code is as follows:

      {
        "name": "imgButton",
        "title": "imgButton",
        "description": "imgButton",
        "category": "add-on",
        "icon": {
          "default": "./static/default.png",
          "hover": "./static/hover.png"
        },
        "definition": {
           "props": {
            "type": "object",
            "properties": {
              "height": {
                "category": "common", //Tag to which the property belongs, including common (common), general (basic), and style (style)
                "type": "integer", //Value type of the property, which can be integer (number text box), date (date selection box), string (text box), select (drop-down list), or switch (switch)
                "title": "Image height",//Property title
                "description": "Set the image height.", //Property description, which is displayed when the pointer is hovered over the title
                "default":16 //Default value of the property
              },
              "width": {
                "category": "common",
                "type": "integer",
                "title": "Image width",
                "description": "Set the image width",
                "default":16
              },
              "text": {
                "category": "common",
                "type": "string",
                "title": "framework.label.text",
                "description": "Button text",
                "default":"Button"
              }
            }
          },
        "main": "./index.js",
        "mainDesignTime": "./design-time/index.js",
        "dnd": {
          "cname": "workCards",
          "dname": "workCards-design",
          "ctype": "Control",
          "displayName": "workCards",
          "selectable": true,
          "targetable": true,
          "draggable": true,
          "deletable": true,
          "wholeRow": true
        }
      }

      After saving the changes, the standard page shows the widget with only height, width, and text properties.

      Figure 7 Widget properties

    • Modify the event in the widget definition file and change the event name to click.
      "on": {
            "type": "object",
            "properties": {
              "click": { // Event name triggered in the code, which is triggered using emit in the widget
                "title": "Click", //Event name
                "description": "Action executed upon clicking", //Event description
                "type": "object"
              }
            }
          },
    • Modify the drag behavior in the widget definition file. Set cname, displayName, and dname to imgButton and imgButtonDesign.
      "dnd": {
          "cname": "imgButton",
          "dname": "imgButtonDesign",
          "ctype": "Control",
          "displayName": "imgButton",
          "selectable": true,
          "targetable": true,
          "draggable": true,
          "deletable": true,
          "wholeRow": true
        }

      cname indicates the widget displayed in the application engine, dname indicates the widget displayed in the application development tool, and displayName indicates the text displayed for the widget in the page builder.

    After these modifications, the final imgButton.json is as follows:

    {
      "name": "imgButton",
      "title": "imgButton",
      "description": "imgButton",
      "category": "add-on",
      "icon": {
        "default": "./static/default.png",
        "hover": "./static/hover.png"
      },
      "definition": {
         "props": {
          "type": "object",
          "properties": {
            "height": {
              "category": "common",
              "type": "integer",
              "title": "Image height",
              "description": "Set the image height",
              "default":16
            },
            "width": {
              "category": "common",
              "type": "integer",
              "title": "Image width",
              "description": "Set the image width",
              "default":16
            },
            "text": {
              "category": "common",
              "type": "string",
              "title": "framework.label.text",
              "description": "Button text",
              "default":"Button"
            }
          }
        },
        "on": {
          "type": "object",
          "properties": {
            "click": {
              "title": "Click",
              "description": "Action executed upon click",
              "type": "object"
            }
          }
        },
        "methods": {
        }
      },
      "main": "./index.js",
      "mainDesignTime": "./design-time/index.js",
      "dnd": {
        "cname": "imgButton",
        "dname": "imgButton",
        "ctype": "Control",
        "displayName": "imgButton",
        "selectable": true,
        "targetable": true,
        "draggable": true,
        "deletable": true,
        "wholeRow": true
      }
    }

  7. Modify the view file imgButton.vue in the src\components\imgButton directory.

    • Modify the layout structure of the view file.

      Add an img and a span to the layout (div tag) and configure the parameters according to the example. The code example is as follows:

      <img
        src="./static/hover.png"
        :height="comHeight"
        :width="comWidth"
        :class="classes + '-img'">
      <span :class="classes+ '-title'">
        {{ currentText }}
      </span>

      img indicates the image in the imgButton button, and span indicates the text in the imgButton button.

    • Modify the property definition of the view file imgButton.vue and change cssprefix to imgButton and add the height, width, and text properties.
      <script>
      const cssprefix = "imgButton";
      
      import { defineComponent } from "vue";
      
      export default defineComponent({
        name: "imgButton",
        data() {
          return {
            currentText: this.text,
          };
        },
        props: {
          /*Image height */
          height: {
            type: [String, Number],
            default: "",
          },
          /*Image width */
          width: {
            type: [String, Number],
            default: "",
          },
          /*Tag text content */
          text: {
            type: String,
            default: "Button1",
          },
        },
    • Modify computed, watch, and methods in the imgButton.vue view file.
        computed: {
          classes() {
            return cssprefix;
          },
          comHeight() {
            return this.height || "16";
          },
          comWidth() {
            return this.width || "16";
          },
        },
        watch: {
          text(newVal) {
            this.currentText = newVal;
          },
        },
        methods: {
          onclick(e) {
            this.$emit("click", e);
          },
          setButtonText(newText) {
            console.log("setButtonText params:", newText);
            if (newText) {
              this.currentText = newText;
            }
          },
        },
      Table 5 computed, watch, and methods parameter description

      Parameter

      Description

      cssprefix

      Constructs the style class name to improve flexibility.

      currentText

      Displays the button text.

      comHeight

      Obtains the image height.

      comWidth

      Obtains the image width.

      classes

      Returns the style class name. You can also replace the variable with a character string to increase flexibility.

      onclick

      Triggers the service logic of the click event when the image button is clicked.

      setButtonText

      Changes the text in the button. This method is exposed externally. All methods defined in method can be directly called in events. Figure 8 shows the calling mode.

      Figure 8 Calling the method
    • Modify the style in the view file imgButton.vue to define the style class of the image button. The style class includes the image button frame, image, and text.
      .imgButton {
        display: inline-block;
        background-color: #8cdcdb;
        border: blue1pxsolid;
        cursor: pointer;
      }
      .imgButton-img {
        margin-top: 5px;
        margin-left: 5px;
      }
      .imgButton-title {
        padding-bottom: 10px;
        padding-right: 10px;
        font-size: 16px;
        cursor: pointer;
      }

  8. Modify the control definition file index.js of the application development tool and application engine in the src\components\imgButton\index.js directory. Change workCards in the control definition file to imgButton.

    import imgButton from './imgButton.vue'
    
    export default imgButton

  9. After the custom image is developed, perform the following operations to generate a custom image package.

    1. On your local PC, press Windows logo key+R and enter cmd to open the command prompt.
    2. Go to the folder where imgButton is located and run the following command to generate the custom widget package dist\imgButton-***.zip:
      If a message is displayed indicating that the Yarn is not installed when you run the yarn commands, run the bnpm install -g yarnb command to install it.
      yarn install
      yarn run build
      Figure 9 Generating a custom widget package

      You have completed customizing and packaging the widget. You can compare your generated widget package with the provided imgButton.zip sample.

Step 3: Upload the Custom Widget Package

Upload the custom widget package to Huawei Cloud Astro Zero and use it on standard pages.

  1. Apply for a free trial or purchase a commercial instance by referring to Authorization of Users for Huawei Cloud Astro Zero Usage and Instance Purchases.
  2. After you have an instance, click Access Homepage on Homepage. The application development page is displayed.

    Figure 10 Application development page

  3. Click in the upper left corner of the page and choose Environments > Environment Configuration.
  4. On the Environment Configuration page, choose Maintenance from the main menu.

    Figure 11 Selecting Maintenance

  5. In the navigation pane, choose Global Elements > Page Assets > Custom Widgets.

    Figure 12 Selecting a custom widget

  6. On the displayed page, click New and select the custom widget imgButton.zip created in Procedure of Customizing Standard Page Widgets and upload it.

    After the upload is successful, the custom widgets page is displayed. You can view imgButton in the widget list.

    Figure 13 Viewing the uploaded custom widget

Step 4: Verify the Custom Widget

Create a standard page and drag the custom widget onto it to check if it displays properly. Add display and hide events for the custom widget and verify that the effects meet the expectations.

  1. Create a low-code application.

    1. On the Huawei Cloud Astro Zero console, click Access Homepage to go to the application development page.
    2. In the navigation pane, choose Applications. On the displayed page, click Low-Code or .
    3. In the displayed dialog box, choose Standard Applications and click Confirm.
    4. Enter a label and name of the application, and click the confirm button. The application designer is displayed.
      Figure 14 Creating a blank application
      Table 6 Parameters for creating a blank application

      Parameter

      Description

      Example

      Label

      The label for the new application; Max. 80 characters. A label uniquely identifies an application in the system and cannot be modified after creation.

      My first application

      Name

      Name of the new application. After you enter the label value and click the text box of this parameter, the system automatically generates an application name and adds Namespace__ before the name. Naming rules:

      • Max. characters: 31, including the prefix namespace.

        To prevent duplicate data names among different tenants, each tenant must define a unique namespace when first creating an application. A tenant can only create one namespace, and once it is created, it cannot be modified.

      • Start with a letter and use only letters, digits, and underscores (_). Do not end with an underscore (_).

      A

  2. In the navigation pane, choose Page, and click + next to Standard Page.
  3. Drag the input box and column widgets from Basic to the canvas. The layout is shown in Figure 15.

    Figure 15 Dragging the input box and column widgets

  4. Select the column widget, choose Properties > Style > Layout, and set the width to 360 pixels.

    Figure 16 Adjusting the widget width

  5. Drag the imgButton widget from Custom to the two columns of the column widget.

    Figure 17 Dragging the imgButton widget to the columns

  6. Select the custom widget in each column, choose Properties > Common, and set Text to Display in the first and Hide in the second.

    Figure 18 Modifying the widget text content

  7. Select the Display widget, click the Events tab, and click + next to on-click.

    Figure 19 Creating an event

  8. Under the built-in actions, choose Display/Hide Control and click Add Control.

    Figure 20 Clicking Add Control

  9. Select the input widget, set Visibility of the "Display" button to Display, and click Create.

    Figure 21 Selecting the input widget
    Figure 22 Setting the visibility of the Display button to Display

  10. Similarly, set Visibility of the Hide button to Hide.

    Figure 23 Setting the visibility of the hide button to Hide

  11. Verify the effect.

    Click in the upper part of the standard page to save the settings. After the settings are saved, click . The preview page is displayed. On the preview page, click Hide. The input widget is hidden. Click Display. The input widget is displayed.

    Figure 24 Preview effect
    1. Click in the upper part of the standard page to save the settings. After the settings are saved, click . The preview page is displayed.
      Figure 25 Preview page
    2. Click Hide. The input widget is hidden.
      Figure 26 Input widget hidden
    3. Click Display. The input widget is displayed.
      Figure 27 Input widget displayed

Other Operations: Update the Custom Widget Package

If you change the widget's code, re-upload the updated package to replace the existing version. After the widget content is updated, change the version in src/manifest.json from 1.0.5 to 1.0.6, and run the yarn run build command again. After the packaging is complete, the imgButton-1.0.6.zip package is generated in the dist folder.

  1. On the Huawei Cloud Astro Zero console, click Access Homepage to go to the application development page.
  2. Click in the upper left corner of the page and choose Environments > Environment Configuration.
  3. Choose Maintenance from the main menu.
  4. In the navigation pane, choose Global Elements > Page Assets > Custom Widgets.

    In the custom widget list, the current widget version is 1.0.5.
    Figure 28 Widget version: 1.0.5.

  5. Click New, select the imgButton-1.0.6.zip package, and click Open.

    After the update, the custom widget list shows version 1.0.6. Go to the standard page where the custom widget is used. The widget content is updated.

    Figure 29 Widget version: 1.0.6