Create a UIPluginV2 Contract
Learning Objectives
After completing this unit, you’ll be able to:
- Describe the components of user interface (UI) plugins.
- Explain the functions of iframe and React classes.
- Create a UIPluginV2 contract in Visual Studio (VS) Code-based Modeler.
Before You Start
Before you start this module, consider completing the following recommended content.
Also, to complete the work in this badge, you need a VS Code-based Modeler implementation and a Salesforce org with these installations.
- Consumer Goods Cloud Managed Package
- Consumer Goods Cloud Mobile Sync
- Salesforce Command-Line Interface (CLI) with Modeler plugin
- Git client
- VS Code
- VS Code extensions or plugins, such as Git viewer and SQLite
If you have a sandbox instance or Salesforce test org with these installations, you can try out the steps mentioned in this module. If you don’t have a sandbox and you’re a customer or partner developer, contact your Salesforce admin to request one.
Endless Possibilities
Alpine Group is a leading manufacturer of nutrition and beverage products in the United States. The field sales reps at Alpine use the Consumer Goods (CG) offline mobile app to perform store audits and product surveys. While the app is a great asset, the reps are looking for ways to customize it to boost their productivity. They want to customize the appearance of the app, create charts, and communicate with other third-party apps from the offline mobile app.
The sales reps request help from Fatima Daniels, the Salesforce developer at Alpine Group. Fatima knows just the tool to meet their requirements.
Fatima uses the CG Modeler to configure and customize the app’s UI, processes, and business logic. CG Modeler is a Visual Studio (VS) Code-based tool that is easy to set up and has low maintenance costs.
The Modeler offers various options for app customization. For example, Fatima can create UIPluginV2 controls in the Modeler to build and show charts on the app. UIPluginV2 is a special control that developers such as Fatima use to integrate plugins into the UI. UIPluginV2 cannot access the file system or database for security reasons. So, she can only work with the elements and data she hands over to the plugin.
In this module, follow Fatima as she uses the CG Modeler to create a UIPluginV2 contract for showing charts on the CG offline mobile app. She also creates buttons that help sales reps communicate with other third-party apps from the offline mobile app.
UI Plugin Definition
What are UI plugins? They’re React classes that host an inline frame, also called iframe, within the CG offline mobile app. Here’s a look at the elements that a UI plugin definition contains. Click each element to learn more.
This image shows the relationship between the different UI plugin elements.
The iframe is the HTML element that defines an HTML web page. While the JavaScript libraries and CSS define the head content of the iframe, the HTML and JavaScript define the body content of the iframe.
Communication within the framework works with JavaScript bindings and events. Follow Fatima as she explores these concepts more.
Iframes and React Classes
Next, Fatima learns about the components of UI plugins, such as iframes and React classes.
-
iframe: An iframe is an HTML element that embeds an HTML web page within the parent web page.
-
React: React is a JavaScript library for building UIs.
-
Classes: Classes are templates for creating JavaScript objects and defining their behavior by using syntax and semantics unique to the classes.
-
React classes: React classes are simple classes made up of multiple functions. These classes can have a state, lifecycle method, and event handler. You use these classes to build complex and stateful UI components.
For UIPluginV2, the code runs in iframe—a sandbox in the browser. That’s why direct access to the database or the filesystem and FileWriter classes is impossible. To show or modify data, pass the data as parameters from the process. This also helps to protect the business logic layers.
Fatima has a good understanding of the UI plugin components now. Follow along as she creates a UIPluginV2 contract in the next section.
UIPluginV2 Contract for Showing Charts
Salesforce developers such as Fatima use UIPluginV2 contracts to build embedded offline reports for the CG offline mobile app. They also use the C3 and D3 JavaScript libraries to build reusable charts. Sample charts such as these are available out-of-the-box on the mobile app.
- Customer Sales Report
- Promotion Calendar
- Visit Rate Report
- Visit Success Report
- Survey Exception Report
Such charts and reports are useful for sales reps and sales managers because they can readily analyze the business data and make informed decisions.
UI contracts describe the UI elements in the CG offline mobile app such as cockpits, master-detail pages, tab pages, and tab areas.
Fatima uses a UIPluginV2 contract to show a Competitor Rate custom report on the app. This report shows the competitor rate of the available displays in a store.
What does it mean? In a retail store, Alpine Group’s competitors also showcase their products in the same category. Sales reps review the percentage of products from each brand to understand trends such as the share-of-shelf of a product. They then analyze the percentage of displayed products from Alpine Group and its competitors. The Competitor Rate report shows this info with an easy-to-understand chart.
Here, a 33.3% competitor rate on the chart means that competitor products make up 33.3% of displayed products in a retail store. The remaining 66.7% of displayed products are from the Alpine Group.
CG Cloud gets the data for competitor fields from the Display business object. Developers such as Fatima can pass the count of competitor fields as a parameter to show or modify the data.
To set up a report with the Competitor Rate chart, Fatima creates a UIPluginV2 contract in CG Modeler using these steps.
- Create the UIPluginV2 file.
- Implement the plugin.
- Create a global label.
- Prepare data in the business object.
- Add a cockpit card to view the chart.
In this module, we assume you’re a Salesforce developer with the proper permissions to set up CG Modeler. If you’re not a developer for CG Modeler, that’s OK. Read along to learn how your developer would take the steps in a production org. Don’t try to follow these steps in your Trailhead Playground. CG Modeler isn’t available in the Trailhead Playground.
Before creating a UIPluginV2 contract, Fatima uses the CG Modeler to create, model, and expose a custom card on the User Cockpit of the CG offline mobile app. For more information, check out Model and Expose a Salesforce Object on Consumer Goods Cloud Offline Mobile App.
Next, Fatima creates a UIPluginV2 contract in the UI Plugins folder in her Modeler workspace.
- To create a UIPluginV2 contract, clone the template file $workspace/contractSnippets/UI_Plugins/#Name#UiPluginV2.uipluginv2.xml.
- Name the cloned contract as
MyCardDisplayReportUiPluginV2.uipluginv2.xmland save the contract at $workspace/src/UI Plugins.
- In MyCardDisplayReportUiPluginV2.uipluginv2.xml file, set the name attribute to MyCardDisplayReportUiPluginV2.
- Save your changes.
- Build your contracts to check for validation errors. Run
sf mdl build.
Fatima has successfully created the UIPluginV2 contract. For more information, see Create a UIPluginV2.
Onward and Upward
In this unit, Fatima created a UIPluginV2 contract that helps to show reports and charts on the CG offline mobile app.
In the next unit, follow Fatima as she implements UIPluginV2 in CG Modeler, sets up business logic methods to prepare the report data, and creates a cockpit card on the CG offline mobile app.