[MGNLUI-6215] DOC: Restructure uploadField documentation Created: 16/Sep/20  Updated: 18/Jan/22  Resolved: 18/Nov/20

Status: Closed
Project: Magnolia UI
Component/s: None
Affects Version/s: 6.2.4
Fix Version/s: None

Type: Task Priority: Neutral
Reporter: Šimon Demočko Assignee: Ashraf Khamis
Resolution: Done Votes: 0
Labels: fields, new-UI-framework, new-form
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Relates
relates to MGNLUI-7017 Model content with file/binary proper... Accepted
documentation
documents MGNLDAM-880 CLONE - 2 or more DamUploadFields can... Closed
documents MGNLUI-5886 2 or more UploadFields cannot be used... Closed
Template:
Acceptance criteria:
Empty
Task DoR:
Empty
Date of First Response:
Epic Link: UI framework: forms, dialogs, content editing
Sprint: UI FW 14, UI FW 15
Story Points: 5

 Description   
  • Using uploadField to upload a file directly to an app's workspace has drawbacks. We decided to call it bad practice and point to the fact using an @MgnlDeprecated annotation in the classes. We should document this at https://documentation.magnolia-cms.com/display/DOCS62/Upload+field. Reasons why it is bad practice:
    • It does not centralize "assets" to a single "asset" workspace, which can be problematic if you want to migrate data to an external DAM.
    • Exports with binaries throw an exception unless configured to XML exports.
    • Binaries increase the space needed by a workspace.
    • Indexing, backup/restore, publishing, difficulties in manipulation (thumbnails, scaling and other operations to be applied).
  • Add information to the uploadField page about best practice (advise to avoid using this field and to use linkField instead. This is already mentioned in the damUploadField page). We should keep the uploadField page in DOCS62, mark it as deprecated and mention that it is not good practice to use the field.
  • damUploadField makes only sense in the context of the Assets app. Details about it should probably be mentioned in the Assets app page instead. So it would be best to move the content there and delete the damUploadField page altogether to avoid suggesting that the field can be used generically in other contexts. The example should be removed too.
  • While damUploadField is not deprecated, it is no longer annotated as a field type. Both UploadFieldDefinition and UploadViewDefinition are now deprecated.
  • Delete both uploadField and damUploadField and their fully qualified class names from https://documentation.magnolia-cms.com/display/DOCS62/Field+definition#Fielddefinition-Fieldtypes.
  • Introduce UploadViewDefinition docs based on this comment:
    • Won't address, see reason in comments below.


 Comments   
Comment by Šimon Demočko [ 17/Sep/20 ]

Note to self: Might need to add an example to deprecated Upload Field, that if they want to use it they need to specify class: UploadViewDefinition, b/c uploadField type points to the UploadFieldDefinition and if anyone still would use the UF even tho it's not recommended, they need to use the UVD. 

Outdated info. We don't want users to use Upload Fields at all but rather link fields pointing to asset app. This has been documented here https://documentation.magnolia-cms.com/display/DOCS62/Upload+field UploadViewDefinition is deprecated externally but we do use it internally correctly.

Comment by Šimon Demočko [ 18/Nov/20 ]

The UploadViewDefinition was introduced, originally inteded for user purposes as well, but as per above comment, now only intended for internal use only. For this reason, we're not documenting anything about it in docs. This cancels out the need to address the last point in description.

Comment by Ashraf Khamis [ 18/Nov/20 ]

Reviewed by Šimon and Roman.

Generated at Mon Feb 12 09:34:16 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.