diff --git a/content/en/docs/marketplace/platform-supported-content/widgets/richtext/_index.md b/content/en/docs/marketplace/platform-supported-content/widgets/richtext/_index.md index 168d736c722..56fc058c02c 100644 --- a/content/en/docs/marketplace/platform-supported-content/widgets/richtext/_index.md +++ b/content/en/docs/marketplace/platform-supported-content/widgets/richtext/_index.md @@ -93,7 +93,9 @@ To configure this widget, follow these steps: * **Syntax** - items: blockquote, codesample, codeblock, (view/edit)code * **Font colors** - items: fontfamily, fontsize, forecolor, backcolor * **Content type** - items: header + * **View** - items: fullscreen * **Removal** - items: clear + * **Table** - items: table * **Advanced** – if selected, you can configure buttons for different toolbar groups {{% alert color="info" %}}All the toolbar groups that you configure will be available in the toolbar. With vertical bars or separator options ("|"), you can separate different toolbar groups.{{% /alert %}} @@ -128,8 +130,144 @@ To configure this widget, follow these steps: ### Advanced Tab -* **Enable spell checking** – configures to use the browser’s native spell checker +* **Enable spell checking** – configures to use the browser’s native spell checker. +* **Custom fonts** – configures extra fonts selection for the font family. +* **Selectable images** – configures image entity source to allow rich text to use images from entity instead of base64 string. +* **Enable default upload** – if enabled, it will keep the current image upload method using base64 string, otherwise it is hidden (default value: true). ### Common Tab For more information, see [Common Section](/refguide/common-widget-properties/#common-properties) in *Properties Common in the Page Editor*. + + +## Advance configuration + +### Custom fonts + +This advance configuration allows you to add extra font list to the font family selection in Rich Text widget. + +#### Prerequisite +Prior to adding new font, font files and font family have to be already included in your project. + +* **Adding font files** +To add font files into the project, you can put the font files inside your styles/web directory. + +* **Define font family in styling** +You will need to define the new font by adding the font face custom styling. +```css +@font-face { + font-family: 'Your-font-family-name'; + src: url('YourFontFile.ttf') format('truetype'); + font-weight: 100; + font-style: normal; +} +``` + +#### Adding a custom font into rich text +{{% alert color="info" %}}This feature is available from Rich Text version 4.7.0 and above.{{% /alert %}} +To add a new custom font, simply go to advance tab and click new on custom font. + +* **Font name** – this is the font name that will be use to display the font on font-family selection in Rich Text toolbar. +* **Font style** – this is the font-family declaration that you have set previously in font-face styling. + +#### Display custom font with correct styling in the toolbar +This is an optional configuration that user can do to display the custom fonts in it's own styling on the font-family toolbar selection. + +* **Font name variable** +The new font name will be display in the toolbar with data-value attribute as `data-value="your-font-name"`. +The name will be derrived from **Font name** configuration by set it to lower case, and replace all space(" ") with dash("-"). +You can use this following custom styling to display it correctly in the toolbar: + +```css +.widget-rich-text .ql-toolbar [data-value=your-font-name]:before { + font-family: 'Your-font-family-name'; +} +``` + + +### Image from entity +{{% alert color="info" %}}This feature is available from Rich Text version 4.8.0 and above.{{% /alert %}} +The default image upload and selection method of Rich Text is to use base64 string as the image source.\ +This has found to be troublesome if the image size is too large that causes the string value attribute to be big. +By using image source from entity, Rich Text will use the image url instead of base64. + + +#### Using file uploader widget +The default and recommended way of uploading and selecting images from entity in Rich Text widget is to use [File Uploader](/appstore/modules/file-uploader/) module. + +##### Prerequisite +Entity that being used for Rich Text data source value attribute have to use FileUploadContext entity generalization. +{{< figure src="/attachments/appstore/platform-supported-content/widgets/rich-text/entity-with-file-upload-context.png" alt="Rich text entity with FileUploadContext generalization" >}} + +##### Configuration +* **Selectable images**\ + Rich text needs to know the source of image entity to be display.\ + On the **advance tab > selectable images**, choose association to **UploadedImage_FileUploadContext/UploadedImage** entity.\ + By selecting this, Rich Text will display a dropzone for image upload widget. + +* **Configuring the image upload widget** + - Drag and drop File Uploader widget to the available image upload dropzone underneath Rich Text widget. + - Open File Uploader widget configuration and select Images as **Upload mode** + - On the advace tab of File Uploader widget, set **Enable custom buttons** "Yes" and add a custom buttons. + - Set **Default file action** to "Yes" on the custom button and call the [nanoflow to select images](#configuring-image-selection-nanoflow) as the action. + +#### Using other widget as image selector +User can also configure to use another widget as the image selector for Rich Text.\ +This widget have to has access to the System.Image object. + +##### Prerequisite + +* Entity that being used for Rich Text data source value attribute have to use has association to System.Image entity. + +{{< figure src="/attachments/appstore/platform-supported-content/widgets/rich-text/entity-with-system-image.png" alt="Rich text entity with FileUploadContext generalization" >}} + +* The custom widget needs to have access to the System.Image object and able to call nanoflow action when image being selected. +* It is not mandatory that the custom widget have upload image function (e.g, using gallery and [Image](/appstore/widgets/image/) widget with onClick is also possible), because Rich Text widget only need the selection action call. + +##### Configuration +* **Selectable images** + Rich text needs to know the source of image entity to be display.\ + On the **advance tab > selectable images**, choose association to the **System.Image** entity.\ + By selecting this, Rich Text will display a dropzone for image upload widget. + +* **Configuring the image upload widget** + - Drag and drop the custom widget to the available image upload dropzone underneath Rich Text widget. + - Use the same **System.Image** association as the datasource. + - Set the action to call the [nanoflow to select images](#configuring-image-selection-nanoflow) as necessary. + +#### Configuring image selection nanoflow +The nanoflow is needed to trigger image object selection and returning the flow back to Rich Text widget. + +{{< figure src="/attachments/appstore/platform-supported-content/widgets/rich-text/image-selection-nanoflow.png" alt="Image selection nanoflow" >}} + +* **Nanoflow parameter** +The nanoflow needs to have access to the **System.Image** entity. Set this as the parameter. +In case of using File Uploader, this should be automatically set up when creating the nanoflow from custom action button. + +* **Getting the object GUID** +The first step of the nanoflow is to get the GUID from the image object. Set call to javascript action GetGuid provided by [Nanoflow Commons](/appstore/modules/nanoflow-commons/) module. + +* **Trigger image selection javascript** +This step is required to pass the GUID of the image object back to Rich Text. +Create a new javascript action and add a string parameter. +In this example, we will name the parameter *fileGuid* and *selectImage* as the Javascript action. + +{{< figure src="/attachments/appstore/platform-supported-content/widgets/rich-text/js-action-setup.png" alt="Javascript action configuration" >}} + +Use the following code in the javascript action: + +```Javascript +export async function selectImage(fileGuid) { + // BEGIN USER CODE + const img = { + id: fileGuid, + url: mx.data.getDocumentUrl(fileGuid, Date.now(), false) + } + const customEvent = new CustomEvent("imageSelected", { bubbles: true, detail: img }); + window.getSelection().anchorNode.dispatchEvent(customEvent); + // END USER CODE +} +``` + +This code will trigger a new Event called "imageSelected" and bubble up the event back to Rich Text widget to continue the flow. +User then can use the image id instead of base64 string as the image source. diff --git a/static/attachments/appstore/platform-supported-content/widgets/rich-text/entity-with-file-upload-context.png b/static/attachments/appstore/platform-supported-content/widgets/rich-text/entity-with-file-upload-context.png new file mode 100644 index 00000000000..49160dea858 Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/widgets/rich-text/entity-with-file-upload-context.png differ diff --git a/static/attachments/appstore/platform-supported-content/widgets/rich-text/entity-with-system-image.png b/static/attachments/appstore/platform-supported-content/widgets/rich-text/entity-with-system-image.png new file mode 100644 index 00000000000..0de7bd41bb0 Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/widgets/rich-text/entity-with-system-image.png differ diff --git a/static/attachments/appstore/platform-supported-content/widgets/rich-text/image-selection-nanoflow.png b/static/attachments/appstore/platform-supported-content/widgets/rich-text/image-selection-nanoflow.png new file mode 100644 index 00000000000..d6a42529cde Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/widgets/rich-text/image-selection-nanoflow.png differ diff --git a/static/attachments/appstore/platform-supported-content/widgets/rich-text/js-action-setup.png b/static/attachments/appstore/platform-supported-content/widgets/rich-text/js-action-setup.png new file mode 100644 index 00000000000..55e553ae6f0 Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/widgets/rich-text/js-action-setup.png differ