|
| 1 | +# Adaptive Card Designer Host |
| 2 | + |
| 3 | +This control allows you to embed the official Adaptive Cards designer inside a React SPFx solution. |
| 4 | + |
| 5 | +The control consists of 2 components: |
| 6 | + |
| 7 | +* **AdaptiveCardDesigner**: implements all the logic to embed the designer control as a React component; |
| 8 | +* **AdaptiveCardDesignerHost**: main control to render the designer in a full page Fluent UI panel; |
| 9 | + |
| 10 | +**Due to the nature in which the original Adaptive Card Designer control was implemented**, it is not possible at this time to adapt it to the current theme applied to the site and especially to localize it to give multilingual support. **The designer, therefore, is only available in the English language**. |
| 11 | + |
| 12 | +This control shares a lot of code with another control in this library, the "AdaptiveCardHost" control. In this way you have a uniformity of display between the cards created with this designer and those rendered with "AdaptiveCardHost". The same thing goes for the various HostContainer objects, so that you can test the cards with the themes available for "AdaptiveCardHost". |
| 13 | + |
| 14 | +The Adaptive Cards version supported is 1.5, by using the 'adaptivecards' npm package version 2.10.0. |
| 15 | + |
| 16 | +All Inputs Elements and Actions of Adaptive Cards have been redefined using Fluent UI React, adding and improving features that are not managed in Microsoft's implementation of the "adaptivecards-fluentui" library (Theme support for example). |
| 17 | + |
| 18 | +Thanks to the "context" property that allows you to pass the SPFx context, whether the "data" property is passed or not, a new field called @context will be injected into the data object. |
| 19 | + |
| 20 | +This allows, using Adaptive Cards templating syntax and binding feature of the Designer, to access to the context informations. |
| 21 | + |
| 22 | +For more info please to refear tot he documentation of [AdaptiveCardHost ](http://www.google.com)control |
| 23 | + |
| 24 | +Here is an example of the control in action inside a Web Part: |
| 25 | + |
| 26 | + |
| 27 | + |
| 28 | +## How to use this control in your solutions |
| 29 | + |
| 30 | +* Check that you installed the `@pnp/spfx-controls-react` dependency. Check out the [getting started](../../#getting-started) page for more information about installing the dependency. |
| 31 | + |
| 32 | +* In your component file, import the `AdaptiveCardDesignerHost` control as follows: |
| 33 | +```Typescript |
| 34 | +import { AdaptiveCardDesignerHost, HostContainer, BindingPreviewMode, Versions } from "@pnp/spfx-controls-react/lib/AdaptiveCardDesignerHost"; |
| 35 | +``` |
| 36 | + |
| 37 | +- Example on use the `AdaptiveCardDesignerHost` control with only required properties: |
| 38 | +```Typescript |
| 39 | +<AdaptiveCardDesignerHost |
| 40 | + headerText="Adaptive Card Designer" |
| 41 | + buttonText="Open the Designer" |
| 42 | + context={props.context} |
| 43 | + onSave={(payload: object) => setCard(payload)} |
| 44 | +/> |
| 45 | +``` |
| 46 | + |
| 47 | +- Example on use the `AdaptiveCardDesignerHost` control with all properties: |
| 48 | +```Typescript |
| 49 | +<AdaptiveCardDesignerHost |
| 50 | + headerText="Adaptive Card Designer" |
| 51 | + buttonText="Open the Designer" |
| 52 | + context={props.context} |
| 53 | + onSave={(payload: object) => setCard(payload)} |
| 54 | + addDefaultAdaptiveCardHostContainer={true} |
| 55 | + bindingPreviewMode={BindingPreviewMode.SampleData} |
| 56 | + theme={props.theme} |
| 57 | + card={card} |
| 58 | + data={data} |
| 59 | + enableDataBindingSupport={true} |
| 60 | + hostConfig={hostConfig} |
| 61 | + hostContainers={[]} |
| 62 | + injectAdaptiveCardHostContextProperty={true} |
| 63 | + newCardPayload={newCard} |
| 64 | + selectedHostContainerControlsTargetVersion={false} |
| 65 | + showCopyToJsonToolbarCommand={true} |
| 66 | + showDataStructureToolbox={true} |
| 67 | + showFluentBreakpointsPicker={true} |
| 68 | + showSampleDataEditorToolbox={true} |
| 69 | + showTargetVersionMismatchWarning={true} |
| 70 | + showVersionPicker={true} |
| 71 | + supportedTargetVersions={[Versions.v1_5]} |
| 72 | + snippets={snippets} |
| 73 | +/> |
| 74 | +``` |
| 75 | +## Implementation |
| 76 | + |
| 77 | +The `AdaptiveCardDesignerHost` control can be configured with the following properties: |
| 78 | + |
| 79 | +| Property | Type | Required | Description | Default Value | |
| 80 | +| ---- | ---- | ---- | ---- | ---- | |
| 81 | +| context | BaseComponentContext | true | Set the context from SPFx component | - | |
| 82 | +| theme | IPartialTheme or ITheme | false | Set Fluent UI Theme | - | |
| 83 | +| onSave | (payload: object) => void | true | Callback for saving the card | - | |
| 84 | +| card | object | false | Set Adaptive Card payload | - | |
| 85 | +| data | { "$root": object } | false | Set Data Source for template rendering | - | |
| 86 | +| newCardPayload | object | false | Set Adaptive Card payload for the New Card | - | |
| 87 | +| hostContainers | HostContainer[] | false | Set custom HostContainers | [] | |
| 88 | +| supportedTargetVersions | Version[] | false | Set the suported Versions | [Versions.v1_5] | |
| 89 | +| snippets | IToolboxSnippet[] | false | Set the Toolbox Snippets | [] | |
| 90 | +| bindingPreviewMode | BindingPreviewMode | false | Set the Binding preview mode | BindingPreviewMode.GeneratedData | |
| 91 | +| enableDataBindingSupport | boolean | false | Enable the support for Data Binding | true | |
| 92 | +| selectedHostContainerControlsTargetVersion | boolean | false | Enable the support for Data Binding | false | |
| 93 | +| showTargetVersionMismatchWarning | boolean | false | Show the target version mismatch warning | true | |
| 94 | +| showVersionPicker | boolean | false | Show the Version Picker | false | |
| 95 | +| showSampleDataEditorToolbox | boolean | false | Show the Sample Data Editor Toolbox | false | |
| 96 | +| showDataStructureToolbox | boolean | false | Show the Data Structure Toolbox | true | |
| 97 | +| showFluentBreakpointsPicker | boolean | false | Show the Fluent UI Breakpoint Picker | true | |
| 98 | +| showCopyToJsonToolbarCommand | boolean | false | Show the copy to json button | false | |
| 99 | +| addDefaultAdaptiveCardHostContainer | boolean | false | Add the default Host Containers to the Picker | true | |
| 100 | +| injectAdaptiveCardHostContextProperty | boolean | false | Inject the SPFx Context Property inside the Adaptive Card data object | true | |
| 101 | +| headerText | boolean | false | Set the Header text for the Adaptive Card Designer | - | |
| 102 | +| buttonText | boolean | false | Set the Button text for open the Adaptive Card Designer | - | |
| 103 | + |
| 104 | + |
0 commit comments