Using Scaffolding to Develop Vue3 Widgets for Advanced Pages

To enhance widget development and debugging efficiency, the platform offers the Scaffolding tool. This tool allows you to create, develop, debug, preview, release, and download widgets, as well as create local asset projects.

This section describes how to install and use the Scaffolding tool.

1. Start Scaffolding.
   Run the magno ui command in any directory in the command window. The GUI is automatically displayed in the browser.

   Figure 2 Homepage of the Scaffolding graphical operation page
   

   Area 1 is the project management area. You can create or import a local asset project. Area 2 displays the list of existing asset projects. This list is empty when using the Scaffolding tool for the first time. If the Scaffolding tool fails to be started, rectify the fault by referring to Handling Exceptions.

2. Create an application (that is, a new asset project).
   1. On the Scaffolding homepage, click the create button.
   2. In the displayed dialog box, set the directory and name of the new application.
      Figure 3 Setting application information
      
   3. Click Confirm Creation to complete the application creation and start initialization.
      You can also click Import to import an existing application project package.

      • After the application is initialized, the new application is displayed in the application list on the homepage, as shown in the following figure.
        Figure 4 Application created
        
      • The following figure shows the structure of the new application directory.
        Figure 5 Application project directory
        

        Table 1 Directory description

        Directory	Function
        demos	Example of preset widgets.
        packages	Stores widget packages.
        READMD.md	Help document, which describes the commands for initializing projects and creating, previewing, uploading, and downloading widgets.

3. Configure the application.
   1. The Scaffolding tool provides access to the widget development environment for debugging and release. To authenticate access, use OAuth 2.0 client mode.
      • If you have created an authentication key and the corresponding information is available, click the button to check the key in the Operation column. The key information is downloaded to the local host as a file. You can read the client ID (client_id) and client secret (client_secret) from the file for application settings.
        Figure 6 OAuth authentication
        
      • If you have not created an authentication key, perform authentication by referring to Authentication. During OAuth authentication, set the authorization type to client credential when creating an authentication key. You are advised to select a user with System Administrator Profile.
   2. On the homepage, click the new application. The widget management page is displayed.
      Figure 7 Widget management page
      
   3. On the widget management page, click Set up, configure the development environment information, and click the confirm button.
      Figure 8 Application settings page
      

      Table 2 Parameters for setting an application

      Parameter	Description
      Environment Address	Huawei Cloud Astro Zero development environment address.
      Client ID	Client ID required for logging in to the development environment using the Scaffolding tool. For details about how to obtain the client ID, see 3.a.
      Client Key	Client key required for logging in to the development environment using the Scaffolding tool. For details about how to obtain the client key, see 3.a.
      Internet access agent	Configure this parameter if your network is restricted and you need to use a proxy server to access the development environment.
      Proxy Address	Address of the proxy server. This parameter is displayed only when the Internet access agent parameter is enabled.
      Proxy Port	Port number of the proxy server This parameter is displayed only when the Internet access agent parameter is enabled.
      Proxy Authentication Username	It indicates the username for proxy authentication when a proxy server is used. This parameter is displayed only when the Internet access agent parameter is enabled.
      Proxy Authentication Password	It indicates the password for proxy authentication when a proxy server is used. This parameter is displayed only when the Internet access agent parameter is enabled.

      If the Error getting token error message is displayed during the application setting, check the following items:

      • Determine whether a proxy is required when you access the environment from your network.
      • When applying for OAuth authentication records, check whether the selected user has the system administrator profile (System Administrator Profile) and whether the selected authorization type is client mode.

4. Create a widget.
   1. On the widget management page, click the create button create a widget, set parameters, and click Create a new component.
      Figure 9 Creating a widget
      

      Table 3 Parameters for creating a widget

      Parameter	Description
      Type	Type of the widget to be created. The options are as follows: Advanced page widget: Used on advanced pages. This type of widget is stored in packages\advancedPageAssets in the local application project directory. Standard page widget: Used on standard pages. This type of widget is stored in packages\advancedPageAssets in the local application project directory. Vue advanced page widget: Used to develop the Vue single-file widget, which can be packaged into traditional widget packages for advanced pages. Unlike standard or advanced page widgets, it cannot be directly used on the platform. This type of widget is stored in packages\advancedPageAssets in the application project directory.
      Name	Name of the new widget.
      Description	Description of the widget.
      Developer	Developer information.

   2. After the widget is created, the widget management page is displayed, as shown in the following figure.
      Figure 10 Advanced page widget list
      
      For details about the buttons in the widget list, see Table 4.

      Table 4 Buttons

      Button	Name	Function
      	Editing widgets	You can click this to open the widget editing page and develop widgets with the online editor.
      	Opening the local editor	You can click this to open a local editor (such as the Atom, Brackets, Visual Studio Code, IDEA, Notepad++, PyCharm, PhpStorm, RubyMine, Sublime Text and WebStorm editors) to develop widgets.
      	Starting debugging	You can click this to start debugging. A message is displayed, indicating that the debugging address is copied successfully and the debugging address of Widget1 is https://localhost:8001/widget.
      	Previewing widgets	You can click this to preview the GUI effect of a widget. When clicked, a new tab opens displaying the widget's DOM structure. This preview is similar to the effect after an advanced page is released. The page dynamically updates when the widget's DOM structure changes.
      	Configuring widgets	Configures the library resources on which the widget depends.
      	Compiling widgets	You can click this to compile a widget. Upon successful compilation, the path of the widget asset package is displayed.
      	Releasing widgets	You can click this to upload the local widget to the widget library in the environment. After the widget is released, you can view it in the widget library of the corresponding development environment.

      In the packages > advancedPageAssets directory of the application, you can view the new widget newwidget. The following figure shows the directory structure.

      Figure 11 Directory structure
      

      Table 5 Description of the widget directory

      Directory/File	Function
      dist	This directory is created after you click the compile button and is used to store the compiled widget asset packages.
      preview	This directory is created when you click the preview button and contains the code for the widget preview page.
      widget	Widget source code package, which is used for widget development. For details about each file, see Developing Custom Widgets.
      package.json	Metadata file of the current widget project package in the application.

5. Preview and release the widget.

   After a widget is released, you can preview and release the widget.

   1. Preview: Click the preview button.
      Figure 12 Preview effect
      

      the dom of the widget displayed on the preview page is the element contained in the DOM structure of the new widget. The following figure shows the code.

      Figure 13 Code structure
      
   2. Release: Click the release button. In the dialog box that is displayed, enter information such as the widget category. After the widget is published, you can use the published widget on an advanced page created in the development environment.
      Figure 14 Setting parameters for releasing the widget
      

      After the widget is released, you can use the custom widget on an advanced page.

      Figure 15 Using the custom widget on an advanced page
      
      • During widget release, the selected category and domain become the widget's category and domain in the environment. In the development environment, view and use the custom widget within the corresponding category and domain.
      • When developing the widget DOM structure, you can use the widget preview function, which dynamically updates DOM changes.
      • If functions such as event-action and bridge are involved during widget development, you are advised to use the widget debugging function by referring to 6.

6. Debugging a widget

   Developing a widget locally and then packing and uploading its asset package to the environment to check its display effect is inefficient. Instead, you can connect your local environment to the development environment to debug the widget online in real time.

   Before debugging a widget, release it to the development environment widget library and drag it to the advanced page. If you have not performed related operations, perform operations by referring to 5.

   1. On the widget management page of the Scaffolding tool, click (for example, newWidget) next to the widget you want to debug. This enables the widget's debugging function. A dialog box will appear, confirming that the debugging address has been copied. This means you have started widget debugging and have the debugging address ready.
      Figure 16 Debugging address copied
      
   2. After obtaining the debugging address, set the local debugging capability for the widget.
      In the navigation pane, choose Page. Choose More > Page Setting. On the Plugins tab page, click Debug Setting.

      Figure 17 Local debugging settings
      
   3. Configure the widget's local resource access root path by pasting the debugging path copied in 6.a (after starting widget debugging) into the text box and clicking Confirm.
      After the configuration, the widget package configuration data in the local project folder will be read when the advanced page that uses the widget is previewed. In the local debugging settings dialog box, only widgets released via the Scaffolding tool and dragged to the advanced page are displayed.

      Figure 18 Configuring the debugging address
      
   4. On the advanced page that uses the widget, click and then to view the effect of the widget.
   5. After the advanced page is released and previewed, you can modify the widget code in the local asset project for debugging.

      On the widget management page of the Scaffolding tool, click to open the widget editing page, or click to open the local editor for development. Refresh the development environment and preview the new status for debugging and development.

   6. After the widget debugging is complete, click Debug Setting on the Page Setting > Plugins tab page. On the Debug Setting page, select the widget and click Clear Local Resource Access Root. The configuration data in the widget library of the corresponding version is read, manually disable the debugging function.
      You can also set the validity period of the local path. For example, if you set the validity period to 2, the system clears all local resource access root paths and disables the debugging function two days later.

      Figure 19 Disabling the local debugging function
      
   7. Local widget development and debugging are complete. You can now release the widget to the environment for formal use.

      On the widget management page of the Scaffolding tool, click next to the widget to upload its local asset to the environment's widget library.

      If the widget package already exists in the widget library, it will be upgraded. To upgrade the widget, choose Page > Page Setting, click the Plugins tab, and click in the Operation column next to the widget to upgrade it on the site.

7. Download a widget.

   If you need to download a custom advanced widget from the development environment, you can either use the Scaffolding tool to download it, or go to Page Assets > Widgets to download it.

   Currently, the Scaffolding tool supports only the download of custom widgets, but not the download of preset widgets.

   Figure 20 Downloading a widget on the widget management page
   
   Figure 21 Selecting the widget to be downloaded
   
   Figure 22 Returning to the widget management page to preview widgets
   

8. Set the widget and add library resources.

   A library is required for a widget to run normally. During widget development, you can use the Scaffolding tool to configure the widget's dependency library in a local asset project. On the widget management page, click the setting button next to the target widget. Then, click Adding resources, select the required resource library, and click OK.

   Figure 23 Adding resources
   
   Figure 24 Adding required resources