mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-20 02:15:12 +00:00
Add Power Apps Component Framework (PCF) Development Collection (#428)
* Add PCF Development collection with 17 instruction files * Update instructions/pcf-overview.instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Fix description field formatting - wrap values in single quotes --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Troy Simeon Taylor
committed by
GitHub
GitHub
parent
13dc6a4132
commit
cf0f01d981
246
instructions/pcf-alm.instructions.md
Normal file
246
instructions/pcf-alm.instructions.md
Normal file
@@ -0,0 +1,246 @@
|
||||
---
|
||||
description: 'Application lifecycle management (ALM) for PCF code components'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj,sln}'
|
||||
---
|
||||
|
||||
# Code Components Application Lifecycle Management (ALM)
|
||||
|
||||
ALM is a term used to describe the lifecycle management of software applications, which includes development, maintenance, and governance. More information: [Application lifecycle management (ALM) with Microsoft Power Platform](https://learn.microsoft.com/en-us/power-platform/alm/overview-alm).
|
||||
|
||||
This article describes considerations and strategies for working with specific aspects of lifecycle management from the perspective of code components in Microsoft Dataverse:
|
||||
|
||||
1. Development and debugging ALM considerations
|
||||
2. Code component solution strategies
|
||||
3. Versioning and deploying updates
|
||||
4. Canvas apps ALM considerations
|
||||
|
||||
## Development and Debugging ALM Considerations
|
||||
|
||||
When developing code components, you would follow the steps below:
|
||||
|
||||
1. Create code component project (`pcfproj`) from a template using `pac pcf init`. More information: [Create and build a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/create-custom-controls-using-pcf).
|
||||
2. Implement code component logic. More information: [Component implementation](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/custom-controls-overview#component-implementation).
|
||||
3. Debug the code component using the local test harness. More information: [Debug code components](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/debugging-custom-controls).
|
||||
4. Create a solution project (`cdsproj`) and add the code component project as a reference. More information: [Package a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/import-custom-controls).
|
||||
5. Build the code component in release mode for distribution and deployment.
|
||||
|
||||
### Two Deployment Methods to Dataverse
|
||||
|
||||
When your code component is ready for testing inside a model-driven app, canvas app, or portal:
|
||||
|
||||
1. **`pac pcf push`**: This deploys a single code component at a time to a solution specified by the `--solution-unique-name` parameter, or a temporary PowerAppsTools solution when no solution is specified.
|
||||
|
||||
2. **Using `pac solution init` and `msbuild`**: Build a `cdsproj` solution project that has references to one or more code components. Each code component is added to the `cdsproj` using `pac solution add-reference`. A solution project can contain references to multiple code components, whereas code component projects may only contain a single code component.
|
||||
|
||||
The following diagram shows the one-to-many relationship between `cdsproj` and `pcfproj` projects:
|
||||
|
||||
|
||||
|
||||
More information: [Package a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/import-custom-controls#package-a-code-component).
|
||||
|
||||
## Building pcfproj Code Component Projects
|
||||
|
||||
When building `pcfproj` projects, the generated JavaScript depends on the command used to build and the `PcfBuildMode` in the `pcfproj` file.
|
||||
|
||||
You don't normally deploy a code component into Microsoft Dataverse that has been built in development mode since it's often too large to import and may result in slower runtime performance. More information: [Debugging after deploying into Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/debugging-custom-controls#debugging-after-deploying-into-microsoft-dataverse).
|
||||
|
||||
For `pac pcf push` to result in a release build, the `PcfBuildMode` is set inside the `pcfproj` by adding a new element under the `OutputPath` element:
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<Name>my-control</Name>
|
||||
<ProjectGuid>6aaf0d27-ec8b-471e-9ed4-7b3bbc35bbab</ProjectGuid>
|
||||
<OutputPath>$(MSBuildThisFileDirectory)out\controls</OutputPath>
|
||||
<PcfBuildMode>production</PcfBuildMode>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Build Commands
|
||||
|
||||
| Command | Default Behavior | With PcfBuildMode=production |
|
||||
|---------|-----------------|------------------------------|
|
||||
| npm start watch | Always development | |
|
||||
| pac pcf push | Development build | Release build |
|
||||
| npm run build | Development build | `npm run build -- --buildMode production` |
|
||||
|
||||
More information: [Package a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/import-custom-controls#package-a-code-component).
|
||||
|
||||
## Building .cdsproj Solution Projects
|
||||
|
||||
When building a solution project (`.cdsproj`), you have the option to generate the output as a managed or unmanaged solution. Managed solutions are used to deploy to any environment that isn't a development environment for that solution. This includes test, UAT, SIT, and production environments. More information: [Managed and unmanaged solutions](https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm#managed-and-unmanaged-solutions).
|
||||
|
||||
The `SolutionPackagerType` is included in the `.cdsproj` file created by `pac solution init`, but initially commented out. Uncomment the section and set to Managed, Unmanaged, or Both.
|
||||
|
||||
```xml
|
||||
<!-- Solution Packager overrides, un-comment to use: SolutionPackagerType (Managed, Unmanaged, Both) -->
|
||||
<PropertyGroup>
|
||||
<SolutionPackageType>Managed</SolutionPackageType>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Build Configuration Results
|
||||
|
||||
| Command | SolutionPackageType | Result |
|
||||
|---------|-------------------|---------|
|
||||
| msbuild | Managed | Development build inside Managed Solution |
|
||||
| msbuild /p:configuration=Release | Managed | Release build inside Managed Solution |
|
||||
| msbuild | Unmanaged | Development build inside Unmanaged Solution |
|
||||
| msbuild /p:configuration=Release | Unmanaged | Release build inside Unmanaged Solution |
|
||||
|
||||
More information: [Package a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/import-custom-controls#package-a-code-component).
|
||||
|
||||
## Source Code Control with Code Components
|
||||
|
||||
When developing code components, it's recommended that you use a source code control provider such as Azure DevOps or GitHub. When committing changes using git source control, the `.gitignore` file provided by the `pac pcf init` template will ensure that some files are not added to the source control because they're either restored by `npm` or are generated as part of the build process:
|
||||
|
||||
```
|
||||
# dependencies
|
||||
/node_modules
|
||||
|
||||
# generated directory
|
||||
**/generated
|
||||
|
||||
# output directory
|
||||
/out
|
||||
|
||||
# msbuild output directories
|
||||
/bin
|
||||
/obj
|
||||
```
|
||||
|
||||
Since the `/out` folder is excluded, the resulting `bundle.js` file (and related resources) built will not be added to the source control. When your code components are built manually or as part of an automated build pipeline, the `bundle.js` would be built using the latest code to ensure that all changes are included.
|
||||
|
||||
Additionally, when a solution is built, any association solution zip files would not be committed to the source control. Instead, the output would be published as binary release artifacts.
|
||||
|
||||
## Using SolutionPackager with Code Components
|
||||
|
||||
In addition to source controlling the `pcfproj` and `cdsproj`, [SolutionPackager](https://learn.microsoft.com/en-us/power-platform/alm/solution-packager-tool) may be used to incrementally unpack a solution into its respective parts as a series of XML files that can be committed into source control. This has the advantage of creating a complete picture of your metadata in the human-readable format so you can track changes using pull requests or similar.
|
||||
|
||||
> **Note**: At this time, SolutionPackager differs from using `pac solution clone` in that it can be used incrementally to export changes from a Dataverse solution.
|
||||
|
||||
### Example Solution Structure
|
||||
|
||||
Once a solution that contains a code component is unpacked using `SolutionPackager /action: Extract`, it will look similar to:
|
||||
|
||||
```
|
||||
.
|
||||
├── Controls
|
||||
│ └── prefix_namespace.ControlName
|
||||
│ ├── bundle.js *
|
||||
│ └── css
|
||||
│ └── ControlName.css *
|
||||
│ ├── ControlManifest.xml *
|
||||
│ └── ControlManifest.xml.data.xml
|
||||
├── Entities
|
||||
│ └── Contact
|
||||
│ ├── FormXml
|
||||
│ │ └── main
|
||||
│ │ └── {3d60f361-84c5-eb11-bacc-000d3a9d0f1d}.xml
|
||||
│ ├── Entity.xml
|
||||
│ └── RibbonDiff.xml
|
||||
└── Other
|
||||
├── Customizations.xml
|
||||
└── Solution.xml
|
||||
```
|
||||
|
||||
Under the `Controls` folder, you can see there are subfolders for each code component included in the solution. When committing this folder structure to the source control, you would exclude the files marked with an asterisk (*) above, because they will be output when the `pcfproj` project is built for the corresponding component.
|
||||
|
||||
The only files that are required are the `*.data.xml` files since they contain metadata that describes the resources required by the packaging process.
|
||||
|
||||
More information: [SolutionPackager command-line arguments](https://learn.microsoft.com/en-us/power-platform/alm/solution-packager-tool#solutionpackager-command-line-arguments).
|
||||
|
||||
## Code Component Solution Strategies
|
||||
|
||||
Code components are deployed to downstream environments using Dataverse solutions. There are two strategies for deploying code components inside solutions:
|
||||
|
||||
### 1. Segmented Solutions
|
||||
|
||||
A solution project is created using `pac solution init` and then using `pac solution add-reference` to add one or more code components. This solution can then be exported and imported into downstream environments and other segmented solutions will take a dependency on the code component solution such that it must be deployed into that environment first.
|
||||
|
||||
**Reasons for adopting segmented solution approach:**
|
||||
|
||||
1. **Versioning lifecycle** - You want to develop, deploy, and version-control your code components on a separate lifecycle to the other parts of your solution. This is common in 'fusion team' scenarios where code components built by developers are being consumed by app makers.
|
||||
|
||||
2. **Shared use** - You want to share your code components between multiple environments and therefore don't want to couple your code components with any other solution components. This could be if you're an ISV or developing a code component for use by different parts of your organization.
|
||||
|
||||
### 2. Single Solution
|
||||
|
||||
A single solution is created inside a Dataverse environment and then code components are added along with other solution components (such as tables, model-driven apps, or canvas apps) that in turn reference those code components. This solution can be exported and imported into downstream environments without any inter-solution dependencies.
|
||||
|
||||
### Solution Lifecycle Overview
|
||||
|
||||
|
||||
|
||||
More information: [Package and distribute extensions using solutions](https://learn.microsoft.com/en-us/powerapps/developer/data-platform/introduction-solutions).
|
||||
|
||||
## Code Components and Automated Build Pipelines
|
||||
|
||||
In addition to manually building and deploying your code component solutions, you can also build and package your code components using automated build pipelines.
|
||||
|
||||
- If you're using Azure DevOps, you can use the [Microsoft Power Platform Build Tool for Azure DevOps](https://learn.microsoft.com/en-us/power-platform/alm/devops-build-tools).
|
||||
- If you're using GitHub, you can use the [Power Platform GitHub Actions](https://learn.microsoft.com/en-us/power-platform/alm/devops-github-actions).
|
||||
|
||||
### Advantages of Automated Build Pipelines
|
||||
|
||||
- **Time-efficient** - Removing the manual tasks makes building and packaging quicker
|
||||
- **Repeatable** - Performed the same every time, not dependent on the team member
|
||||
- **Versioning consistency** - Automatic versioning relative to previous versions
|
||||
- **Maintainable** - Everything needed to build is contained in source control
|
||||
|
||||
## Versioning and Deploying Updates
|
||||
|
||||
When deploying and updating your code components, it's important to have a consistent versioning strategy. A common versioning strategy is [semantic versioning](https://semver.org/), which has the format: `MAJOR.MINOR.PATCH`.
|
||||
|
||||
### Incrementing the PATCH Version
|
||||
|
||||
The `ControlManifest.Input.xml` stores the code component version in the control element:
|
||||
|
||||
```xml
|
||||
<control namespace="..." constructor="..." version="1.0.0" display-name-key="..." description-key="..." control-type="...">
|
||||
```
|
||||
|
||||
When deploying an update to a code component, the version in the `ControlManifest.Input.xml` must at minimum have its PATCH (the last part of the version) incremented for the change to be detected.
|
||||
|
||||
**Commands to update version:**
|
||||
|
||||
```bash
|
||||
# Advance the PATCH version by one
|
||||
pac pcf version --strategy manifest
|
||||
|
||||
# Specify an exact PATCH value (e.g., in automated build pipeline)
|
||||
pac pcf version --patchversion <PATCH VERSION>
|
||||
```
|
||||
|
||||
### When to Increment the MAJOR and MINOR Version
|
||||
|
||||
It's recommended that the MAJOR and MINOR version of the code component's version are kept in sync with the Dataverse solution that is distributed.
|
||||
|
||||
A [Dataverse solution has four parts](https://learn.microsoft.com/en-us/powerapps/maker/data-platform/update-solutions#understanding-version-numbers-for-updates): `MAJOR.MINOR.BUILD.REVISION`.
|
||||
|
||||
| Code Component | Dataverse Solution | Notes |
|
||||
|----------------|-------------------|--------|
|
||||
| MAJOR | MAJOR | Set using Pipeline Variable or last committed value |
|
||||
| MINOR | MINOR | Set using Pipeline Variable or last committed value |
|
||||
| PATCH | BUILD | $(Build.BuildId) |
|
||||
| --- | REVISION | $(Rev:r) |
|
||||
|
||||
## Canvas Apps ALM Considerations
|
||||
|
||||
Consuming code components in canvas apps is different from doing so in model-driven apps. Code components must be explicitly added to the app by selecting **Get more components** on the Insert panel. Once the code component is added to the canvas app, it's included as the content inside the app definition.
|
||||
|
||||
To update to a new version of the code component after it's deployed (and the control version incremented), the app maker must first open the app in Power Apps Studio and select **Update** when prompted on the Update code components dialog. The app must then be saved and published for the new version to be used when the app is played by users.
|
||||
|
||||
|
||||
|
||||
If the app is not updated or **Skip** is used, the app continues to use the older version of the code component, even though it doesn't exist in the environment since it's been overwritten by the newer version.
|
||||
|
||||
Since the app contains a copy of the code component, it's therefore possible to have different versions of the code components running side by side in a single environment from inside different canvas apps. However, you cannot have different versions of a code component running side by side in the same app.
|
||||
|
||||
> **Note**: Although, at this time, you can import a canvas app without the matching code component being deployed to that environment, it's recommended that you always ensure apps are updated to use the latest version of the code components and that the same version is deployed to that environment first or as part of the same solution.
|
||||
|
||||
## Related Articles
|
||||
|
||||
- [Application lifecycle management (ALM) with Microsoft Power Platform](https://learn.microsoft.com/en-us/power-platform/alm/overview-alm)
|
||||
- [Power Apps component framework API reference](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/)
|
||||
- [Create your first component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript)
|
||||
- [Debug code components](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/debugging-custom-controls)
|
||||
162
instructions/pcf-api-reference.instructions.md
Normal file
162
instructions/pcf-api-reference.instructions.md
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
description: 'Complete PCF API reference with all interfaces and their availability in model-driven and canvas apps'
|
||||
applyTo: '**/*.{ts,tsx,js}'
|
||||
---
|
||||
|
||||
# Power Apps Component Framework API Reference
|
||||
|
||||
The Power Apps component framework provides a rich set of APIs that enable you to create powerful code components. This reference lists all available interfaces and their availability across different app types.
|
||||
|
||||
## API Availability
|
||||
|
||||
The following table shows all API interfaces available in the Power Apps component framework, along with their availability in model-driven apps and canvas apps.
|
||||
|
||||
| API | Model-driven apps | Canvas apps |
|
||||
|-----|------------------|-------------|
|
||||
| AttributeMetadata | Yes | No |
|
||||
| Client | Yes | Yes |
|
||||
| Column | Yes | Yes |
|
||||
| ConditionExpression | Yes | Yes |
|
||||
| Context | Yes | Yes |
|
||||
| DataSet | Yes | Yes |
|
||||
| Device | Yes | Yes |
|
||||
| Entity | Yes | Yes |
|
||||
| Events | Yes | Yes |
|
||||
| Factory | Yes | Yes |
|
||||
| Filtering | Yes | Yes |
|
||||
| Formatting | Yes | Yes |
|
||||
| ImageObject | Yes | Yes |
|
||||
| Linking | Yes | Yes |
|
||||
| Mode | Yes | Yes |
|
||||
| Navigation | Yes | Yes |
|
||||
| NumberFormattingInfo | Yes | Yes |
|
||||
| Paging | Yes | Yes |
|
||||
| Popup | Yes | Yes |
|
||||
| PopupService | Yes | Yes |
|
||||
| PropertyHelper | Yes | Yes |
|
||||
| Resources | Yes | Yes |
|
||||
| SortStatus | Yes | Yes |
|
||||
| StandardControl | Yes | Yes |
|
||||
| UserSettings | Yes | Yes |
|
||||
| Utility | Yes | Yes |
|
||||
| WebApi | Yes | Yes |
|
||||
|
||||
## Key API Namespaces
|
||||
|
||||
### Context APIs
|
||||
|
||||
The `Context` object provides access to all framework capabilities and is passed to your component's lifecycle methods. It contains:
|
||||
|
||||
- **Client**: Information about the client (form factor, network status)
|
||||
- **Device**: Device capabilities (camera, location, microphone)
|
||||
- **Factory**: Factory methods for creating framework objects
|
||||
- **Formatting**: Number and date formatting
|
||||
- **Mode**: Component mode and tracking
|
||||
- **Navigation**: Navigation methods
|
||||
- **Resources**: Access to resources (images, strings)
|
||||
- **UserSettings**: User settings (locale, number format, security roles)
|
||||
- **Utils**: Utility methods (getEntityMetadata, hasEntityPrivilege, lookupObjects)
|
||||
- **WebApi**: Dataverse Web API methods
|
||||
|
||||
### Data APIs
|
||||
|
||||
- **DataSet**: Work with tabular data
|
||||
- **Column**: Access column metadata and data
|
||||
- **Entity**: Access record data
|
||||
- **Filtering**: Define data filtering
|
||||
- **Linking**: Define relationships
|
||||
- **Paging**: Handle data pagination
|
||||
- **SortStatus**: Manage sorting
|
||||
|
||||
### UI APIs
|
||||
|
||||
- **Popup**: Create popup dialogs
|
||||
- **PopupService**: Manage popup lifecycle
|
||||
- **Mode**: Get component rendering mode
|
||||
|
||||
### Metadata APIs
|
||||
|
||||
- **AttributeMetadata**: Column metadata (model-driven only)
|
||||
- **PropertyHelper**: Property metadata helpers
|
||||
|
||||
### Standard Control
|
||||
|
||||
- **StandardControl**: Base interface for all code components with lifecycle methods:
|
||||
- `init()`: Initialize component
|
||||
- `updateView()`: Update component UI
|
||||
- `destroy()`: Cleanup resources
|
||||
- `getOutputs()`: Return output values
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
### Model-Driven vs Canvas Apps
|
||||
|
||||
Some APIs are only available in model-driven apps due to platform differences:
|
||||
|
||||
- **AttributeMetadata**: Model-driven only - provides detailed column metadata
|
||||
- Most other APIs are available in both platforms
|
||||
|
||||
### API Version Compatibility
|
||||
|
||||
- Always check the API availability for your target platform (model-driven or canvas)
|
||||
- Some APIs may have different behaviors across platforms
|
||||
- Test components in the target environment to ensure compatibility
|
||||
|
||||
### Common Patterns
|
||||
|
||||
1. **Accessing Context APIs**
|
||||
```typescript
|
||||
// In init or updateView
|
||||
const userLocale = context.userSettings.locale;
|
||||
const isOffline = context.client.isOffline();
|
||||
```
|
||||
|
||||
2. **Working with DataSet**
|
||||
```typescript
|
||||
// Access dataset records
|
||||
const records = context.parameters.dataset.records;
|
||||
|
||||
// Get sorted columns
|
||||
const sortedColumns = context.parameters.dataset.sorting;
|
||||
```
|
||||
|
||||
3. **Using WebApi**
|
||||
```typescript
|
||||
// Retrieve records
|
||||
context.webAPI.retrieveMultipleRecords("account", "?$select=name");
|
||||
|
||||
// Create record
|
||||
context.webAPI.createRecord("contact", data);
|
||||
```
|
||||
|
||||
4. **Device Capabilities**
|
||||
```typescript
|
||||
// Capture image
|
||||
context.device.captureImage();
|
||||
|
||||
// Get current position
|
||||
context.device.getCurrentPosition();
|
||||
```
|
||||
|
||||
5. **Formatting**
|
||||
```typescript
|
||||
// Format date
|
||||
context.formatting.formatDateLong(date);
|
||||
|
||||
// Format number
|
||||
context.formatting.formatDecimal(value);
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Type Safety**: Use TypeScript for type checking and IntelliSense
|
||||
2. **Null Checks**: Always check for null/undefined before accessing API objects
|
||||
3. **Error Handling**: Wrap API calls in try-catch blocks
|
||||
4. **Platform Detection**: Check `context.client.getFormFactor()` to adapt behavior
|
||||
5. **API Availability**: Verify API availability for your target platform before use
|
||||
6. **Performance**: Cache API results when appropriate to avoid repeated calls
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- For detailed documentation on each API, refer to the [Power Apps component framework API reference](https://learn.microsoft.com/power-apps/developer/component-framework/reference/)
|
||||
- Sample code for each API is available in the [PowerApps-Samples repository](https://github.com/microsoft/PowerApps-Samples/tree/master/component-framework)
|
||||
219
instructions/pcf-best-practices.instructions.md
Normal file
219
instructions/pcf-best-practices.instructions.md
Normal file
@@ -0,0 +1,219 @@
|
||||
---
|
||||
description: 'Best practices and guidance for developing PCF code components'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj,css,html}'
|
||||
---
|
||||
|
||||
# Best Practices and Guidance for Code Components
|
||||
|
||||
Developing, deploying, and maintaining code components needs a combination of knowledge across multiple areas. This article outlines established best practices and guidance for professionals developing code components.
|
||||
|
||||
## Power Apps Component Framework
|
||||
|
||||
### Avoid Deploying Development Builds to Dataverse
|
||||
|
||||
Code components can be built in [production or development mode](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/code-components-alm#building-pcfproj-code-component-projects). Avoid deploying development builds to Dataverse since they adversely affect the performance and can even get blocked from deployment due to their size. Even if you plan to deploy a release build later, it can be easy to forget to redeploy if you don't have an automated release pipeline. More information: [Debugging custom controls](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/debugging-custom-controls).
|
||||
|
||||
### Avoid Using Unsupported Framework Methods
|
||||
|
||||
These include using undocumented internal methods that exist on the `ComponentFramework.Context`. These methods might work but, because they're not supported, they might stop working in future versions. Use of control script that accesses host application HTML Document Object Model (DOM) isn't supported. Any parts of the host application DOM that are outside the code component boundary, are subject to change without notice.
|
||||
|
||||
### Use `init` Method to Request Network Required Resources
|
||||
|
||||
When the hosting context loads a code component, the `init` method is first called. Use this method to request any network resources such as metadata instead of waiting for the `updateView` method. If the `updateView` method is called before the requests return, your code component must handle this state and provide a visual loading indicator.
|
||||
|
||||
### Clean Up Resources Inside the `destroy` Method
|
||||
|
||||
The hosting context calls the `destroy` method when a code component is removed from the browser DOM. Use the `destroy` method to close any `WebSockets` and remove event handlers that are added outside of the container element. If you're using React, use `ReactDOM.unmountComponentAtNode` inside the `destroy` method. Cleaning up resources in this way prevents any performance issues caused by code components being loaded and unloaded within a given browser session.
|
||||
|
||||
### Avoid Unnecessary Calls to Refresh on a Dataset Property
|
||||
|
||||
If your code component is of type dataset, the bound dataset properties expose a `refresh` method that causes the hosting context to reload the data. Calling this method unnecessarily impacts the performance of your code component.
|
||||
|
||||
### Minimize Calls to `notifyOutputChanged`
|
||||
|
||||
In some circumstances, it's undesirable for updates to a UI control (such as keypresses or mouse move events) to each call `notifyOutputChanged`, as more calls would result in many more events propagating to the parent context than needed. Instead, consider using an event when a control loses focus, or when the user's touch or mouse event completes.
|
||||
|
||||
### Check API Availability
|
||||
|
||||
When developing code components for different hosts (model-driven apps, canvas apps, portals), always check the availability of the APIs you're using for support on those platforms. For example, `context.webAPI` isn't available in canvas apps. For individual API availability, see [Power Apps component framework API reference](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/).
|
||||
|
||||
### Manage Temporarily Null Property Values Passed to `updateView`
|
||||
|
||||
Null values are passed to the `updateView` method when data isn't ready. Your components should account for this situation and expect that the data could be null, and that a subsequent `updateView` cycle can include updated values. `updateView` is available for both [standard](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/control/updateview) and [React](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/react-control/updateview) components.
|
||||
|
||||
## Model-Driven Apps
|
||||
|
||||
### Don't Interact Directly with `formContext`
|
||||
|
||||
If you have experience working with client API, you might be used to interacting with `formContext` to access attributes, controls, and call API methods such as `save`, `refresh`, and `setNotification`. Code components are expected to work across various products like model-driven apps, canvas apps, and dashboards, therefore they can't have a dependency on `formContext`.
|
||||
|
||||
A workaround is to make the code component bound to a column and add an `OnChange` event handler to that column. The code component can update the column value, and the `OnChange` event handler can access the `formContext`. Support for the custom events will be added in the future, which will enable communicating changes outside of a control without adding a column configuration.
|
||||
|
||||
### Limit Size and Frequency of Calls to the `WebApi`
|
||||
|
||||
When using the `context.WebApi` methods, limit both the number of calls and the amount of data. Each time you call the `WebApi`, it counts towards the user's API entitlement and service protection limits. When performing CRUD operations on records, consider the size of the payload. In general, the larger the request payload, the slower your code component is.
|
||||
|
||||
## Canvas Apps
|
||||
|
||||
### Minimize the Number of Components on a Screen
|
||||
|
||||
Each time you add a component to your canvas app, it takes a finite amount of time to render. Render time increases with each component you add. Carefully measure the performance of your code components as you add more to a screen using the Developer Performance tools.
|
||||
|
||||
Currently, each code component bundles their own library of shared libraries such as Fluent UI and React. Loading multiple instances of the same library won't load these libraries multiple times. However, loading multiple different code components results in the browser loading multiple bundled versions of these libraries. In the future, these libraries will be able to be loaded and shared with code components.
|
||||
|
||||
### Allow Makers to Style Your Code Component
|
||||
|
||||
When app makers consume code components from inside a canvas app, they want to use a style that matches the rest of their app. Use input properties to provide customization options for theme elements such as color and size. When using Microsoft Fluent UI, map these properties to the theme elements provided by the library. In the future, theming support will be added to code components to make this process easier.
|
||||
|
||||
### Follow Canvas Apps Performance Best Practices
|
||||
|
||||
Canvas apps provide a wide set of best practices from inside the app and solution checker. Ensure your apps follow these recommendations before you add code components. For more information, see:
|
||||
|
||||
- [Tips to improve canvas app performance](https://learn.microsoft.com/en-us/powerapps/maker/canvas-apps/performance-tips)
|
||||
- [Considerations for optimized performance in Power Apps](https://powerapps.microsoft.com/blog/considerations-for-optimized-performance-in-power-apps/)
|
||||
|
||||
## TypeScript and JavaScript
|
||||
|
||||
### ES5 vs ES6
|
||||
|
||||
By default, code components target ES5 to support older browsers. If you don't want to support these older browsers, you can change the target to ES6 inside your `pcfproj` folder's `tsconfig.json`. More information: [ES5 vs ES6](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/debugging-custom-controls#es5-vs-es6).
|
||||
|
||||
### Module Imports
|
||||
|
||||
Always bundle the modules that are required as part of your code component instead of using scripts that are required to be loading using the `SCRIPT` tag. For example, if you wanted to use a non-Microsoft charting API where the sample shows adding `<script type="text/javascript" src="somechartlibrary.js></script>` to the page, this isn't supported inside a code component. Bundling all of the required modules isolates the code component from other libraries and also supports running in offline mode.
|
||||
|
||||
> **Note**: Support for shared libraries across components using library nodes in the component manifest is not yet supported.
|
||||
|
||||
### Linting
|
||||
|
||||
Linting is where a tool can scan the code for potential issues. The template used by `pac pcf init` installs the `eslint` module to your project and configures it by adding an `.eslintrc.json` file.
|
||||
|
||||
To configure, at the command-line use:
|
||||
|
||||
```bash
|
||||
npx eslint --init
|
||||
```
|
||||
|
||||
Then answer the following questions when prompted:
|
||||
|
||||
- **How would you like to use ESLint?** Answer: To check syntax, find problems, and enforce code style
|
||||
- **What type of modules does your project use?** Answer: JavaScript modules (import/export)
|
||||
- **Which framework does your project use?** Answer: React
|
||||
- **Does your project use TypeScript?** Answer: Yes
|
||||
- **Where does your code run?** Answer: Browser
|
||||
- **How would you like to define a style for your project?** Answer: Answer questions about your style
|
||||
- **What format do you want your config file to be in?** Answer: JSON
|
||||
- **What style of indentation do you use?** Answer: Spaces
|
||||
- **What quotes do you use for strings?** Answer: Single
|
||||
- **What line endings do you use?** Answer: Windows
|
||||
- **Do you require semicolons?** Answer: Yes
|
||||
|
||||
Before you can use `eslint`, you need to add some scripts to the `package.json`:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
...
|
||||
"lint": "eslint MY_CONTROL_NAME --ext .ts,.tsx",
|
||||
"lint:fix": "npm run lint -- --fix"
|
||||
}
|
||||
```
|
||||
|
||||
Now at the command-line, you can use:
|
||||
|
||||
```bash
|
||||
npm run lint:fix
|
||||
```
|
||||
|
||||
Additionally, you can add files to ignore by adding to the `.eslintrc.json`:
|
||||
|
||||
```json
|
||||
"ignorePatterns": ["**/generated/*.ts"]
|
||||
```
|
||||
|
||||
## HTML Browser User Interface Development
|
||||
|
||||
### Use Microsoft Fluent UI React
|
||||
|
||||
[Fluent UI React](https://developer.microsoft.com/fluentui#/get-started/web) is the official [open source](https://github.com/microsoft/fluentui) React front-end framework designed to build experiences that fit seamlessly into a broad range of Microsoft products. Power Apps itself uses Fluent UI, meaning you are able to create UI that's consistent with the rest of your apps.
|
||||
|
||||
#### Use Path-Based Imports from Fluent to Reduce Bundle Size
|
||||
|
||||
Currently, the code component templates used with `pac pcf init` won't use tree-shaking, which is the process where `webpack` detects modules imported that aren't used and removes them. If you import from Fluent UI using the following command, it imports and bundles the entire library:
|
||||
|
||||
```typescript
|
||||
import { Button } from '@fluentui/react'
|
||||
```
|
||||
|
||||
To avoid importing and bundling the entire library, you can use path-based imports where the specific library component is imported using the explicit path:
|
||||
|
||||
```typescript
|
||||
import { Button } from '@fluentui/react/lib/Button';
|
||||
```
|
||||
|
||||
Using the specific path reduces your bundle size both in development and release builds.
|
||||
|
||||
#### Optimize React Rendering
|
||||
|
||||
When using React, follow React specific best practices regarding minimizing rendering of components:
|
||||
|
||||
- Only make a call to `ReactDOM.render` inside the `updateView` method when a bound property or framework aspect change requires the UI to reflect the change. You can use `updatedProperties` to determine what has changed.
|
||||
- Use `PureComponent` (with class components) or `React.memo` (with function components) where possible to avoid unnecessary re-renders.
|
||||
- For large React components, deconstruct your UI into smaller components to improve performance.
|
||||
- Avoid use of arrow functions and function binding inside the render function as these practices create a new callback closure with each render.
|
||||
|
||||
### Check Accessibility
|
||||
|
||||
Ensure that code components are accessible so that keyboard only and screen-reader users can use them:
|
||||
|
||||
- Provide keyboard navigation alternatives to mouse/touch events
|
||||
- Ensure that `alt` and [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) (Accessible Rich Internet Applications) attributes are set so that screen readers announce an accurate representation of the code components interface
|
||||
- Modern browser developer tools offer helpful ways to inspect accessibility
|
||||
|
||||
More information: [Create accessible canvas apps in Power Apps](https://learn.microsoft.com/en-us/powerapps/maker/canvas-apps/accessible-apps).
|
||||
|
||||
### Always Use Asynchronous Network Calls
|
||||
|
||||
When making network calls, never use a synchronous blocking request since this causes the app to stop responding and result in slow performance. More information: [Interact with HTTP and HTTPS resources asynchronously](https://learn.microsoft.com/en-us/powerapps/developer/model-driven-apps/best-practices/business-logic/interact-http-https-resources-asynchronously).
|
||||
|
||||
### Write Code for Multiple Browsers
|
||||
|
||||
Model-driven apps, canvas apps, and portals all support multiple browsers. Be sure to only use techniques that are supported on all modern browsers, and test with a representative set of browsers for your intended audience.
|
||||
|
||||
- [Limits and configurations](https://learn.microsoft.com/en-us/powerapps/maker/canvas-apps/limits-and-config)
|
||||
- [Supported web browsers](https://learn.microsoft.com/en-us/power-platform/admin/supported-web-browsers-and-mobile-devices)
|
||||
- [Browsers used by office](https://learn.microsoft.com/en-us/office/dev/add-ins/concepts/browsers-used-by-office-web-add-ins)
|
||||
|
||||
### Code Components Should Plan for Supporting Multiple Clients and Screen Formats
|
||||
|
||||
Code components can be rendered in multiple clients (model-driven apps, canvas apps, portals) and screen formats (mobile, tablet, web).
|
||||
|
||||
- Using `trackContainerResize` allows code components to respond to changes in the available width and height
|
||||
- Using `allocatedHeight` and `allocatedWidth` can be combined with `getFormFactor` to determine if the code component is running on a mobile, tablet, or web client
|
||||
- Implementing `setFullScreen` allows users to expand to use the entire available screen available where space is limited
|
||||
- If the code component can't provide a meaningful experience in the given container size, it should disable functionality appropriately and provide feedback to the user
|
||||
|
||||
### Always Use Scoped CSS Rules
|
||||
|
||||
When you implement styling to your code components using CSS, ensure that the CSS is scoped to your component using the automatically generated CSS classes applied to the container `DIV` element for your component. If your CSS is scoped globally, it might break the existing styling of the form or screen where the code component is rendered.
|
||||
|
||||
For example, if your namespace is `SampleNamespace` and your code component name is `LinearInputComponent`, you would add a custom CSS rule using:
|
||||
|
||||
```css
|
||||
.SampleNamespace\.LinearInputComponent rule-name
|
||||
```
|
||||
|
||||
### Avoid Use of Web Storage Objects
|
||||
|
||||
Code components shouldn't use the HTML web storage objects, like `window.localStorage` and `window.sessionStorage`, to store data. Data stored locally on the user's browser or mobile client isn't secure and not guaranteed to be available reliably.
|
||||
|
||||
## ALM/Azure DevOps/GitHub
|
||||
|
||||
See the article on [Code component application lifecycle management (ALM)](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/code-components-alm) for best practices on code components with ALM/Azure DevOps/GitHub.
|
||||
|
||||
## Related Articles
|
||||
|
||||
- [What are code components](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/custom-controls-overview)
|
||||
- [Code components for canvas apps](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/component-framework-for-canvas-apps)
|
||||
- [Create and build a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/create-custom-controls-using-pcf)
|
||||
- [Learn Power Apps component framework](https://learn.microsoft.com/en-us/training/paths/use-power-apps-component-framework)
|
||||
- [Use code components in Power Pages](https://learn.microsoft.com/en-us/power-apps/maker/portals/component-framework)
|
||||
104
instructions/pcf-canvas-apps.instructions.md
Normal file
104
instructions/pcf-canvas-apps.instructions.md
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
description: 'Code components for canvas apps implementation, security, and configuration'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Code Components for Canvas Apps
|
||||
|
||||
Professional developers can use Power Apps component framework to create code components that can be used in their canvas apps. App makers can use Power Apps component framework to create, import, and add code components to canvas apps using [Microsoft Power Platform CLI](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/get-powerapps-cli).
|
||||
|
||||
> **Note**: Certain APIs might not be available in canvas apps. We recommend that you check each API to determine where it's available.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
> **Warning**: Code components contain code that may not be generated by Microsoft and can potentially access security tokens and data when rendered in Power Apps Studio. When adding code components to a canvas app, make sure that the code component solutions are from a trusted source. This vulnerability does not exist when playing the canvas app.
|
||||
|
||||
### Security Warning in Power Apps Studio
|
||||
|
||||
When you open a canvas app that contains code components in Power Apps Studio, a warning message about potentially unsafe code appears. Code components in the Power Apps Studio environment have access to security tokens; hence only components from trusted sources should be opened.
|
||||
|
||||
**Best Practices:**
|
||||
- Administrators and system customizers should review and validate all code components before importing them into an environment
|
||||
- Make components available to makers only after validation
|
||||
- The `Default` publisher is shown when you import code components by using an unmanaged solution or when you have used `pac pcf push` to install your code component
|
||||
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A Power Apps license is required. More information: [Power Apps component framework licensing](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/overview#licensing)
|
||||
- System administrator privileges are required to enable the Power Apps component framework feature in the environment
|
||||
|
||||
## Enable the Power Apps Component Framework Feature
|
||||
|
||||
To add code components to an app, you need to enable the Power Apps component framework feature in each environment where you want to use them. By default, the Power Apps component feature is enabled for model-driven apps.
|
||||
|
||||
### Steps to Enable for Canvas Apps:
|
||||
|
||||
1. Sign in to [Power Apps](https://powerapps.microsoft.com/)
|
||||
2. Select **Settings** , and then select **Admin Center**
|
||||
|
||||
|
||||
|
||||
3. On the left pane, select **Environments**, select the environment where you want to enable this feature, and then select **Settings**
|
||||
4. Expand **Product**, and select **Features**
|
||||
5. From the list of available features, turn on **Power Apps component framework for canvas apps**, and then select **Save**
|
||||
|
||||
|
||||
|
||||
## Implementing Code Components
|
||||
|
||||
After you enable the Power Apps component framework feature in your environment, you can start implementing the logic for code components. For a step-by-step tutorial, go to [Create your first code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript).
|
||||
|
||||
**Recommendation**: Check the [limitations](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/limitations) of code components in canvas apps before starting implementation.
|
||||
|
||||
## Add Components to a Canvas App
|
||||
|
||||
1. Go to Power Apps Studio
|
||||
2. Create a new canvas app, or edit an existing app to which you want to add the code component
|
||||
|
||||
> **Important**: Make sure the solution .zip file containing the code components has already been [imported](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/import-update-export-solutions) into Microsoft Dataverse before you proceed to the next step.
|
||||
|
||||
3. On the left pane, select **Add (+)**, and then select **Get more components**
|
||||
|
||||
|
||||
|
||||
4. Select the **Code** tab, select a component from the list, and then select **Import**
|
||||
|
||||
|
||||
|
||||
5. On the left pane, select **+**, expand **Code components**, and then select the component to add it to the app
|
||||
|
||||
|
||||
|
||||
> **Note**: You can also add components by selecting **Insert > Custom > Import component**. This option will be removed in a future release, so we suggest using the flow described above.
|
||||
|
||||
### Component Properties
|
||||
|
||||
On the Properties tab, you'll notice the code component properties are displayed.
|
||||
|
||||
|
||||
|
||||
> **Note**: Existing code components can be re-imported by updating the code component's manifest version if you want the properties to be available in the default Properties tab. As before, the properties will continue to be available on the Advanced properties tab.
|
||||
|
||||
## Delete a Code Component from a Canvas App
|
||||
|
||||
1. Open the app where you've added the code component
|
||||
2. On the left pane, select **Tree view**, and then select the screen where you've added the code component
|
||||
3. Next to the component, select **More (...)**, and then select **Delete**
|
||||
|
||||
|
||||
|
||||
4. Save the app to see the changes
|
||||
|
||||
## Update Existing Code Components
|
||||
|
||||
Whenever you update the code components and want to see the runtime changes, you need to change the `version` property in the manifest file. We recommend that you change the version of the component whenever you make changes.
|
||||
|
||||
> **Note**: Existing code components are updated only when the app is closed or reopened in Power Apps Studio. When you reopen the app, it asks you to update the code components. Simply deleting or adding code components back into the app won't update the components. Publish all the customizations in the updated solution first, otherwise updates made to the code component won't appear.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Power Apps component framework overview](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/overview)
|
||||
- [Create your first code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript)
|
||||
- [Learn Power Apps component framework](https://learn.microsoft.com/en-us/training/paths/use-power-apps-component-framework)
|
||||
111
instructions/pcf-code-components.instructions.md
Normal file
111
instructions/pcf-code-components.instructions.md
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
description: 'Understanding code components structure and implementation'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# 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)
|
||||
189
instructions/pcf-community-resources.instructions.md
Normal file
189
instructions/pcf-community-resources.instructions.md
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
description: 'PCF community resources including gallery, videos, blogs, and development tools'
|
||||
applyTo: '**'
|
||||
---
|
||||
|
||||
# PCF Community Resources
|
||||
|
||||
The Power Apps Component Framework has a vibrant community that creates and shares resources, tools, and knowledge. This guide provides links to key community resources.
|
||||
|
||||
## PCF Gallery
|
||||
|
||||
**[PCF Gallery](https://pcf.gallery)**
|
||||
|
||||
The PCF Gallery is the central hub for discovering, sharing, and learning about PCF components.
|
||||
|
||||
**What You'll Find:**
|
||||
- Community-created components
|
||||
- Component demonstrations and screenshots
|
||||
- Source code links
|
||||
- Installation instructions
|
||||
- Component ratings and reviews
|
||||
- Search and filtering capabilities
|
||||
|
||||
**How to Use:**
|
||||
- Browse components by category
|
||||
- Search for specific functionality
|
||||
- Download components for your projects
|
||||
- Submit your own components to share with the community
|
||||
- Learn from real-world component implementations
|
||||
|
||||
## Community Videos
|
||||
|
||||
Learn from expert developers through these comprehensive video tutorials:
|
||||
|
||||
### Getting Started
|
||||
- **Getting started with code components with OOB React and Fluent UI by PowerfulDevs** - Introduction to building components with React and Fluent UI
|
||||
- **Getting Started With Power Apps Component Framework by April Dunnam** - Beginner-friendly introduction to PCF
|
||||
|
||||
### Deep Dives
|
||||
- **Power Apps Component Framework Manifest File Explained by April Dunnam** - Detailed explanation of the manifest structure
|
||||
- **Easier Development with React Controls and Platform Libraries by Scott Durow** - Using React and platform-provided libraries
|
||||
- **Understanding the Power Apps Component Framework by PowerfulDevs** - Comprehensive overview of the framework
|
||||
|
||||
### Debugging & Development
|
||||
- **How to Debug Power Apps Component Framework Components by April Dunnam** - Debugging techniques and tools
|
||||
- **Using React and the Fluent UI in Power Apps Component Framework by Microsoft** - Official guidance on React/Fluent UI integration
|
||||
|
||||
### Advanced Topics
|
||||
- **Power Apps Component Framework: Datasets with React and Azure Maps by Nishant Rana** - Working with datasets and external APIs
|
||||
- **How to Upload and Display Images with Power Apps Component Framework by April Dunnam** - Image handling in components
|
||||
- **Deep Dive: Power Apps Component Framework API by PowerfulDevs** - Comprehensive API exploration
|
||||
|
||||
### Styling & Theming
|
||||
- **Using Fluent UI Components in Power Apps Component Framework by Sancho Harker** - Styling with Fluent UI
|
||||
- **Power Apps Component Framework: Styling and Theming by Microsoft** - Official theming guidance
|
||||
|
||||
### Additional Resources
|
||||
- **Power Apps Component Framework End to End Series by April Dunnam** - Complete walkthrough series
|
||||
- More videos available through community channels and Microsoft's official documentation
|
||||
|
||||
## Community Blogs
|
||||
|
||||
Stay updated with these excellent community blogs:
|
||||
|
||||
1. **Sancho Harker** - Advanced PCF techniques and best practices
|
||||
2. **Benedikt Bergmann** - Component architecture and patterns
|
||||
3. **Andrew Butenko** - PCF development tips and tools
|
||||
4. **Nishant Rana** - Integration scenarios and advanced features
|
||||
5. **OlivierFlying** - Performance optimization and debugging
|
||||
6. **Ramakrishnan Raman** - Real-world implementation examples
|
||||
7. **Temmy Wahyu Raharjo** - Component design patterns
|
||||
8. **Scott Durow** - Platform libraries and React components
|
||||
9. **Guido Preite** - Enterprise PCF development
|
||||
10. **Ulrikke Akerbæk** - Canvas apps and PCF integration
|
||||
|
||||
**Topics Covered:**
|
||||
- Component development tutorials
|
||||
- Best practices and patterns
|
||||
- Performance optimization
|
||||
- Integration with external services
|
||||
- Troubleshooting common issues
|
||||
- New feature announcements
|
||||
- Real-world use cases
|
||||
|
||||
## Community Tools
|
||||
|
||||
### PCF Builder for XrmToolBox
|
||||
|
||||
**What It Does:**
|
||||
- Simplifies PCF component creation
|
||||
- Provides visual manifest editor
|
||||
- Generates boilerplate code
|
||||
- Streamlines component testing
|
||||
|
||||
**Key Features:**
|
||||
- Visual manifest designer
|
||||
- Property configuration UI
|
||||
- Resource management
|
||||
- Quick component scaffolding
|
||||
- Integration with XrmToolBox ecosystem
|
||||
|
||||
**Best For:**
|
||||
- Rapid prototyping
|
||||
- Learning PCF structure
|
||||
- Quick component setup
|
||||
- Manifest validation
|
||||
|
||||
### PCF Builder for VS Code
|
||||
|
||||
**What It Does:**
|
||||
- Integrates PCF development into Visual Studio Code
|
||||
- Provides IntelliSense and code completion
|
||||
- Simplifies workflow without leaving the editor
|
||||
|
||||
**Key Features:**
|
||||
- VS Code extension
|
||||
- Command palette integration
|
||||
- Manifest schema validation
|
||||
- Code snippets for common patterns
|
||||
- Integrated terminal commands
|
||||
|
||||
**Best For:**
|
||||
- Developers who prefer VS Code
|
||||
- Streamlined workflow
|
||||
- Modern development experience
|
||||
- Built-in debugging support
|
||||
|
||||
## How to Engage with the Community
|
||||
|
||||
### Contribute Components
|
||||
- Share your components on PCF Gallery
|
||||
- Publish source code on GitHub
|
||||
- Write blog posts about your implementation
|
||||
|
||||
### Learn from Others
|
||||
- Browse PCF Gallery for inspiration
|
||||
- Watch community videos for tutorials
|
||||
- Read blogs for best practices and tips
|
||||
|
||||
### Get Help
|
||||
- Microsoft Learn Q&A forums
|
||||
- Power Apps Community forums
|
||||
- GitHub repository issues and discussions
|
||||
- Twitter/LinkedIn Power Platform community
|
||||
|
||||
### Stay Updated
|
||||
- Follow community bloggers
|
||||
- Subscribe to YouTube channels
|
||||
- Join Power Platform user groups
|
||||
- Attend community calls and events
|
||||
|
||||
## Community Best Practices
|
||||
|
||||
1. **Share Your Work**: Contribute components and knowledge back to the community
|
||||
2. **Provide Feedback**: Report issues and suggest improvements
|
||||
3. **Document Well**: Include clear documentation with your components
|
||||
4. **Test Thoroughly**: Ensure components work across platforms before sharing
|
||||
5. **Follow Standards**: Use established patterns and naming conventions
|
||||
6. **Be Helpful**: Answer questions and help other developers
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Microsoft Learn**: Official documentation and tutorials
|
||||
- **Power Platform Community**: Forums and discussion boards
|
||||
- **GitHub**: Source code repositories and samples
|
||||
- **Power CAT (Customer Advisory Team)**: Enterprise guidance and patterns
|
||||
- **User Groups**: Local and virtual meetups
|
||||
|
||||
## Contributing to PCF Gallery
|
||||
|
||||
To add your component to PCF Gallery:
|
||||
|
||||
1. Create a well-documented component
|
||||
2. Test across target platforms
|
||||
3. Prepare screenshots and demos
|
||||
4. Submit to pcf.gallery
|
||||
5. Include source code link (GitHub recommended)
|
||||
6. Provide clear installation instructions
|
||||
|
||||
## Finding the Right Resource
|
||||
|
||||
- **Just Starting?** → Watch April Dunnam's "Getting Started" video
|
||||
- **Need a Component?** → Browse PCF Gallery
|
||||
- **Learning Best Practices?** → Read community blogs
|
||||
- **Want Quick Setup?** → Use PCF Builder tools
|
||||
- **Debugging Issues?** → Watch debugging videos and read troubleshooting blogs
|
||||
- **Advanced Techniques?** → Follow Scott Durow and PowerfulDevs content
|
||||
|
||||
The PCF community is welcoming and eager to help. Don't hesitate to reach out, ask questions, and share your own experiences!
|
||||
131
instructions/pcf-dependent-libraries.instructions.md
Normal file
131
instructions/pcf-dependent-libraries.instructions.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
description: 'Using dependent libraries in PCF components'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Dependent Libraries (Preview)
|
||||
|
||||
[This topic is pre-release documentation and is subject to change.]
|
||||
|
||||
With model-driven apps, you can reuse a prebuilt library contained in another component that is loaded as a dependency to more than one component.
|
||||
|
||||
Having copies of a prebuilt library in multiple controls is undesirable. Reusing existing libraries improves performance, especially when the library is large, by reducing the load time for all components that use the library. Library reuse also helps reduce the maintenance overhead in build processes.
|
||||
|
||||
## Before and After
|
||||
|
||||
**Before**: Custom library files contained in each PCF component
|
||||
|
||||
|
||||
**After**: Components calling a shared function from a Library Control
|
||||
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
To use dependent libraries, you need to:
|
||||
|
||||
1. Create a **Library component** that contains the library. This component can provide some functionality or only be a container for the library.
|
||||
2. Configure another component to depend on the library loaded by the library component.
|
||||
|
||||
By default, the library loads when the dependent component loads, but you can configure it to load on demand.
|
||||
|
||||
This way you can independently maintain the library in the Library Control and the dependent controls don't need to have a copy of the library bundled with them.
|
||||
|
||||
## How It Works
|
||||
|
||||
You need to add configuration data to your component project so that the build process deploys your libraries the way you want. Set this configuration data by adding or editing the following files:
|
||||
|
||||
- **featureconfig.json**
|
||||
- **webpack.config.js**
|
||||
- Edit the manifest schema to **Register dependencies**
|
||||
|
||||
### featureconfig.json
|
||||
|
||||
Add this file to override the default feature flags for a component without modifying the files generated in the `node_modules` folder.
|
||||
|
||||
**Feature Flags:**
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `pcfResourceDependency` | Enables the component to use a library resource. |
|
||||
| `pcfAllowCustomWebpack` | Enables the component to use a custom web pack. This feature must be enabled for components that define a library resource. |
|
||||
|
||||
By default, these values are `off`. Set them to `on` to override the default.
|
||||
|
||||
**Example 1:**
|
||||
```json
|
||||
{
|
||||
"pcfAllowCustomWebpack": "on"
|
||||
}
|
||||
```
|
||||
|
||||
**Example 2:**
|
||||
```json
|
||||
{
|
||||
"pcfResourceDependency": "on",
|
||||
"pcfAllowCustomWebpack": "off"
|
||||
}
|
||||
```
|
||||
|
||||
### webpack.config.js
|
||||
|
||||
The build process for components uses [Webpack](https://webpack.js.org/) to bundle the code and dependencies into a deployable asset. To exclude your libraries from this bundling, add a `webpack.config.js` file to the project root folder that specifies the alias of the library as `externals`. [Learn more about the Webpack externals configuration option](https://webpack.js.org/configuration/externals/)
|
||||
|
||||
This file might look like the following when the library alias is `myLib`:
|
||||
|
||||
```javascript
|
||||
/* eslint-disable */
|
||||
"use strict";
|
||||
|
||||
module.exports = {
|
||||
externals: {
|
||||
"myLib": "myLib"
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Register Dependencies
|
||||
|
||||
Use the [dependency element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/dependency) within [resources](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/resources) of the manifest schema.
|
||||
|
||||
```xml
|
||||
<resources>
|
||||
<dependency
|
||||
type="control"
|
||||
name="samples_SampleNS.SampleStubLibraryPCF"
|
||||
order="1"
|
||||
/>
|
||||
<code path="index.ts" order="2" />
|
||||
</resources>
|
||||
```
|
||||
|
||||
### Dependency as On-Demand Load of a Component
|
||||
|
||||
Rather than loading the dependent library when a component loads, you can load the dependent library on demand. Loading on demand provides the flexibility for more complex controls to only load dependencies when they're required, especially if the dependent libraries are large.
|
||||
|
||||
|
||||
|
||||
To enable on demand loading, you need to:
|
||||
|
||||
**Step 1**: Add these [platform-action element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/platform-action), [feature-usage element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/feature-usage), and [uses-feature element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/uses-feature) child elements to the [control element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/control):
|
||||
|
||||
```xml
|
||||
<platform-action action-type="afterPageLoad" />
|
||||
<feature-usage>
|
||||
<uses-feature name="Utility"
|
||||
required="true" />
|
||||
</feature-usage>
|
||||
```
|
||||
|
||||
**Step 2**: Set the `load-type` attribute of the [dependency element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/dependency) to `onDemand`.
|
||||
|
||||
```xml
|
||||
<dependency type="control"
|
||||
name="samples_SampleNamespace.StubLibrary"
|
||||
load-type="onDemand" />
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Try a tutorial that walks you through creating a dependent library:
|
||||
|
||||
[Tutorial: Use dependent libraries in a component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/tutorial-use-dependent-libraries)
|
||||
102
instructions/pcf-events.instructions.md
Normal file
102
instructions/pcf-events.instructions.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
description: 'Define and handle custom events in PCF components'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Define Events (Preview)
|
||||
|
||||
[This topic is pre-release documentation and is subject to change.]
|
||||
|
||||
A common requirement when building custom components with the Power Apps Component Framework is the ability to react to events generated within the control. These events can be invoked either due to user interaction or programmatically via code. For example, an application can have a code component that lets a user build a product bundle. This component can also raise an event which could show product information in another area of the application.
|
||||
|
||||
## Component Data Flow
|
||||
|
||||
The common data flow for a code component is data flowing from the hosting application into the control as inputs and updated data flowing out of the control to the hosting form or page. This diagram shows the standard pattern of data flow for a typical PCF component:
|
||||
|
||||
|
||||
|
||||
The data update from the code component to the bound field triggers the `OnChange` event. For most component scenarios, this is enough and makers just add a handler to trigger subsequent actions. However, a more complicated control might require events to be raised that aren't field updates. The event mechanism allows code components to define events that have separate event handlers.
|
||||
|
||||
## Using Events
|
||||
|
||||
The event mechanism in PCF is based on the standard event model in JavaScript. The component can define events in the manifest file and raise these events in the code. The hosting application can listen to these events and react to them.
|
||||
|
||||
### Define Events in Manifest
|
||||
|
||||
The component defines events using the [event element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/event) in the manifest file. This data allows the respective hosting application to react to events in different ways.
|
||||
|
||||
```xml
|
||||
<property
|
||||
name="sampleProperty"
|
||||
display-name-key="Property_Display_Key"
|
||||
description-key="Property_Desc_Key"
|
||||
of-type="SingleLine.Text"
|
||||
usage="bound"
|
||||
required="true"
|
||||
/>
|
||||
<event
|
||||
name="customEvent1"
|
||||
display-name-key="customEvent1"
|
||||
description-key="customEvent1"
|
||||
/>
|
||||
<event
|
||||
name="customEvent2"
|
||||
display-name-key="customEvent2"
|
||||
description-key="customEvent2"
|
||||
/>
|
||||
```
|
||||
|
||||
### Canvas Apps Event Handling
|
||||
|
||||
Canvas apps react to the event using Power Fx expressions:
|
||||
|
||||
|
||||
|
||||
### Model-Driven Apps Event Handling
|
||||
|
||||
Model Driven Apps use the [addEventHandler method](https://learn.microsoft.com/en-us/power-apps/developer/model-driven-apps/clientapi/reference/controls/addeventhandler) to associate event handlers to custom events for a component.
|
||||
|
||||
```javascript
|
||||
const controlName1 = "cr116_personid";
|
||||
|
||||
this.onLoad = function (executionContext) {
|
||||
const formContext = executionContext.getFormContext();
|
||||
|
||||
const sampleControl1 = formContext.getControl(controlName1);
|
||||
sampleControl1.addEventHandler("customEvent1", this.onSampleControl1CustomEvent1);
|
||||
sampleControl1.addEventHandler("customEvent2", this.onSampleControl1CustomEvent2);
|
||||
}
|
||||
```
|
||||
|
||||
> **Note**: These events occur separately for each instance of the code component in the app.
|
||||
|
||||
## Defining an Event for Model-Driven Apps
|
||||
|
||||
For model-driven apps you can pass a payload with the event allowing for more complex scenarios. For example in the diagram below the component passes a callback function in the event allowing the script handling to call back to the component.
|
||||
|
||||
|
||||
|
||||
```javascript
|
||||
this.onSampleControl1CustomEvent1 = function (params) {
|
||||
//alert(`SampleControl1 Custom Event 1: ${params}`);
|
||||
alert(`SampleControl1 Custom Event 1`);
|
||||
}.bind(this);
|
||||
|
||||
this.onSampleControl2CustomEvent2 = function (params) {
|
||||
alert(`SampleControl2 Custom Event 2: ${params.message}`);
|
||||
// prevent the default action for the event
|
||||
params.callBackFunction();
|
||||
}
|
||||
```
|
||||
|
||||
## Defining an Event for Canvas Apps
|
||||
|
||||
Makers configure an event using Power Fx on the PCF control in the properties pane.
|
||||
|
||||
## Calling an Event
|
||||
|
||||
See how to call an event in [Events](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/events).
|
||||
|
||||
## Next Steps
|
||||
|
||||
[Tutorial: Define a custom event in a component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/tutorial-define-event)
|
||||
106
instructions/pcf-fluent-modern-theming.instructions.md
Normal file
106
instructions/pcf-fluent-modern-theming.instructions.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
description: 'Style components with modern theming using Fluent UI'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Style Components with Modern Theming (Preview)
|
||||
|
||||
[This topic is pre-release documentation and is subject to change.]
|
||||
|
||||
Developers need to be able to style their components so they look like the rest of the application they're included in. They can do this when modern theming is in effect for either a canvas app (via the [Modern controls and themes](https://learn.microsoft.com/en-us/power-apps/maker/canvas-apps/controls/modern-controls/overview-modern-controls) feature) or model-driven app (through the [new refreshed look](https://learn.microsoft.com/en-us/power-apps/user/modern-fluent-design)).
|
||||
|
||||
Use modern theming, which is based on [Fluent UI React v9](https://react.fluentui.dev/), to style your component. This approach is recommended to get the best performance and theming experience for your component.
|
||||
|
||||
## Four Ways to Apply Modern Theming
|
||||
|
||||
1. **Fluent UI v9 controls**
|
||||
2. **Fluent UI v8 controls**
|
||||
3. **Non-Fluent UI controls**
|
||||
4. **Custom theme providers**
|
||||
|
||||
## Fluent UI v9 Controls
|
||||
|
||||
Wrapping Fluent UI v9 controls as a component is the easiest way to utilize modern theming because the modern theme is automatically applied to these controls. The only prerequisite is to ensure your component adds a dependency on the [React controls & platform libraries](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/react-controls-platform-libraries).
|
||||
|
||||
This approach allows your component to use the same React and Fluent libraries as the platform, and therefore share the same React context that passes the theme tokens down to the component.
|
||||
|
||||
```xml
|
||||
<resources>
|
||||
<code path="index.ts" order="1"/>
|
||||
<!-- Dependency on React controls & platform libraries -->
|
||||
<platform-library name="React" version="16.14.0" />
|
||||
<platform-library name="Fluent" version="9.46.2" />
|
||||
</resources>
|
||||
```
|
||||
|
||||
## Fluent UI v8 Controls
|
||||
|
||||
Fluent provides a migration path for applying v9 theme constructs when you use Fluent UI v8 controls in your component. Use the `createV8Theme` function included in the [Fluent's v8 to v9 migration package](https://www.npmjs.com/package/@fluentui/react-migration-v8-v9) to create a v8 theme based on v9 theme tokens:
|
||||
|
||||
```typescript
|
||||
const theme = createV8Theme(
|
||||
context.fluentDesignLanguage.brand,
|
||||
context.fluentDesignLanguage.theme
|
||||
);
|
||||
return <ThemeProvider theme={theme}></ThemeProvider>;
|
||||
```
|
||||
|
||||
## Non-Fluent UI Controls
|
||||
|
||||
If your component doesn't use Fluent UI, you can take a dependency directly on the v9 theme tokens available through the `fluentDesignLanguage` context parameter. Use this parameter to get access to all [theme](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/theming) tokens so it can reference any aspect of the theme to style itself.
|
||||
|
||||
```typescript
|
||||
<span style={{ fontSize: context.fluentDesignLanguage.theme.fontSizeBase300 }}>
|
||||
{"Stylizing HTML with platform provided theme."}
|
||||
</span>
|
||||
```
|
||||
|
||||
## Custom Theme Providers
|
||||
|
||||
When your component requires styling that is different from the current theme of the app, create your own `FluentProvider` and pass your own set of theme tokens to be used by your component.
|
||||
|
||||
```typescript
|
||||
<FluentProvider theme={context.fluentDesignLanguage.tokenTheme}>
|
||||
{/* your control */}
|
||||
</FluentProvider>
|
||||
```
|
||||
|
||||
## Sample Controls
|
||||
|
||||
Examples for each of these use cases are available at [Modern Theming API control](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/sample-controls/modern-theming-api-control).
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: My control uses Fluent UI v9 and has a dependency on the platform libraries, but I don't want to utilize modern theming. How can I disable it for my component?
|
||||
|
||||
A: You can do this two different ways:
|
||||
|
||||
**Option 1**: Create your own component-level `FluentProvider`
|
||||
|
||||
```typescript
|
||||
<FluentProvider theme={customFluentV9Theme}>
|
||||
{/* your control */}
|
||||
</FluentProvider>
|
||||
```
|
||||
|
||||
**Option 2**: Wrap your control inside `IdPrefixContext.Provider` and set your own `idPrefix` value. This prevents your component from getting theme tokens from the platform.
|
||||
|
||||
```typescript
|
||||
<IdPrefixProvider value="custom-control-prefix">
|
||||
<Label weight="semibold">This label is not getting Modern Theming</Label>
|
||||
</IdPrefixProvider>
|
||||
```
|
||||
|
||||
### Q: Some of my Fluent UI v9 controls aren't getting styles
|
||||
|
||||
A: Fluent v9 controls that rely on the React Portal need to be rewrapped in the theme provider to ensure styling is properly applied. You can use `FluentProvider`.
|
||||
|
||||
### Q: How can I check if modern theming is enabled?
|
||||
|
||||
A: You can check if tokens are available: `context.fluentDesignLanguage?.tokenTheme`. Or in model-driven applications you can check app settings: `context.appSettings.getIsFluentThemingEnabled()`.
|
||||
|
||||
## Related Articles
|
||||
|
||||
- [Theming (Power Apps component framework API reference)](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/theming)
|
||||
- [Modern Theming API control](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/sample-controls/modern-theming-api-control)
|
||||
- [Use modern themes in canvas apps (preview)](https://learn.microsoft.com/en-us/power-apps/maker/canvas-apps/controls/modern-controls/modern-theming)
|
||||
31
instructions/pcf-limitations.instructions.md
Normal file
31
instructions/pcf-limitations.instructions.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
description: 'Limitations and restrictions of Power Apps Component Framework'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Limitations
|
||||
|
||||
With Power Apps component framework, you can create your own code components to improve the user experience in Power Apps and Power Pages. Even though you can create your own components, there are some limitations that restrict developers implementing some features in the code components. Below are some of the limitations:
|
||||
|
||||
## 1. Dataverse Dependent APIs Not Available for Canvas Apps
|
||||
|
||||
Microsoft Dataverse dependent APIs, including WebAPI, are not available for Power Apps canvas applications yet. For individual API availability, see [Power Apps component framework API reference](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/).
|
||||
|
||||
## 2. Bundle External Libraries or Use Platform Libraries
|
||||
|
||||
Code components should either use [React controls & platform libraries](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/react-controls-platform-libraries) or bundle all the code including external library content into the primary code bundle.
|
||||
|
||||
To see an example of how the Power Apps command line interface can help with bundling your external library content into a component-specific bundle, see [Angular flip component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/sample-controls/angular-flip-control) example.
|
||||
|
||||
## 3. Do Not Use HTML Web Storage Objects
|
||||
|
||||
Code components should not use the HTML web storage objects, like `window.localStorage` and `window.sessionStorage`, to store data. Data stored locally on the user's browser or mobile client is not secure and not guaranteed to be available reliably.
|
||||
|
||||
## 4. Custom Auth Not Supported in Canvas Apps
|
||||
|
||||
Custom auth in code components is not supported in Power Apps canvas applications. Use connectors to get data and take actions instead.
|
||||
|
||||
## Related Topics
|
||||
|
||||
- [Power Apps component framework API reference](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/)
|
||||
- [Power Apps component framework overview](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/overview)
|
||||
297
instructions/pcf-manifest-schema.instructions.md
Normal file
297
instructions/pcf-manifest-schema.instructions.md
Normal file
@@ -0,0 +1,297 @@
|
||||
---
|
||||
description: 'Complete manifest schema reference for PCF components with all available XML elements'
|
||||
applyTo: '**/*.xml'
|
||||
---
|
||||
|
||||
# Manifest Schema Reference
|
||||
|
||||
The manifest file (`ControlManifest.Input.xml`) is a metadata document that defines your code component. This reference lists all available manifest elements and their purposes.
|
||||
|
||||
## Root Element
|
||||
|
||||
### manifest
|
||||
|
||||
The root element that contains the entire component definition.
|
||||
|
||||
## Core Elements
|
||||
|
||||
### code
|
||||
|
||||
Refers to the resource file that implements the component logic.
|
||||
|
||||
**Attributes:**
|
||||
- `path`: Path to the TypeScript/JavaScript implementation file
|
||||
- `order`: Loading order (typically "1")
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps, portals
|
||||
|
||||
### control
|
||||
|
||||
Defines the component itself, including namespace, version, and display information.
|
||||
|
||||
**Key Attributes:**
|
||||
- `namespace`: Namespace for the component
|
||||
- `constructor`: Constructor name
|
||||
- `version`: Semantic version (e.g., "1.0.0")
|
||||
- `display-name-key`: Resource key for display name
|
||||
- `description-key`: Resource key for description
|
||||
- `control-type`: Type of control ("standard" or "virtual")
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps, portals
|
||||
|
||||
## Property Elements
|
||||
|
||||
### property
|
||||
|
||||
Defines an input or output property for the component.
|
||||
|
||||
**Key Attributes:**
|
||||
- `name`: Property name
|
||||
- `display-name-key`: Resource key for display name
|
||||
- `description-key`: Resource key for description
|
||||
- `of-type`: Data type (e.g., "SingleLine.Text", "Whole.None", "TwoOptions", "DateAndTime.DateOnly")
|
||||
- `usage`: Property usage ("bound" or "input")
|
||||
- `required`: Whether property is required (true/false)
|
||||
- `of-type-group`: Reference to a type-group
|
||||
- `default-value`: Default value for the property
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps, portals
|
||||
|
||||
### type-group
|
||||
|
||||
Defines a group of types that a property can accept.
|
||||
|
||||
**Usage:** Allows a property to accept multiple data types
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps, portals
|
||||
|
||||
## Data Set Elements
|
||||
|
||||
### data-set
|
||||
|
||||
Defines a dataset property for working with tabular data.
|
||||
|
||||
**Key Attributes:**
|
||||
- `name`: Dataset name
|
||||
- `display-name-key`: Resource key for display name
|
||||
- `description-key`: Resource key for description
|
||||
|
||||
**Availability:** Model-driven apps (canvas apps with limitations)
|
||||
|
||||
## Resource Elements
|
||||
|
||||
### resources
|
||||
|
||||
Container for all resource definitions (code, CSS, images, localization).
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps, portals
|
||||
|
||||
### css
|
||||
|
||||
References a CSS stylesheet file.
|
||||
|
||||
**Attributes:**
|
||||
- `path`: Path to CSS file
|
||||
- `order`: Loading order
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps, portals
|
||||
|
||||
### img
|
||||
|
||||
References an image resource.
|
||||
|
||||
**Attributes:**
|
||||
- `path`: Path to image file
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps, portals
|
||||
|
||||
### resx
|
||||
|
||||
References a resource file for localization.
|
||||
|
||||
**Attributes:**
|
||||
- `path`: Path to .resx file
|
||||
- `version`: Version number
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps, portals
|
||||
|
||||
## Feature Usage Elements
|
||||
|
||||
### uses-feature
|
||||
|
||||
Declares that the component uses a specific platform feature.
|
||||
|
||||
**Key Attributes:**
|
||||
- `name`: Feature name (e.g., "Device.captureImage", "Device.getCurrentPosition", "Utility.lookupObjects", "WebAPI")
|
||||
- `required`: Whether feature is required (true/false)
|
||||
|
||||
**Common Features:**
|
||||
- Device.captureAudio
|
||||
- Device.captureImage
|
||||
- Device.captureVideo
|
||||
- Device.getBarcodeValue
|
||||
- Device.getCurrentPosition
|
||||
- Device.pickFile
|
||||
- Utility.lookupObjects
|
||||
- WebAPI
|
||||
|
||||
**Availability:** Varies by feature and platform
|
||||
|
||||
### feature-usage
|
||||
|
||||
Container for feature declarations.
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps
|
||||
|
||||
## Dependency Elements
|
||||
|
||||
### dependency
|
||||
|
||||
Declares external dependencies required by the component.
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps
|
||||
|
||||
### external-service-usage
|
||||
|
||||
Declares external services that the component uses.
|
||||
|
||||
**Key Attributes:**
|
||||
- `enabled`: Whether external service usage is enabled (true/false)
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps
|
||||
|
||||
## Library Elements
|
||||
|
||||
### platform-library
|
||||
|
||||
References a platform-provided library (e.g., React, Fluent UI).
|
||||
|
||||
**Key Attributes:**
|
||||
- `name`: Library name (e.g., "React", "Fluent")
|
||||
- `version`: Library version
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps
|
||||
|
||||
## Event Elements
|
||||
|
||||
### event
|
||||
|
||||
Defines custom events that the component can raise.
|
||||
|
||||
**Key Attributes:**
|
||||
- `name`: Event name
|
||||
- `display-name-key`: Resource key for display name
|
||||
- `description-key`: Resource key for description
|
||||
|
||||
**Availability:** Model-driven apps, canvas apps
|
||||
|
||||
## Action Elements
|
||||
|
||||
### platform-action
|
||||
|
||||
Defines platform actions that the component can invoke.
|
||||
|
||||
**Availability:** Model-driven apps
|
||||
|
||||
## Example Manifest Structure
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8" ?>
|
||||
<manifest>
|
||||
<control namespace="SampleNamespace"
|
||||
constructor="SampleControl"
|
||||
version="1.0.0"
|
||||
display-name-key="Sample_Display_Key"
|
||||
description-key="Sample_Desc_Key"
|
||||
control-type="standard">
|
||||
|
||||
<!-- Properties -->
|
||||
<property name="sampleProperty"
|
||||
display-name-key="Property_Display_Key"
|
||||
description-key="Property_Desc_Key"
|
||||
of-type="SingleLine.Text"
|
||||
usage="bound"
|
||||
required="true" />
|
||||
|
||||
<!-- Type Group Example -->
|
||||
<type-group name="numbers">
|
||||
<type>Whole.None</type>
|
||||
<type>Currency</type>
|
||||
<type>FP</type>
|
||||
<type>Decimal</type>
|
||||
</type-group>
|
||||
|
||||
<property name="numericProperty"
|
||||
display-name-key="Numeric_Display_Key"
|
||||
of-type-group="numbers"
|
||||
usage="bound" />
|
||||
|
||||
<!-- Data Set Example -->
|
||||
<data-set name="dataSetProperty"
|
||||
display-name-key="Dataset_Display_Key">
|
||||
</data-set>
|
||||
|
||||
<!-- Events -->
|
||||
<event name="onCustomEvent"
|
||||
display-name-key="Event_Display_Key"
|
||||
description-key="Event_Desc_Key" />
|
||||
|
||||
<!-- Resources -->
|
||||
<resources>
|
||||
<code path="index.ts" order="1" />
|
||||
<css path="css/SampleControl.css" order="1" />
|
||||
<img path="img/icon.png" />
|
||||
<resx path="strings/SampleControl.1033.resx" version="1.0.0" />
|
||||
</resources>
|
||||
|
||||
<!-- Feature Usage -->
|
||||
<feature-usage>
|
||||
<uses-feature name="WebAPI" required="true" />
|
||||
<uses-feature name="Device.captureImage" required="false" />
|
||||
</feature-usage>
|
||||
|
||||
<!-- Platform Library -->
|
||||
<platform-library name="React" version="16.8.6" />
|
||||
<platform-library name="Fluent" version="8.29.0" />
|
||||
|
||||
</control>
|
||||
</manifest>
|
||||
```
|
||||
|
||||
## Manifest Validation
|
||||
|
||||
The manifest schema is validated during the build process:
|
||||
- Missing required elements will cause build errors
|
||||
- Invalid attribute values will be flagged
|
||||
- Use `pac pcf` commands to validate manifest structure
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Semantic Versioning**: Use semantic versioning (major.minor.patch) for component versions
|
||||
2. **Localization Keys**: Always use resource keys instead of hardcoded strings
|
||||
3. **Feature Declaration**: Declare all features your component uses
|
||||
4. **Required vs Optional**: Mark properties and features as required only when truly necessary
|
||||
5. **Type Groups**: Use type-groups for properties that accept multiple numeric types
|
||||
6. **Data Types**: Choose the most specific data type that matches your requirements
|
||||
7. **CSS Scoping**: Scope CSS to avoid conflicts with host applications
|
||||
8. **Resource Organization**: Keep resources organized in separate folders (css/, img/, strings/)
|
||||
|
||||
## Data Type Reference
|
||||
|
||||
Common `of-type` values for properties:
|
||||
|
||||
- **Text**: SingleLine.Text, Multiple, SingleLine.TextArea, SingleLine.Email, SingleLine.Phone, SingleLine.Url, SingleLine.Ticker
|
||||
- **Numbers**: Whole.None, Currency, FP, Decimal
|
||||
- **Date/Time**: DateAndTime.DateAndTime, DateAndTime.DateOnly
|
||||
- **Boolean**: TwoOptions
|
||||
- **Lookup**: Lookup.Simple
|
||||
- **OptionSet**: OptionSet, MultiSelectOptionSet
|
||||
- **Other**: Enum
|
||||
|
||||
## Platform Availability Legend
|
||||
|
||||
- ✅ **Model-driven apps**: Fully supported
|
||||
- ✅ **Canvas apps**: Supported (may have limitations)
|
||||
- ✅ **Portals**: Supported in Power Pages
|
||||
|
||||
Most manifest elements are available across all platforms, but some features (like certain Device APIs or platform actions) may be platform-specific. Always test in your target environment.
|
||||
51
instructions/pcf-model-driven-apps.instructions.md
Normal file
51
instructions/pcf-model-driven-apps.instructions.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
description: 'Code components for model-driven apps implementation and configuration'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Code Components for Model-Driven Apps
|
||||
|
||||
Power Apps component framework gives developers the ability to extend the visualizations in model-driven apps. Professional developers can create, debug, import, and add code components to model-driven apps using [Microsoft Power Platform CLI](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/get-powerapps-cli).
|
||||
|
||||
## Component Usage
|
||||
|
||||
You can add code components to:
|
||||
- Columns
|
||||
- Grids
|
||||
- Sub grids
|
||||
|
||||
in model-driven apps.
|
||||
|
||||
> **Important**: Power Apps component framework is enabled for model-driven apps by default. See [Code components for canvas apps](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/component-framework-for-canvas-apps) to learn how to enable Power Apps component framework for canvas apps.
|
||||
|
||||
## Implementing Code Components
|
||||
|
||||
Before you start creating code components, make sure that you have installed all the [prerequisites](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/create-custom-controls-using-pcf#prerequisites) that are required to develop components using Power Apps component framework.
|
||||
|
||||
The [create your first code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript) article demonstrates the step-by-step process to create code components.
|
||||
|
||||
## Add Code Components to Model-Driven Apps
|
||||
|
||||
To add code components to a column or a table in model-driven apps, see [Add code components to model-driven apps](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/add-custom-controls-to-a-field-or-entity).
|
||||
|
||||
### Examples
|
||||
|
||||
**Linear Slider Control:**
|
||||
|
||||
|
||||
|
||||
**Data Set Grid Component:**
|
||||
|
||||
|
||||
|
||||
## Update Existing Code Components
|
||||
|
||||
Whenever you update the code components and want to see the changes in runtime, you need to bump the version property in the manifest file.
|
||||
|
||||
**Best Practice**: It is recommended to always bump the version of the component whenever you make changes.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Power Apps component framework overview](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/overview)
|
||||
- [Create your first code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript)
|
||||
- [Learn Power Apps component framework](https://learn.microsoft.com/en-us/training/paths/use-power-apps-component-framework)
|
||||
87
instructions/pcf-overview.instructions.md
Normal file
87
instructions/pcf-overview.instructions.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
description: 'Power Apps Component Framework overview and fundamentals'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Power Apps Component Framework Overview
|
||||
|
||||
Power Apps component framework empowers professional developers and app makers to create code components for model-driven and canvas apps. These code components can be used to enhance the user experience for users working with data on forms, views, dashboards, and canvas app screens.
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
You can use PCF to:
|
||||
- Replace a column on a form that displays a numeric text value with a `dial` or `slider` code component
|
||||
- Transform a list into an entirely different visual experience bound to the dataset, like a `Calendar` or `Map`
|
||||
|
||||
## Important Limitations
|
||||
|
||||
- Power Apps component framework works only on Unified Interface and not on the legacy web client
|
||||
- Power Apps component framework is currently not supported for on-premises environments
|
||||
|
||||
## How PCF Differs from Web Resources
|
||||
|
||||
Unlike HTML web resources, code components are:
|
||||
- Rendered as part of the same context
|
||||
- Loaded at the same time as any other components
|
||||
- Provide a seamless experience for the user
|
||||
|
||||
Code components can be:
|
||||
- Used across the full breadth of Power Apps capabilities
|
||||
- Reused many times across different tables and forms
|
||||
- Bundled with all HTML, CSS, and TypeScript files into a single solution package
|
||||
- Moved across environments
|
||||
- Made available via AppSource
|
||||
|
||||
## Key Advantages
|
||||
|
||||
### Rich Framework APIs
|
||||
- Component lifecycle management
|
||||
- Contextual data and metadata access
|
||||
- Seamless server access via Web API
|
||||
- Utility and data formatting methods
|
||||
- Device features: camera, location, microphone
|
||||
- User experience elements: dialogs, lookups, full-page rendering
|
||||
|
||||
### Development Benefits
|
||||
- Support for modern web practices
|
||||
- Optimized for performance
|
||||
- High reusability
|
||||
- Bundle all files into a single solution file
|
||||
- Handle being destroyed and reloaded for performance reasons while preserving state
|
||||
|
||||
## Licensing Requirements
|
||||
|
||||
Power Apps component framework licensing is based on the type of data and connections used:
|
||||
|
||||
### Premium Code Components
|
||||
Code components that connect to external services or data directly via the user's browser client (not through connectors):
|
||||
- Considered premium components
|
||||
- Apps using these become premium
|
||||
- End-users require Power Apps licenses
|
||||
|
||||
Declare as premium by adding to manifest:
|
||||
```xml
|
||||
<external-service-usage enabled="true">
|
||||
<domain>www.microsoft.com</domain>
|
||||
</external-service-usage>
|
||||
```
|
||||
|
||||
### Standard Code Components
|
||||
Code components that don't connect to external services or data:
|
||||
- Apps using these with standard features remain standard
|
||||
- End-users require minimum Office 365 license
|
||||
|
||||
**Note**: If using code components in model-driven apps connected to Microsoft Dataverse, end users will require Power Apps licenses.
|
||||
|
||||
## Related Resources
|
||||
|
||||
- [What are code components?](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/custom-controls-overview)
|
||||
- [Code components for canvas apps](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/component-framework-for-canvas-apps)
|
||||
- [Create and build a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/create-custom-controls-using-pcf)
|
||||
- [Learn Power Apps component framework](https://learn.microsoft.com/en-us/training/paths/use-power-apps-component-framework)
|
||||
- [Use code components in Power Pages](https://learn.microsoft.com/en-us/power-apps/maker/portals/component-framework)
|
||||
|
||||
## Training Resources
|
||||
|
||||
- [Create components with Power Apps Component Framework - Training](https://learn.microsoft.com/en-us/training/paths/create-components-power-apps-component-framework/)
|
||||
- [Microsoft Certified: Power Platform Developer Associate](https://learn.microsoft.com/en-us/credentials/certifications/power-platform-developer-associate/)
|
||||
126
instructions/pcf-power-pages.instructions.md
Normal file
126
instructions/pcf-power-pages.instructions.md
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
description: 'Using code components in Power Pages sites'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Use Code Components in Power Pages
|
||||
|
||||
Power Pages now support controls built for model-driven apps created using Power Apps component framework. To use code components in Power Pages site webpages:
|
||||
|
||||
|
||||
|
||||
After completing these steps, users can interact with the code component using the webpage that has the respective [form](https://learn.microsoft.com/en-us/power-pages/getting-started/add-form) component.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- You need system administrator privileges to enable the code component feature in the environment
|
||||
- Your Power Pages site version needs to be [9.3.3.x](https://learn.microsoft.com/en-us/power-apps/maker/portals/versions/version-9.3.3.x) or higher
|
||||
- Your starter site package needs to be [9.2.2103.x](https://learn.microsoft.com/en-us/power-apps/maker/portals/versions/package-version-9.2.2103) or higher
|
||||
|
||||
## Create and Package Code Component
|
||||
|
||||
To learn about creating and packaging code components in Power Apps component framework, go to [Create your first component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript).
|
||||
|
||||
### Supported Field Types and Formats
|
||||
|
||||
Power Pages supports restricted field types and formats for using code components. The following table lists all supported field data types and formats:
|
||||
|
||||
**Supported Types:**
|
||||
- Currency
|
||||
- DateAndTime.DateAndTime
|
||||
- DateAndTime.DateOnly
|
||||
- Decimal
|
||||
- Enum
|
||||
- Floating Point Number
|
||||
- Multiple
|
||||
- OptionSet
|
||||
- SingleLine.Email
|
||||
- SingleLine.Phone
|
||||
- SingleLine.Text
|
||||
- SingleLine.TextArea
|
||||
- SingleLine.Ticker
|
||||
- SingleLine.URL
|
||||
- TwoOptions
|
||||
- Whole
|
||||
|
||||
For more information, see [Attributes list and descriptions](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/property#remarks).
|
||||
|
||||
### Unsupported Code Components in Power Pages
|
||||
|
||||
The following code component APIs aren't supported:
|
||||
- [Device.captureAudio](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/device/captureaudio)
|
||||
- [Device.captureImage](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/device/captureimage)
|
||||
- [Device.captureVideo](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/device/capturevideo)
|
||||
- [Device.getBarcodeValue](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/device/getbarcodevalue)
|
||||
- [Device.getCurrentPosition](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/device/getcurrentposition)
|
||||
- [Device.pickFile](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/device/pickfile)
|
||||
- [Utility](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/utility)
|
||||
|
||||
**Additional Restrictions:**
|
||||
- The [uses-feature](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/uses-feature) element must not be set to true
|
||||
- [Value elements not supported](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/property#value-elements-that-are-not-supported) by Power Apps component framework
|
||||
- Power Apps Component Framework (PCF) controls bound to multiple fields in a form isn't supported
|
||||
|
||||
## Add a Code Component to a Field in a Model-Driven App
|
||||
|
||||
To learn how to add a code component to a field in a model-driven app, go to [Add a code component to a field](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/add-custom-controls-to-a-field-or-entity#add-a-code-component-to-a-column).
|
||||
|
||||
> **Important**: Code components for Power Pages are available for web browsers using the client option of **Web**.
|
||||
|
||||
### Add Using Data Workspace
|
||||
|
||||
You can also add a code component to a form using [Data workspace](https://learn.microsoft.com/en-us/power-pages/configure/data-workspace-forms).
|
||||
|
||||
1. When editing a Dataverse form in the Data workspace form designer, select a field
|
||||
2. Choose **+ Component** and select an appropriate component for the field
|
||||
|
||||
|
||||
|
||||
3. Select **Save** and **Publish form**
|
||||
|
||||
## Configure Power Pages Site for Code Component
|
||||
|
||||
After the code component is added to a field in a model-driven app, you can configure Power Pages to use the code component on a form.
|
||||
|
||||
There are two methods to enable the code component:
|
||||
|
||||
### Enable Code Component in Design Studio
|
||||
|
||||
To enable a code component on a form using the design studio:
|
||||
|
||||
1. After you [add the form to a page](https://learn.microsoft.com/en-us/power-pages/getting-started/add-form), select the field where you added the code component and select **Edit field**
|
||||
2. Select the **Enable custom component** field
|
||||
|
||||
|
||||
|
||||
3. When you preview the site, you should see the custom component enabled
|
||||
|
||||
### Enable Code Component in Portals Management App
|
||||
|
||||
To add a code component to a basic form by using the Portals Management app:
|
||||
|
||||
1. Open the [Portals Management](https://learn.microsoft.com/en-us/power-pages/configure/portal-management-app) app
|
||||
2. On the left pane, select **Basic Forms**
|
||||
3. Select the form to which you want to add the code component
|
||||
4. Select **Related**
|
||||
5. Select **Basic Form Metadata**
|
||||
6. Select **New Basic Form Metadata**
|
||||
7. Select **Type** as **Attribute**
|
||||
8. Select **Attribute Logical Name**
|
||||
9. Enter **Label**
|
||||
10. For **Control Style**, select **Code Component**
|
||||
11. Save and close the form
|
||||
|
||||
## Code Components Using the Portal Web API
|
||||
|
||||
A code component can be built and added to a webpage that can use the [portal Web API](https://learn.microsoft.com/en-us/power-pages/configure/web-api-overview) to perform create, retrieve, update, and delete actions. This feature allows greater customization options when developing portal solutions. For more information, see [Implement a sample portal Web API component](https://learn.microsoft.com/en-us/power-pages/configure/implement-webapi-component).
|
||||
|
||||
## Next Steps
|
||||
|
||||
[Tutorial: Use code components in portals](https://learn.microsoft.com/en-us/power-pages/configure/component-framework-tutorial)
|
||||
|
||||
## See Also
|
||||
|
||||
- [Power Apps component framework overview](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/overview)
|
||||
- [Create your first component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript)
|
||||
- [Add code components to a column or table in model-driven apps](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/add-custom-controls-to-a-field-or-entity)
|
||||
123
instructions/pcf-react-platform-libraries.instructions.md
Normal file
123
instructions/pcf-react-platform-libraries.instructions.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
description: 'React controls and platform libraries for PCF components'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# React Controls & Platform Libraries
|
||||
|
||||
When you use React and platform libraries, you're using the same infrastructure used by the Power Apps platform. This means you no longer have to package React and Fluent libraries individually for each control. All controls share a common library instance and version to provide a seamless and consistent experience.
|
||||
|
||||
## Benefits
|
||||
|
||||
By reusing the existing platform React and Fluent libraries, you can expect:
|
||||
|
||||
- **Reduced control bundle size**
|
||||
- **Optimized solution packaging**
|
||||
- **Faster runtime transfer, scripting, and control rendering**
|
||||
- **Design and theme alignment with the Power Apps Fluent design system**
|
||||
|
||||
> **Note**: With GA release, all existing virtual controls will continue to function. However, they should be rebuilt and deployed using the latest CLI version (>=1.37) to facilitate future platform React version upgrades.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
As with any component, you must install [Visual Studio Code](https://code.visualstudio.com/Download) and the [Microsoft Power Platform CLI](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/powerapps-cli#install-microsoft-power-platform-cli).
|
||||
|
||||
> **Note**: If you have already installed Power Platform CLI for Windows, make sure you are running the latest version by using the `pac install latest` command. The Power Platform Tools for Visual Studio Code should update automatically.
|
||||
|
||||
## Create a React Component
|
||||
|
||||
> **Note**: These instructions expect that you have created code components before. If you have not, see [Create your first component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript).
|
||||
|
||||
There's a new `--framework` (`-fw`) parameter for the `pac pcf init` command. Set the value of this parameter to `react`.
|
||||
|
||||
### Command Parameters
|
||||
|
||||
| Parameter | Value |
|
||||
|-----------|-------|
|
||||
| --name | ReactSample |
|
||||
| --namespace | SampleNamespace |
|
||||
| --template | field |
|
||||
| --framework | react |
|
||||
| --run-npm-install | true (default) |
|
||||
|
||||
### PowerShell Command
|
||||
|
||||
The following PowerShell command uses the parameter shortcuts and creates a React component project and runs `npm-install`:
|
||||
|
||||
```powershell
|
||||
pac pcf init -n ReactSample -ns SampleNamespace -t field -fw react -npm
|
||||
```
|
||||
|
||||
You can now build and view the control in the test harness as usual using `npm start`.
|
||||
|
||||
After you build the control, you can package it inside solutions and use it for model-driven apps (including custom pages) and canvas apps like standard code components.
|
||||
|
||||
## Differences from Standard Components
|
||||
|
||||
### ControlManifest.Input.xml
|
||||
|
||||
The [control element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/control) `control-type` attribute is set to `virtual` rather than `standard`.
|
||||
|
||||
> **Note**: Changing this value does not convert a component from one type to another.
|
||||
|
||||
Within the [resources element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/resources), find two new [platform-library element](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/platform-library) child elements:
|
||||
|
||||
```xml
|
||||
<resources>
|
||||
<code path="index.ts" order="1" />
|
||||
<platform-library name="React" version="16.14.0" />
|
||||
<platform-library name="Fluent" version="9.46.2" />
|
||||
</resources>
|
||||
```
|
||||
|
||||
> **Note**: For more information about valid platform library versions, see Supported platform libraries list.
|
||||
|
||||
**Recommendation**: We recommend using platform libraries for Fluent 8 and 9. If you don't use Fluent, you should remove the `platform-library` element where the `name` attribute value is `Fluent`.
|
||||
|
||||
### Index.ts
|
||||
|
||||
The [ReactControl.init](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/react-control/init) method for control initialization doesn't have `div` parameters because React controls don't render the DOM directly. Instead [ReactControl.updateView](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/react-control/updateview) returns a ReactElement that has the details of the actual control in React format.
|
||||
|
||||
### bundle.js
|
||||
|
||||
React and Fluent libraries aren't included in the package because they're shared, therefore the size of bundle.js is smaller.
|
||||
|
||||
## Sample Controls
|
||||
|
||||
The following controls are included in the samples. They function the same as their standard versions but offer better performance since they are virtual controls.
|
||||
|
||||
| Sample | Description | Link |
|
||||
|--------|-------------|------|
|
||||
| ChoicesPickerReact | The standard ChoicesPickerControl converted to be a React Control | ChoicesPickerReact Sample |
|
||||
| FacepileReact | The ReactStandardControl converted to be a React Control | FacepileReact |
|
||||
|
||||
## Supported Platform Libraries List
|
||||
|
||||
Platform libraries are made available both at the build and runtime to the controls that are using platform libraries capability. Currently, the following versions are provided by the platform and are the highest currently supported versions.
|
||||
|
||||
| Library | Package | Build Version | Runtime Version |
|
||||
|---------|---------|---------------|-----------------|
|
||||
| React | react | 16.14.0 | 17.0.2 (Model), 16.14.0 (Canvas) |
|
||||
| Fluent | @fluentui/react | 8.29.0 | 8.29.0 |
|
||||
| Fluent | @fluentui/react | 8.121.1 | 8.121.1 |
|
||||
| Fluent | @fluentui/react-components | >=9.4.0 <=9.46.2 | 9.68.0 |
|
||||
|
||||
> **Note**: The application might load a higher compatible version of a platform library at runtime, but the version might not be the latest version available. Fluent 8 and Fluent 9 are each supported but can not both be specified in the same manifest.
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: Can I convert an existing standard control to a React control using platform libraries?
|
||||
|
||||
A: No. You must create a new control using the new template and then update the manifest and index.ts methods. For reference, compare the standard and react samples described above.
|
||||
|
||||
### Q: Can I use React controls & platform libraries with Power Pages?
|
||||
|
||||
A: No. React controls & platform libraries are currently only supported for canvas and model-driven apps. In Power Pages, React controls don't update based on changes in other fields.
|
||||
|
||||
## Related Articles
|
||||
|
||||
- [What are code components?](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/custom-controls-overview)
|
||||
- [Code components for canvas apps](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/component-framework-for-canvas-apps)
|
||||
- [Create and build a code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/create-custom-controls-using-pcf)
|
||||
- [Learn Power Apps component framework](https://learn.microsoft.com/en-us/training/paths/use-power-apps-component-framework)
|
||||
- [Use code components in Power Pages](https://learn.microsoft.com/en-us/power-apps/maker/portals/component-framework)
|
||||
129
instructions/pcf-sample-components.instructions.md
Normal file
129
instructions/pcf-sample-components.instructions.md
Normal file
@@ -0,0 +1,129 @@
|
||||
---
|
||||
description: 'How to use and run PCF sample components from the PowerApps-Samples repository'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# How to Use the Sample Components
|
||||
|
||||
All the sample components listed under this section are available to download from [github.com/microsoft/PowerApps-Samples/tree/master/component-framework](https://github.com/microsoft/PowerApps-Samples/tree/master/component-framework) so that you can try them out in your model-driven or canvas apps.
|
||||
|
||||
The individual sample component topics under this section provide you an overview of the sample component, its visual appearance, and a link to the complete sample component.
|
||||
|
||||
## Before You Can Try the Sample Components
|
||||
|
||||
To try the sample components, you must first:
|
||||
|
||||
- [Download](https://docs.github.com/repositories/working-with-files/using-files/downloading-source-code-archives#downloading-source-code-archives-from-the-repository-view) or [clone](https://docs.github.com/repositories/creating-and-managing-repositories/cloning-a-repository) this repository [github.com/microsoft/PowerApps-Samples](https://github.com/microsoft/PowerApps-Samples).
|
||||
- Install [Install Power Platform CLI for Windows](https://learn.microsoft.com/en-us/power-platform/developer/cli/introduction#install-power-platform-cli-for-windows).
|
||||
|
||||
## Try the Sample Components
|
||||
|
||||
Follow the steps in the [README.md](https://github.com/microsoft/PowerApps-Samples/blob/master/component-framework/README.md) to generate solutions containing the controls so you can import and try the sample components in your model-driven or canvas app.
|
||||
|
||||
## How to Run the Sample Components
|
||||
|
||||
Use the following steps to import and try the sample components in your model-driven or canvas app.
|
||||
|
||||
### Step-by-Step Process
|
||||
|
||||
1. **Download or clone the repository**
|
||||
- [Download](https://docs.github.com/repositories/working-with-files/using-files/downloading-source-code-archives#downloading-source-code-archives-from-the-repository-view) or [clone](https://docs.github.com/repositories/creating-and-managing-repositories/cloning-a-repository) [github.com/microsoft/PowerApps-Samples](https://github.com/microsoft/PowerApps-Samples).
|
||||
|
||||
2. **Open Developer Command Prompt**
|
||||
- Open a [Developer Command Prompt for Visual Studio](https://learn.microsoft.com/visualstudio/ide/reference/command-prompt-powershell) and navigate to the `component-framework` folder.
|
||||
- On Windows, you can type `developer command prompt` in Start to open a developer command prompt.
|
||||
|
||||
3. **Install dependencies**
|
||||
- Navigate to the component you want to try, for example `IncrementControl`, and run:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
4. **Restore project**
|
||||
- After the command has completed, run:
|
||||
```bash
|
||||
msbuild /t:restore
|
||||
```
|
||||
|
||||
5. **Create solution folder**
|
||||
- Create a new folder inside the sample component folder:
|
||||
```bash
|
||||
mkdir IncrementControlSolution
|
||||
```
|
||||
|
||||
6. **Navigate to solution folder**
|
||||
```bash
|
||||
cd IncrementControlSolution
|
||||
```
|
||||
|
||||
7. **Initialize solution**
|
||||
- Inside the folder you created, run the `pac solution init` command:
|
||||
```bash
|
||||
pac solution init --publisher-name powerapps_samples --publisher-prefix sample
|
||||
```
|
||||
> **Note**: This command creates a new file named `IncrementControlSolution.cdsproj` in the folder.
|
||||
|
||||
8. **Add component reference**
|
||||
- Run the `pac solution add-reference` command with the `path` set to the location of the `.pcfproj` file:
|
||||
```bash
|
||||
pac solution add-reference --path ../../IncrementControl
|
||||
```
|
||||
or
|
||||
```bash
|
||||
pac solution add-reference --path ../../IncrementControl/IncrementControl.pcfproj
|
||||
```
|
||||
> **Important**: Reference the folder that contains the `.pcfproj` file for the control you want to add.
|
||||
|
||||
9. **Build the solution**
|
||||
- To generate a zip file from your solution project, run the following three commands:
|
||||
```bash
|
||||
msbuild /t:restore
|
||||
msbuild /t:rebuild /restore /p:Configuration=Release
|
||||
msbuild
|
||||
```
|
||||
- The generated solution zip file becomes in the `IncrementControlSolution\bin\debug` folder.
|
||||
|
||||
10. **Import the solution**
|
||||
- Now that you have the zip file, you have two options:
|
||||
- Manually [import the solution](https://learn.microsoft.com/powerapps/maker/data-platform/import-update-export-solutions) into your environment using [make.powerapps.com](https://make.powerapps.com/).
|
||||
- Alternatively, to import the solution using Power Apps CLI commands, see the [Connecting to your environment](https://learn.microsoft.com/powerapps/developer/component-framework/import-custom-controls#connecting-to-your-environment) and [Deployment](https://learn.microsoft.com/powerapps/developer/component-framework/import-custom-controls#deploying-code-components) sections.
|
||||
|
||||
11. **Add components to apps**
|
||||
- Finally, to add code components to your model-driven and canvas apps, see:
|
||||
- [Add components to model-driven apps](https://learn.microsoft.com/powerapps/developer/component-framework/add-custom-controls-to-a-field-or-entity)
|
||||
- [Add components to canvas apps](https://learn.microsoft.com/powerapps/developer/component-framework/component-framework-for-canvas-apps#add-components-to-a-canvas-app)
|
||||
|
||||
## Available Sample Components
|
||||
|
||||
The repository contains numerous sample components including:
|
||||
|
||||
- AngularJSFlipControl
|
||||
- CanvasGridControl
|
||||
- ChoicesPickerControl
|
||||
- ChoicesPickerReactControl
|
||||
- CodeInterpreterControl
|
||||
- ControlStateAPI
|
||||
- DataSetGrid
|
||||
- DeviceApiControl
|
||||
- FacepileReactControl
|
||||
- FluentThemingAPIControl
|
||||
- FormattingAPIControl
|
||||
- IFrameControl
|
||||
- ImageUploadControl
|
||||
- IncrementControl
|
||||
- LinearInputControl
|
||||
- LocalizationAPIControl
|
||||
- LookupSimpleControl
|
||||
- MapControl
|
||||
- ModelDrivenGridControl
|
||||
- MultiSelectOptionSetControl
|
||||
- NavigationAPIControl
|
||||
- ObjectOutputControl
|
||||
- PowerAppsGridCustomizerControl
|
||||
- PropertySetTableControl
|
||||
- ReactStandardControl
|
||||
- TableControl
|
||||
- TableGrid
|
||||
- WebAPIControl
|
||||
|
||||
Each sample demonstrates different aspects of the Power Apps component framework and can serve as a learning resource or starting point for your own components.
|
||||
17
instructions/pcf-tooling.instructions.md
Normal file
17
instructions/pcf-tooling.instructions.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
description: 'Get Microsoft Power Platform CLI tooling for Power Apps Component Framework'
|
||||
applyTo: '**/*.{ts,tsx,js,json,xml,pcfproj,csproj}'
|
||||
---
|
||||
|
||||
# Get Tooling for Power Apps Component Framework
|
||||
|
||||
Use Microsoft Power Platform CLI (command-line interface) to create, debug, and deploy code components using Power Apps component framework. Microsoft Power Platform CLI enables developers to create code components quickly. In the future, it will be expanded to include support for additional development and application life cycle management (ALM) experiences.
|
||||
|
||||
More information: [Install Microsoft Power Platform CLI](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/powerapps-cli)
|
||||
|
||||
> **Important**: To deploy your code component using Microsoft Power Platform CLI, you must have a Microsoft Dataverse environment with system administrator or system customizer privileges.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Create your first code component](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/implementing-controls-using-typescript)
|
||||
- [Learn Power Apps component framework](https://learn.microsoft.com/en-us/training/paths/use-power-apps-component-framework)
|
||||
Reference in New Issue
Block a user