diff --git a/content/en/docs/marketplace/platform-supported-content/modules/image-crop.md b/content/en/docs/marketplace/platform-supported-content/modules/image-crop.md index e1e2ad9b30e..ca5fde3d37c 100644 --- a/content/en/docs/marketplace/platform-supported-content/modules/image-crop.md +++ b/content/en/docs/marketplace/platform-supported-content/modules/image-crop.md @@ -1,10 +1,15 @@ --- title: "Image Crop" +deprecated: true url: /appstore/modules/image-crop/ description: "Describes the configuration and usage of the Image Crop module, which is available in the Mendix Marketplace." #If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. --- +{{% alert color="warning" %}} +This module is deprecated. It is replaced by the [Image Cropper](/appstore/widgets/image-cropper/) widget. +{{% /alert %}} + ## Introduction The [Image Crop](https://marketplace.mendix.com/link/component/254/) module transforms images based on a selection made in the browser. diff --git a/content/en/docs/marketplace/platform-supported-content/widgets/image-cropper.md b/content/en/docs/marketplace/platform-supported-content/widgets/image-cropper.md new file mode 100644 index 00000000000..516099e671d --- /dev/null +++ b/content/en/docs/marketplace/platform-supported-content/widgets/image-cropper.md @@ -0,0 +1,166 @@ +--- +title: "Image Cropper" +url: /appstore/widgets/image-cropper/ +description: "Describes the configuration and usage of the Image Cropper widget, which is available in the Mendix Marketplace." +#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. +--- + +## Introduction + +The [Image Cropper](https://marketplace.mendix.com/link/component/) widget lets an end-user crop, rotate, zoom, and convert an image to grayscale directly in the browser. The edited result is saved back to the same image attribute the widget is bound to. + +All editing is done client-side on an HTML canvas. There is no separate apply or save button: the crop is saved back to the image attribute automatically as the end-user works. + +{{% alert color="info" %}} +This widget replaces the legacy [Image Crop](/appstore/modules/image-crop/) module. +{{% /alert %}} + +{{< figure src="/attachments/appstore/platform-supported-content/widgets/image-cropper/image-cropper-demo.gif" alt="Cropping an image with a rectangular crop shape" class="no-border" >}} + +### Features + +- Crop with a rectangular or circular crop shape +- Constrain the crop to a fixed aspect ratio (1:1, 16:9, 4:3, 3:4), a custom ratio, or a free selection +- Zoom with a slider and/or the mouse wheel +- Rotate the image in 90-degree increments +- Convert the image to grayscale +- Reset the image back to its original state +- Save the result as PNG or JPEG at the source or on-screen resolution +- Trigger a Mendix action each time the crop is applied + +### Limitations + +- The widget requires an editable image attribute and both reads from and writes to that same attribute. There is no separate output attribute. +- Editing operations do not save back to a read-only image attribute. +- The widget is available on the web platform only and is not offline capable. + +## Configuration + +The following sections will describe the different available widget properties and configurations. + +### General Tab {#general} + +#### Source Section + +The **Source** section (required) is used to configure the image the widget edits. It has the following property: + +- **Image attribute** – Specifies the image the end-user wants to crop. + - The cropped result is saved back to this same attribute. + - The attribute is both the source and the destination for the widget. + +#### Crop Area Section + +The **Crop area** section is used to configure the shape and proportions of the crop selection. It includes the following properties: + +* **Crop shape** – Defines the shape of the crop. + * **Rectangle** (default) – When enabled, the full crop rectangle is saved. + * **Circle** – When enabled, the corners are masked and the saved image is clipped to an ellipse inscribed in the crop rectangle. +- **Aspect ratio** – Locks the crop proportions. + * ***Free** (default) – The end-user can resize the selection to any proportion. + * **1:1**, **16:9**, **4:3**, or **3:4** – When set to one of these predetermined ratios, the selection is locked to that ratio during resize. + * ***Custom** – When enabled, the selection is locked to the ratio defined by **Custom aspect width** and **Custom aspect height**. +- **Custom aspect width** (default **1**) – The width side of the ratio (for example, _3_ in 3:2). + - Configurable when **Aspect ratio** is set to **Custom**. + - When either the custom width or custom height is not greater than _0_, the selection falls back to a free-form shape. +- **Custom aspect height** (default **1**) – The height side of the ratio (for example, _2_ in 3:2). + - Configurable when **Aspect ratio** is set to **Custom**. + - When either the custom width or custom height is not greater than _0_, the selection falls back to a free-form shape. + +{{< figure src="/attachments/appstore/platform-supported-content/widgets/image-cropper/image-cropper-circle-demo.gif" alt="Cropping an image with a circular crop shape" class="no-border" >}} + +#### Events Section + +The **Events** section allows you to configure what happens each time the crop is applied. It includes the following property: + +- **On crop** (optional) – A Mendix action that runs each time the crop is auto-applied to the image attribute. + - The action runs after a crop is saved back, but not after a rotation or a reset. + +### Dimensions Tab {#dimensions} + +#### Canvas Section + +The **Canvas** section is used to configure the on-screen size of the crop area. It includes the following properties: + +- **Canvas max width (px)** (default **800**) – Sets the maximum on-screen width of the crop area. + - The image scales down to fit, and the canvas wraps the rendered image so that smaller crops produce a smaller canvas with no blank gaps. + - This property does not change the saved image size. +- **Canvas max height (px)** (default **800**) – the maximum on-screen height of the crop area. + - The image scales down to fit, and the canvas wraps the rendered image so that smaller crops produce a smaller canvas with no blank gaps. + - This property does not change the saved image size. + +### Behavior Tab {#behavior} + +#### Interaction Section + +The **Interaction** section is used to configure how the end-user interacts with the crop selection. It includes the following property: + +- **Resizable handles** (default **Yes**) – Allows the end-user to resize the selection by dragging its corners. + - When set to **No**, the selection cannot be resized by dragging its corners. + +#### Buttons Section + +The **Buttons** section is used to configure the editing buttons shown in the toolbar. It includes the following properties: + +- **Enable rotation** (default **Yes**) – Shows rotate-left and rotate-right buttons that rotate the image in 90-degree increments. + - The rotation is baked into the saved image. +- **Enable grayscale** (default **No**) – Shows a grayscale toggle. + - When the toggle is on, the saved image is converted to grayscale (black and white). +- **Enable reset** (default **Yes**) – Shows a **Reset** button that restores the original image and clears zoom, rotation, and grayscale. + - The button is available only when the original image could be captured. + +#### Zoom Section + +The **Zoom** section is used to configure how the end-user zooms the image. It includes the following properties: + +- **Enable zoom** (default **Yes**) – The primary switch for zooming. + - When set to **No**, the slider and mouse-wheel zoom are disabled and the image stays at **1x**. +- **Show zoom slider** (default **Yes**) – shows the zoom slider below the crop area. + - Configurable when **Enable zoom** is set to **Yes**. + - Turn this off to keep mouse-wheel zoom while hiding the slider. +- **Mouse wheel zoom** (default **On (hold Ctrl)**) – Determines whether the mouse wheel zooms the image. + - Configurable when **Enable zoom** is set to **Yes**. + - When set to **On (hold Ctrl)**, the wheel zooms only while Ctrl is held, so page scroll keeps working. + - When set to **On**, the wheel always zooms. + - When set to **Off**, the wheel never zooms. +- **Minimum zoom** (default **1**) – Sets the smallest zoom level. + - Configurable when **Enable zoom** is set to **Yes**. + - A value of _1_ means the image fits the canvas; a value below _1_ lets the end-user zoom out further. +- **Maximum zoom** (default **4**) – Sets the largest zoom level. + - Configurable when **Enable zoom** is set to **Yes**. + - A value of _4_ means the image can be zoomed up to four times the canvas size. + - This value must be greater than **Minimum zoom**. + +### Output Tab {#output} + +#### Output Section + +The **Output** section is used to configure the format and resolution of the saved image. It includes the following properties: + +- **Output format** (default **PNG**) – Sets the file format of the saved image. + - When set to **PNG**, transparency is preserved and **JPEG quality** is ignored. + - When set to **JPEG**, a white background is filled behind the image and smaller files are produced. +- **JPEG quality (0.0 - 1.0)** (default **0.92**) – Sets the JPEG compression level. + - Configurable when **Output format** is set to **JPEG**. + - A higher value produces a sharper and larger file. +- **Output size** (default **Original (source resolution)**) – Sets the resolution of the saved crop. + - When set to **Original (source resolution)**, the crop is saved at the source resolution of the cropped region, which is the sharpest option. + - When set to **Viewport (canvas dimensions)**, the crop is saved at the on-screen canvas size. + +## Usage + +When the widget loads, it shows the image bound to the **Image attribute** with a default crop box centered on the image and covering 80% of it at the configured aspect ratio. If no image is available, the widget shows a **No image** message. + +The end-user edits the image as follows: + +- **Move or resize the crop box** – The crop is saved immediately when the end-user finishes the drag. +- **Zoom or toggle grayscale** – The change is saved a short moment after the last adjustment. +- **Rotate** – A live preview is shown immediately, and the rotation is then saved back to the image attribute. +- **Reset** – The original image is restored and zoom, rotation, and grayscale are cleared. A reset is not saved as a crop and does not trigger the **On crop** action. + +## Styling + +The widget is shipped with default styles and works out of the box without Atlas UI. + +## Read More + +- [Image](/appstore/widgets/image/) diff --git a/static/attachments/appstore/platform-supported-content/widgets/image-cropper/image-cropper-circle-demo.gif b/static/attachments/appstore/platform-supported-content/widgets/image-cropper/image-cropper-circle-demo.gif new file mode 100644 index 00000000000..582c373e410 Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/widgets/image-cropper/image-cropper-circle-demo.gif differ diff --git a/static/attachments/appstore/platform-supported-content/widgets/image-cropper/image-cropper-demo.gif b/static/attachments/appstore/platform-supported-content/widgets/image-cropper/image-cropper-demo.gif new file mode 100644 index 00000000000..22fe6f377b2 Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/widgets/image-cropper/image-cropper-demo.gif differ