What are code components

Code components are a type of solution components, which means they can be included in a solution file and installed in different environments. More information: Package and distribute extensions using solutions.

You add code components by including them in a solution and then import it into Common Data Service. Once the components are in Common Data Service, system administrators and system customizers can configure fields, subgrids, views, and dashboard subgrids to use in place of default components. You can also add these code components in canvas apps.

Code components consist of three elements:

  1. Manifest
  2. Component implementation library
  3. Resources

Manifest

Manifest is the metadata file that defines a component. It is an XML document that describes:

  • The name of the component.
  • The kind of data that can be configured, either a field or a data-set.
  • Any properties that can be configured in the application when the component is added.
  • A list of resource files that the component needs.
  • The name of the TypeScript function in the component implementation library that returns an object that applies the required component interface.

When a user configures a code component, the data in the manifest file filters out the available components so that only valid components for the context are available for configuration. The properties defined in the manifest file for a component are rendered as configuration fields so that the user configuring the component can specify the values. These property values are then available to the component at runtime. More information: Manifest schema reference

Component implementation library

Implementing the component library is one of the key steps when you are developing code components using PowerApps component framework. Developers can implement a component library using TypeScript. Each code component must have a library that includes the definition of a function, which returns an object that implements the methods described in the code component interface.

The object implements the following methods:

These methods control the lifecycle of the code component.

Page load

When the page loads, the application requires an object to work. Using the data from the manifest file, the code gets the object by calling:

var obj =  new <"namespace on manifest">.<"constructor on manifest">();

If the namespace and constructor values from the manifest are SampleNameSpace and LinearInputComponent respectively, the code to instantiate the object would be this:

var controlObj = new SampleNameSpace.LinearInputComponent();

When the page is ready, it initializes the component by calling the init method with a set of parameters.

controlObj.init(context,notifyOutputChanged,state,container);
Parameter Description
context Contains all the information about how the component is configured and all the parameters that can be used within the component along with the PowerApps component framework APIs. For example, the context.parameters.<"property name from manifest"> can be used to access the input property.
notifyOutputChanged Alerts the framework whenever the code component has new outputs ready to be retrieved asynchronously.
state Contains component data from the previous page load in the current session if the component explicitly stored it earlier using the setControlState method.
container An HTML div element to which developers and app makers can append the HTML elements for the UI that defines the component.

User changes data

When the page loads, the component displays the data until the user interacts with the component to change the data. When this occurs, you must call the method passed in as notifyOutputChanged parameter in the init method. When you use this method, the platform then responds by calling the getOutputs method. The getOutputs method returns values that have the changes made by the user. For a field component, this would typically be the new value for the component.

App changes data

If the platform changes the data, it calls out the updateView method of the component and passes the new context object as a parameter. This method should be implemented to update the values displayed in the component.

Page close

Whenever a user steps away from the page, the code component loses the scope and all the memory allocated in that page for the objects is cleared. However, some methods, based on the browser implementation mechanism, might stay and consume memory. Typically, these are event handlers. If the user wants to store this information, they should implement the setControlState method so that the information is given next time within the same session.

Developers should implement the destroy method, which is called when the page closes, to remove any cleanup code such as event handlers.

Resources

Each code component should have a resource file to construct its visualization. You can define a resource file in the manifest. The resource node in the manifest file refers to the resources that the component requires to implement its visualization. More information: resources element

Create and build a code component