|
| 1 | +<!-- |
| 2 | +Copyright 2022 Adobe |
| 3 | +
|
| 4 | +Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | +you may not use this file except in compliance with the License. |
| 6 | +You may obtain a copy of the License at |
| 7 | +
|
| 8 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +
|
| 10 | +Unless required by applicable law or agreed to in writing, software |
| 11 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | +See the License for the specific language governing permissions and |
| 14 | +limitations under the License. |
| 15 | +--> |
| 16 | +Adaptive Form File Input (v2) |
| 17 | +==== |
| 18 | +Adaptive Form File input field component written in HTL. |
| 19 | + |
| 20 | +## Features |
| 21 | + |
| 22 | +* Drag and drop support |
| 23 | +* Custom icon for drag and drop |
| 24 | +* Provides the following type of input: |
| 25 | + * file |
| 26 | +* Custom constraint messages for the above types |
| 27 | +* Styles |
| 28 | + |
| 29 | +### Use Object |
| 30 | +The Form File component uses the `com.adobe.cq.forms.core.components.models.form.FileInput` Sling Model for its Use-object. |
| 31 | + |
| 32 | +### Edit Dialog Properties |
| 33 | +The following properties are written to JCR for this Form File component and are expected to be available as `Resource` properties: |
| 34 | + |
| 35 | +1. `./jcr:title` - defines the label to use for this field |
| 36 | +2. `./hideTitle` - if set to `true`, the label of this field will be hidden |
| 37 | +3. `./name` - defines the name of the field, which will be submitted with the form data |
| 38 | +4. `./default` - defines the default value of the field |
| 39 | +5. `./description` - defines a help message that can be rendered in the field as a hint for the user |
| 40 | +6. `./required` - if set to `true`, this field will be marked as required, not allowing the form to be submitted until the field has a value |
| 41 | +7. `./requiredMessage` - defines the message displayed as tooltip when submitting the form if the value is left empty |
| 42 | +8. `./readOnly` - if set to `true`, the filed will be read only |
| 43 | +9. `./multiSelection` - if set to `true`, the filed will allow to add multiple files in single selection or multiple selections |
| 44 | +10. `./minItems` - if value is selected/provided this will check for minimum number of files that can be attached |
| 45 | +11. `./maxItems` - if value is selected/provided this will check for maximum number of files that can be attached |
| 46 | +12. `./maxFileSize` - if value is selected/provided this will check for maximum file size allowed |
| 47 | +13. `./accept` - defines the type of files accepted to upload |
| 48 | +14. `./showComment` - if set to `true`, comments can be added to attachment |
| 49 | +15. `./minItemsMessage` - defines the message displayed as tooltip when submitting the form if less than allowed minimum files uploaded |
| 50 | +16. `./maxItemsMessage` - defines the message displayed as tooltip when submitting the form if more than allowed maximum files uploaded |
| 51 | +17. `./maxFileSizeMessage` - defines the message displayed as tooltip when submitting the form if the uploaded file size is greater than allowed |
| 52 | +18. `./acceptMessage` - defines the message displayed as tooltip when submitting the form if the uploaded file type is not allowed |
| 53 | + |
| 54 | +## Client Libraries |
| 55 | +The component provides a `core.forms.components.fileinput.v2.runtime` client library category that contains the Javascript runtime for the component. |
| 56 | +It should be added to a relevant site client library using the `embed` property. |
| 57 | + |
| 58 | +It also provides a `core.forms.components.fileinput.v2.editor` editor client library category that includes |
| 59 | +JavaScript handling for dialog interaction. It is already included by its edit dialog. |
| 60 | + |
| 61 | +## BEM Description |
| 62 | +``` |
| 63 | +BLOCK cmp-adaptiveform-fileinput |
| 64 | + ELEMENT cmp-adaptiveform-fileinput__label |
| 65 | + ELEMENT cmp-adaptiveform-fileinput__label-container |
| 66 | + ELEMENT cmp-adaptiveform-fileinput__widget |
| 67 | + ELEMENT cmp-adaptiveform-fileinput__questionmark |
| 68 | + ELEMENT cmp-adaptiveform-fileinput__shortdescription |
| 69 | + ELEMENT cmp-adaptiveform-fileinput__longdescription |
| 70 | + ELEMENT cmp-adaptiveform-fileinput__filelist |
| 71 | + ELEMENT cmp-adaptiveform-fileinput__fileitem |
| 72 | + ELEMENT cmp-adaptiveform-fileinput__filename |
| 73 | + ELEMENT cmp-adaptiveform-fileinput__filedelete |
| 74 | + ELEMENT cmp-adaptiveform-fileinput__widgetlabel |
| 75 | +``` |
| 76 | + |
| 77 | +### Note |
| 78 | +By placing the class names `cmp-adaptiveform-fileinput__label` and `cmp-adaptiveform-fileinput__questionmark` within the `cmp-adaptiveform-fileinput__label-container` class, you create a logical grouping of the label and question mark elements. This approach simplifies the process of maintaining a consistent styling for both elements. |
| 79 | + |
| 80 | +## JavaScript Data Attribute Bindings |
| 81 | + |
| 82 | + |
| 83 | +The following attributes must be added for the initialization of the file-input component in the form view: |
| 84 | + 1. `data-cmp-is="adaptiveFormFileInput"` |
| 85 | + 2. `data-cmp-adaptiveformcontainer-path="${formstructparser.formContainerPath}"` |
| 86 | + |
| 87 | + |
| 88 | +## Information |
| 89 | +* **Vendor**: Adobe |
| 90 | +* **Version**: v2 |
| 91 | +* **Compatibility**: Cloud |
| 92 | +* **Status**: production-ready |
| 93 | + |
0 commit comments