Share via

PowerApps component framework: Getting started

  • Article

Introduction

Power app component framework is a new way of enhancing user interface for Model driven apps & Canvas apps(Public Preview). It gives developers the ability to customize the user interface of PowerApps which is not available out of the box.

Comparison with HTML Web resource

Power app component framework provides the user with a rich and seamless experience, since it runs in the same context of a  field or data sets, unlike HTML web resource which typically runs in an Iframe. It also allows us to include external JavaScript framework like React, Angular etc which is now a more preferred framework for web development.
PowerApps Component framework (PCF) automatically handles its life cycle and can be packaged to a solution for moving it to different environments.

PCF control renders as part of the context unlike Web Resources which makes it easy to access contextual data and metadata including WebAPI and are re usable as they target specific field types and datasets. 

Objective

The aim of this article is to show how to get started building PCF, by creating a sample code component that will demonstrate how to replace a field of an entity form and render a button in its place. This button will allow the user to be redirected to a web URL which is defined in the PCF property.

Getting Started

In order to get started with creating PCF, follow the prerequisite section below.

Prerequisite - Install Microsoft PowerApps CLI

PowerApps CLI command helps to initialize, package & deploy the solution into Common data services (CDS).

To get Microsoft PowerApps CLI, do the following:

To get the latest capabilities, update the PowerApps CLI tooling to the latest version using this command:

pac install latest

Creating new component project

Run the below command to create a folder & then go into the new folder. 

 

      md PCFOfficeUIReactButton  
   
      cd PCFOfficeUIReactButton

Create a new component project by running the below command. Basically, pass a namespace and name of the component as the parameter to initialize the component.

pac pcf init --namespace PCFNamespace --name PCFOfficeUIReactButton --template field

Run the below command for installing all the necessary dependencies for the project.

npm install

Run the below command to open the project in visual studio code

Code .

Install Office UI Fabric React

Since we are making use of React component of Office UI fabric, we will include Office UI Fabric react for our project.
Install Office UI Fabric React by entering the below command. 

npm install office-ui-fabric-react

Inside the project, we will primarily edit or focus ControlManifest.Input.xml & Index.ts file.

Inside  ControlManifest.Input.xml, we are including two properties that is required for our component. These need to be mentioned inside the control. Here we can also specify any custom styling that we may have inside the resources tag.

Overall XML structure should look like the one displayed below.

Here, we are including two properties required for the PCF which are buttonValue and buttonLink

<?xml version="1.0" encoding="utf-8" ?>
<manifest>
  <control namespace="PCFNamespace" constructor="PCFOfficeUIReactButton" version="0.0.1" display-name-key="PCFOfficeUIReactButton" description-key="PCFOfficeUIReactButton description" control-type="standard">
    <property name="buttonValue" display-name-key="buttonValue" description-key="Button_value" of-type="SingleLine.Text" usage="bound" required="true"/>
    <property name="buttonLink" display-name-key="buttonLink"  description-key="Button_Link" of-type="SingleLine.Text" usage="input" required="true"/>
    <resources>
      <code path="index.ts" order="1"/>
    </resources>
  </control>
</manifest>

Create a new file "PCFButton.tsx" in parallel to index.ts file and include the below code. 

import * as React from 'react';
import { PrimaryButton } from 'office-ui-fabric-react';
 
export interface IPCFButtonProps {
  // These are set based on the toggles shown above the examples (not needed in real code)
  buttonValue: string;
  buttonLink: string;
}
 
export const ButtonAnchor: React.FunctionComponent<IPCFButtonProps> = props => {
  return (
    <PrimaryButton href={props.buttonLink} target="_blank">
      {props.buttonValue}
    </PrimaryButton>
  );
};

Explanation

Here, we are specifying the React component PCFButton which is required in our project. This is a react functional component which returns an Office UI Fabric React Button with a set of properties which is passed to it.

↑ Return to Top

Initialize React Element in Power App Component Framework

Include the below code in index.ts file. Completed explanation of the code mentioned below.

import { IInputs, IOutputs } from "./generated/ManifestTypes";
import * as React from 'react';
import * as ReactDOM from 'react-dom';
import { ButtonAnchor, IPCFButtonProps } from './PCFButton';
 
export class PCFOfficeUIReactButton implements ComponentFramework.StandardControl<IInputs, IOutputs> {
    private theContainer: HTMLDivElement;
    private props: IPCFButtonProps = {
        buttonValue: "",
        buttonLink: ""
    }
 
    /**
     * Empty constructor.
     */
    constructor() {
 
    }
 
    /**
     * Used to initialize the control instance. Controls can kick off remote server calls and other initialization actions here.
     * Data-set values are not initialized here, use updateView.
     * @param context The entire property bag available to control via Context Object; It contains values as set up by the customizer mapped to property names defined in the manifest, as well as utility functions.
     * @param notifyOutputChanged A callback method to alert the framework that the control has new outputs ready to be retrieved asynchronously.
     * @param state A piece of data that persists in one session for a single user. Can be set at any point in a controls life cycle by calling 'setControlState' in the Mode interface.
     * @param container If a control is marked control-type='standard', it will receive an empty div element within which it can render its content.
     */
    public init(context: ComponentFramework.Context<IInputs>, notifyOutputChanged: () => void, state: ComponentFramework.Dictionary, container: HTMLDivElement) {
        // Add control initialization code
         
        this.theContainer = container;
        
    }
 
 
    /**
     * Called when any value in the property bag has changed. This includes field values, data-sets, global values such as container height and width, offline status, control metadata values such as label, visible, etc.
     * @param context The entire property bag available to control via Context Object; It contains values as set up by the customizer mapped to names defined in the manifest, as well as utility functions
     */
    public updateView(context: ComponentFramework.Context<IInputs>): void {
        // Add code to update control view
        this.props.buttonValue = context.parameters.buttonValue.raw!;
        this.props.buttonLink = context.parameters.buttonLink.raw!;
        ReactDOM.render(
            React.createElement(
                ButtonAnchor,
                this.props
            ),
            this.theContainer
        );
    }
 
    /** 
     * It is called by the framework prior to a control receiving new data. 
     * @returns an object based on nomenclature defined in manifest, expecting object[s] for property marked as “bound” or “output”
     */
    public getOutputs(): IOutputs {
        return {};
    }
 
    /** 
     * Called when the control is to be removed from the DOM tree. Controls should use this call for cleanup.
     * i.e. cancelling any pending remote calls, removing listeners, etc.
     */
    public destroy(): void {
        // Add code to cleanup control if necessary
        ReactDOM.unmountComponentAtNode(this.theContainer);
    }
}

Explanation

Here, we are including two props buttonValue & buttonLink which are required for the react component PCFButton mentioned earlier. So, we have the lifecycle of PCF component already defined in index.ts file, i.e. init, updateView, getOutputs & destroy.

On updateView, we are creating the react element PCFButton and passing the required props for the component.

↑ Return to Top

Debug PCF Component using Test harness

Run the below command which will host the code component locally and help us to visualize the component.

npm start watch

Here we can simultaneously do changes in our code and see the changes detected by the test harness.

Pass the value & link in the property of the local web app & click on the button to get re-directed.

Package a code component

Create a folder with a name Solutions anywhere in the directory and create a new folder under the solutions folder.

Run the below command to create a solution project which will be used to zip our solution. Enter the publisher name and published prefix as this is required for each solution.

pac solution init --publisher-name <enter your publisher name> --publisher-prefix <enter your publisher prefix>

Make note of the publisher prefix which will be required to push the solution to Common Data Service(CDS) using PowerApps CLI
Open Visual Studio Developer command prompt and run the below command to build the solution package.

msbuild /t:build /restore

Run the below command to build the solution package for production

msbuild /p:configuration=Release

Now, we can manually import the solution created in bin directory of solution project to common data services.

↑ Return to Top

Deploying code components

We are creating an authentication profile which is required for deploying or importing the solution directly to CDS using PowerApps CLI

Create an Authentication Profile

Run the below command to create an authentication profile by providing the Organization URL as the parameter.

pac auth create --url <your Common Data Service org’s url>

Run the below command to push the solution into CDS. Include the publisher prefix we created in Package a code component section.

pac pcf push --publisher-prefix <your publisher prefix>

Add PowerApps component framework to Model Driven Apps

Since this is a field related component, Edit form of the entity where the component needs to be included in form designer. Here, we are considering a custom entity where there are text fields. Make sure the form designer is opened in classic view.

  1. Open the field property and go to Controls section.
  2. Click on Add Control and select PCFOfficeUIReactButton.

 

  1. Select Web, Phone & Tablet. Also, enter the required properties for the Button.

 

  1. Save & Publish the changes done.

Once implemented successfully, a button would render in place of text-field, Upon click of which redirection to the specified location would occur.

↑ Return to Top

Glimpse of the PCF Control

Download this solution

Download this solution from Github

↑ Return to Top

Conclusion

Thus, we saw how to create & build PowerApps component framework for Model driven apps.

↑ Return to Top

See Also