pcf-code-components

# Code Components

Code components are a type of solution component that can be included in a solution file and imported into different environments. They can be added to both model-driven and canvas apps.

## Three Core Elements

Code components consist of three elements:

1. **Manifest**
2. **Component implementation**
3. **Resources**

> **Note**: The definition and implementation of code components using Power Apps component framework is the same for both model-driven and canvas apps. The only difference is the configuration part.

## Manifest

The manifest is the `ControlManifest.Input.xml` 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 `dataset`
- Any properties that can be configured in the application when the component is added
- A list of resource files that the component needs

### Manifest Purpose

When a user configures a code component, the data in the manifest file filters the available components so that only valid components for the context are available for configuration. The properties defined in the manifest file are rendered as configuration columns so that users can specify values. These property values are then available to the component at runtime.

More information: [Manifest schema reference](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/)

## Component Implementation

Code components are implemented using TypeScript. Each code component must include an object that implements the methods described in the code component interface. The [Power Platform CLI](https://learn.microsoft.com/en-us/power-platform/developer/cli/introduction) auto-generates an `index.ts` file with stubbed implementations using the `pac pcf init` command.

### Required Methods

The component object implements these lifecycle methods:

- **init** (Required) - Called when the page loads
- **updateView** (Required) - Called when app data changes
- **getOutputs** (Optional) - Returns values when user changes data
- **destroy** (Required) - Called when the page closes

### Component Lifecycle

#### Page Load

When the page loads, the application creates an object using data from the manifest:

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

Example:
```typescript
var controlObj = new SampleNameSpace.LinearInputComponent();
```

The page then initializes the component:

```typescript
controlObj.init(context, notifyOutputChanged, state, container);
```

**Init Parameters:**

| Parameter | Description |
|-----------|-------------|
| `context` | Contains all information about how the component is configured and all parameters. Access input properties via `context.parameters.<property name from manifest>`. Includes Power Apps component framework APIs. |
| `notifyOutputChanged` | Alerts the framework whenever the component has new outputs ready to be retrieved asynchronously. |
| `state` | Contains component data from the previous page load if explicitly stored using `setControlState` method. |
| `container` | An HTML div element to which developers can append HTML elements for the UI. |

#### User Changes Data

When a user interacts with your component to change data, call the `notifyOutputChanged` method passed in the `init` method. The platform responds by calling the `getOutputs` method, which returns values with the changes made by the user. For a `field` component, this would typically be the new value.

#### App Changes Data

If the platform changes the data, it calls 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

When a user navigates away from the page, the code component loses scope and all memory allocated for objects is cleared. However, some methods (like event handlers) may stay and consume memory based on browser implementation.

**Best Practices:**
- Implement the `setControlState` method to store information for the next time within the same session
- Implement the `destroy` method to remove cleanup code such as event handlers when the page closes

## Resources

The resource node in the manifest file refers to the resources that the component requires to implement its visualization. Each code component must have a resource file to construct its visualization. The `index.ts` file generated by the tooling is a `code` resource. There must be at least 1 code resource.

### Additional Resources

You can define additional resource files in the manifest:

- CSS files
- Image web resources
- Resx web resources for localization

More information: [resources element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/resources)

## Related Resources

- [Create and build a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/create-custom-controls-using-pcf)
- [Learn how to package and distribute extensions using solutions](https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm)