Best Practices: Bring Your Own (BYO) Framework

BYO Component State

Use the component state to reference the current properties or values of a BYO component. Alternatively, you can reference properties of component state dynamically in operations.

To view a component's state in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View., open the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software. and run the following command: UNQENG.tools.getComponentState(key) where key is the component's Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module.. For example, UNQENG.tools.getComponentState('firstName').

BYO Component Event Context (Payloads)

Use Custom Events and their Event Payloads as the primary way to retrieve dynamic data from your BYO component. An example of dynamic data is end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. interactions in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..

Use data from event payloads to create custom events for specific end-user interactions or events. Use these custom events in the Operations Builder to initiate logic by passing data from the event context to inform your operations.

BYO Component Example Scenario

An AG Grid BYO component might have a custom event called On Cell Click (onCellClick). The payload for this event contains the Row Number, Column ID, and Cell Value fields. A Creator Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. can use the Operations Builder and the On Cell Click event context to react when a cell is clicked. They can use the value Row Number and Column ID in their logic open a modal A modal is a window that appears on top of the content you are currently viewing. containing the information of the clicked row.

Version Number

The Unqork Designer Platform requires a Version Number (version) to be set for each BYO Package's Manifest JSON. This version value is important for management of a package in one or multiple environments.

When building or editing a Manifest JSON, use the following information for version numbering:

• The version field is required in every Manifest JSON.

• The version number value applies at the BYO package level. All assets in the package receive the version number.

• In the Custom Assets Administration dashboard, a package's version number displays in the Version column.

Version number best practices:

• Iterate the version number for every significant change to assets in a BYO package. Some examples of significant changes include the following:

  • A change to any setting in any component, event, or operation asset.

  • A change that adds or removes an asset from a package. For example, a new or deleted component, event, or operation.

  • An asset change that results in configuration changes in the Module Builder. For example, behavior changes in a setting.

• When developing new versions of a package, create a copy of the existing package. Doing so is important if you need to roll back to a previous version. If a rollback is required, delete the current version and upload the older version through the Custom Assets Administration page.

Custom Assets Usage

In the Custom Assets Administration page, administrators can view a list of the modules containing a custom component asset.

To view which modules contain custom assets:

1.

From the Homepage, click Administration.

2.

Under Assets, click Custom Assets Administration.

3.

Click the Assets tab.

4.

Navigate to a BYO asset in the list and click View. A list of modules containing the asset displays.

Deleting packages

Administrators can delete BYO packages. Consider the following when deleting packages:

• Deletion occurs at the package level. Deleting a package removes all assets, including the component, events, and operations.

• If required, deleted assets must be manually removed from module definitions. Reference the Used in Module list when viewing the details of a deleted asset. View the Custom Assets Usage section of this article for more details.

• In the Custom Assets Administration screen, administrators can view deleted packages and assets by selecting the Deleted filter.

To delete a BYO package:

1.

From the Homepage, click Administration.

2.

Under Assets, click Custom Assets Administration.

3.

From the Packages list, navigate to a package and click the (ellipsis) button.

4.

Click Delete. A confirmation modal A modal is a window that appears on top of the content you are currently viewing. displays.

5.

Click Delete.

Updating Packages

Currently, the Custom Assets Administration screen does not directly support package updates.

When updating BYO packages, first delete the existing package, then upload a new package to replace the deleted one. Doing so ensures cleanliness and traceability in the environment and module configurations.

Delete the Existing Package

1.

Before deleting the package, copy and retain the Version Number.

2.

Navigate to the Custom Assets Administration screen and delete the package.

3.

After deleting the package, you can view its details using the Deleted filter in the Custom Assets dashboard.

Upload a New Package

1.

Provide the same name to the new replacement BYO package.

2.

Iterate the Version Number using best practices found in the Version Number section of this article.

3.

Upload the new BYO package to the Custom Assets Administration page.

Update Packages FAQ

After deleting a package, module configurations using the old BYO package assets still remain. Here is some detail of the different scenarios that might occur:

Scenario	Change	What happens	Recommended Action
Upload New Component	N/A	The component is ready to use in the Module Builder.	N/A
Update Component	New Setting	If the component type is the same as the previous BYO package, the existing configuration functions as expected. Opening a module containing the updated component displays the new component setting.	Reference the Custom Assets Administration's Assets dashboard to determine which module contain the modified component. Inspect modules containing the updated component to fill in the value for the new setting.
Update Component	Update Existing Setting	If the component type is the same as the previous BYO package, the existing configuration functions as expected. Opening a module containing the updated component displays the updated setting.	Reference the Custom Assets Administration's Assets dashboard to determine which modules contain the modified component. If the setting's data type changed, re-enter the value. If the data type for that setting is the same, no action is required.
Update Component	Delete Existing Setting	If the component type is the same as the previous BYO package, the existing configuration still works. When you open a module with that component, you no longer see the deleted setting in the CSE for your Custom Component.	N/A
Delete Component	N/A	If the component type is the same as the previous BYO package, the existing configuration retains references to the deleted component. As a result, configurations using the deleted assets do not function when previewed in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..	Reference the Custom Assets Administration's Assets dashboard to determine which modules contain the removed component. Inspect the module containing the component and delete it from the configuration.

The above pattern is the same for event or operation assets that might have been manipulated while replacing packages. If those events or operations have the same unique name, they'll be affected in your configuration as seen in the above scenarios.

Promoting BYO Packages

At this time, BYO does not support the automatic promotion of packages. However, module configurations using BYO assets can be promoted. After promoting module configurations, re-upload the BYO packages to the destination environment.

It's important to note the version number of BYO packages before promotion. The version number indicates the package you need to upload at the different environment levels.