Configure a Lightning Web Component for Lightning App Builder

You have created a Lightning Web Component and planning to use it in Lightning Experience. There are a few steps to take before you can use your custom Lightning web components to create a Lightning page in Lightning App Builder.

The Lightning App Builder is a point-and-click tool that makes it easy to create custom pages for the Salesforce mobile app and Lightning Experience, giving your users what they need all in one place. The Lightning App Builder is also a one-stop shop for configuring Lightning apps.

1. Deploy My Domain in Your Org

To add Lightning web components to a Lightning page in Lightning App Builder, deploy My Domain in your Org else you can not use it in Lightning Experience.

For information about deploying My Domain, see Salesforce Help.

2. Define Component Metadata in the Configuration File

Each Lightning web component folder must include a configuration file named <component>.js-meta.xml. The configuration file defines the metadata values for the component, including the design configuration for the Lightning App Builder and Community Builder.
The below image shows the Lightning Web Component named imageGallery has three component. A Lightning web component that renders UI must include an HTML file, a JavaScript file, and a metadata configuration file. The files must use the same name so the framework can autowire them.
1. imageGallery.html
2. imageGallery.js
3. imageGallery.js-meta.xml
The code displayed in the image is the simplest configuration file.
meta-js
You can also have 2 other components as part of this imageGallery Lightning Web Component. They are:-
4. imageGallery.css
5. imageGallery.svg

What is the significance of  <component>.js-meta.xml in Lightning Web COmponent?

The configuration file defines the metadata values for the component, including the design configuration for Lightning App Builder and Community Builder.

The configuration file follows the naming convention <component>.js-meta.xml, such as myComponent.js-meta.xml.

Include the configuration file in your component’s project folder, and push it to your org along with the other component files.

What happens when you remove the configuration file from component’s project folder and tries to push it to your org?

If you don’t include a configuration file for your component, you get an error similar to the following when you push your changes.

Cannot find Lightning Component Bundle <component_name>

Configuration File Tags

apiVersion:- A double value that binds the component to a Salesforce API version. To check the current version, take help of this knowledge article.

description:-A short description of the component, usually a single sentence. Appears in list views, like the list of Lightning Components in Setup, and as a tooltip in the Lightning App Builder and in Community Builder.

description

When you hover your mouse to the custom component deployed to the org, you can see the description with the label.

isExposed:-A Boolean value. Exposes the component in all orgs, and in Lightning App Builder and Community Builder. To make a component usable in a managed package, set isExposed to true. To make a component usable in Lightning App Builder and Community Builder, set isExposed to true.

masterLabel:-The title of the component. Appears in list views, like the list of Lightning Components in Setup, and in the Lightning App Builder and in Community Builder.

Note:- Do not get confused with the Lightning Web Component name to be always as the label. If you do not use masterLabel tag in the configuration file, Your component name will default as the label of the component.

Do you remember using interface in Aura Components which enables to use of Aura Component with App page, Record Page, Home page or Community Builder?

App.PNG
Migrate Interfaces:- The above image shows the interface counterpart in Lightning Web Component

So, the same capability we have in Lightning Web Component, see how…

targets:-Specifies which types of Lightning page the component can be added to. If you want your component to appear in the Lightning App Builder or in Community Builder, specify at least one Lightning page type. Supports the target subtag.

<targets>
<target>lightning__AppPage</target>
</targets>

if you have above lines of code in your configuration file, Your component is available to be used only as App in Lightning App Builder. If you want to use it on the Record page or Home page, it will not be available. To know what tags need to be used in the configuration file so that you can use your Lightning Web Component at different places in Lightning Experience, refer below table:-
VALUE DESCRIPTION
lightning__AppPage Enables a component to be used on a Lightning page of type App Page.
lightning__HomePage Enables a component to be used on a Lightning Experience Home page.
lightning__RecordPage Enables a component to be used on a Lightning record page.
lightningCommunity__Page Enables a component to be used on a Lightning community page in Community Builder.
lightningCommunity__Default Used together with lightningCommunity__Page. Enables a component that includes configurable properties to be used on a Lightning community page in Community Builder. When the component is selected on the page, the properties appear.

Ok, Do you remember using design resource in Aura Component?

Well, let’s remember it. Design resource was used to control which attributes are exposed to builder tools like the Lightning App Builder, Community Builder, or Flow Builder. A design resource lives in the same folder as your .cmp resource and describes the design-time behavior of the Aura component—information that visual tools need to display the component in a page or app.

<design:component label="Hello World">
    <design:attribute name="subject" label="Subject" description="Name of the person you want to greet" />
    <design:attribute name="greeting" label="Greeting" />
</design:component>
Are you wondering how to achieve the same in Lightning Web Component? Well, <component>.js-meta.xml file allows you to achieve the same.
Have a look on below piece of code:-
<targetConfigs>
      <targetConfig targets="lightning__RecordPage">
          <property name="prop1" type="String" />
          <objects>
              <object>Account</object>
              <object>Opportunity</object>
              <object>Warehouse__c</object>
          </objects>
      </targetConfig>
      <targetConfig targets="lightning__AppPage, lightning_HomePage">
          <property name="prop2" type="Boolean" />
      </targetConfig>
  </targetConfigs>
what does targetConfigs tell to Lightning Experience?
Configure the component for different page types and define component properties. For example, a component could have different properties on a record home page than on the Salesforce Home page or on an app page.
targetConfig:- It is subtag of targetConfigs and used for different page type configuration. For Example:-
  • <targetConfig targets=”lightning__RecordPage”>
  • <targetConfig targets=”lightning__AppPage, lightning_HomePage”>

targets:-The targets attribute value that you specify must match one or more of the page types that you listed under <targets> for the component. It Supports the property and objects subtags.

property:-Specifies a public property of a component that can be set in Lightning App Builder or Community Builder. The component author defines the property in the component’s JavaScript class using the @apidecorator.

property name=”prop2″ type=”Boolean” />

Property tag supports different attributes such as datasource, default, description, label, max, min etc. Read more about them here:- Property attributes

objects:-A set of one or more objects the component is supported for. This tag set works only inside a parent targetConfig that’s configured for lightning__RecordPage. Specify the objects tag set only once inside a targetConfig set. Supports the object subtag.

object:-Defines which objects the component is supported for. Use one object tag for each supported object. You can’t use ‘*’ to denote all objects.

Overall, Your <component>.js-meta.xml file will look like this:-

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>45.0</apiVersion>
  <isExposed>true</isExposed>
  <masterLabel>Best Component Ever</masterLabel>
  <description>This is a demo component.</description>
  <targets>
      <target>lightning__RecordPage</target>
      <target>lightning__AppPage</target>
      <target>lightning__HomePage</target>
  </targets>
  <targetConfigs>

      <targetConfig targets="lightning__RecordPage">

          <property name="prop1" type="String" />
          <objects>
              <object>Account</object>
              <object>Opportunity</object>
              <object>Warehouse__c</object>
          </objects>
      </targetConfig>

      <targetConfig targets="lightning__AppPage, lightning_HomePage">

          <property name="prop2" type="Boolean" />
      </targetConfig>

  </targetConfigs>
</LightningComponentBundle>

Note:- Do not forget to read the Tips for Working with Lightning App Builder

 

Leave a Reply