Create a description field for page attachments

Development
#1

Hello everyone,

I am currently working on Loading... and would like some feedback for a few points.
To sum up, attachment revisions stored in the database currently have a field XWA_COMMENT that is not used anywhere. The idea would be to add a setting to expose this field to provide a way to upload one or multiple attachments with a comment, and display it both on the list of attachments and the revision history for attachments. Here is a mock-up from the issue for when the setting is enabled:
image

Now, the field mentions a comment, the issue asks for a description, and in essence the feature is very close to the concept of revision summaries we already have for documents. So a first question would be: how should we name this feature?
Personally, I would be +1 to use “summary” since it would be more aligned to the current UI, but I’m open to other ideas.

Also, note that the current limit on the field is 1023 characters, which seems enough to me for this feature so I would keep it as is.

Finally, where exactly should this be displayed and how should it be edited? The issue mentions only that the field should be set during upload and displayed in the attachments list and the attachments history. If we consider this as a summary, I think it would make sense to have a default value for the different upload methods (upload button, edit mode, API) and to make it non-editable since it is tied to a revision. But there are other pages, such as XWiki.AllAttachments, where I’m still not sure if it makes sense to display it or not (for the record, the summary for document revisions is not displayed on XWiki.AllDocs).

WDYT?
Thanks.

#2

Some thoughts:

  • I like the “summary” terminology since it’s the same one as we have when saving a page
  • I doubt that users are going to use that summary field that frequently and I’d be in favor of not displaying it by default in the Attachment tables (either in the attachments extradoc table or in the Page Index). Also this would be consistent with the doc summary that we don’t display in the Page Index for example. This would mean that to see it, users would need to view the history for the attachments (e.g. http://localhost:8080/xwiki/bin/viewattachrev/Main/WebHome/Screenshot%202023-10-20%20at%2016.15.39.png). I’d also add it by default in the attachment view LD (http://localhost:8080/xwiki/bin/view/Main/?viewer=attachments). Now since this might not be enough, I’d add an Admin UI option to customize the attachment tables in the extradoc tab so that it can be added (but not used by default).
  • To be decided (not sure) if we also want that admin UI option to control displaying a column for the summary in the attachments tab of the Page Index
  • Last, I’d like @tkrieck or @amilica 's help to design the new input since the screenshot above would need to be improved a bit IMO
  • Re edit, indeed, we could, FTM at least, consider it read only. I think it’s ok for a first version.

Thanks!

1 Like
#3

Semantically I’m not sure Comment should match with anything like summary or description. E.g., I can put a WIP comment when uploading an attachment, but it would be a really bad description. I can put Please do not change the size of this attachment as a comment and it would be a bad version summary. If it’s not used by any extension, I’m okay with changing the semantics of this field (given we document it properly ofc).

If we decide that this comment field can be used as a summary or description, it would be great to provide it as a default image alternative text! Right now the default alt is the attachment filename, which is far from perfect. Note that it wouldn’t replace the alt defined in content, because ideally an alt text is context dependent, and the same attachment can be used in multiple contexts (which would make its description context independant).

For the pretty name, it depends a lot on what we prioritize as the main function of the field:

  • Summary if we want its main function to be helping keep track of the version of the attachment
  • Description if we want its main function to be helping figuring out what an attachment is
  • Text alternative if we want its main function to be a default for filling up uses of this attachment in content.

From the way the ticket is described, it seems like Summary is the main function.

I’m not sure about the exact way to edit it. But IMO if we consider it as a summary, we should still show it as editable (even if editing it actually creates a new revision of the attachment with an updated value, and doesn’t edit anything).

Thanks for this proposal!
Lucas

#4

IMO it would be weird to edit a change summary and a first since we don’t do that for documents. Now if someone really wants to add a new change summary, they would always be able to download and re-upload the attachment with a new summary, so at least it’s not blocking. As I mentioned, I’d keep the editing feature for later as I don’t think we need it for the first version.

The only thing that worries me a bit more about the change summary concept for attachments is that when an attachment is added to the page, it’s not saved and the page needs to be saved for the attachment to be added. Thus there’s already the change summary of the page to take care of the summary…

If the attachment was saved independently of the page it would make sense to have its own change summary but since it’s not the case, I’m hesitating and wondering if change summary is the right way to view this.

Maybe this text is not actually a change summary but simply more an attachment title (or description), more similar to the document’s title. In this case, it’s something that should be editable and not related to the history. I have the feeling this makes more sense actually. WDYT?

#5

Going back to this proposal, here are a few more thoughts:

I would agree for a description but I’m not sure it makes sense for a summary, I would expect the information provided to be wrt the upload itself and less to the image.

The main idea here is to add the feature to the attachments tab, where the upload button is. This is in view mode, not edit mode, so there is no summary field to interact with and the save is done automatically. Now, from what I can see, a comment set on an attachment is automatically added to the default page summary:
image
This was the existing behavior, I have not changed anything here.
So, I think it still makes sense to view it as a summary.

This would not fit the requirements of the original issue, that state that “On the history view of the attachment, all successive descriptions could be visible”.

#6

Hi,

maybe I missed it in previous answers but I haven’t seen mention of the attachment summary in case of attachments added while editing a page? Are you planning to reuse directly the comment used for saving the page? That’s probably easiest way to start, knowing that ultimately we’d need a proper UI to select / edit the uploaded attachments during an edit session (see also Loading...)

#7

That was exactly my point; you’ve shown it in your screenshot that there’s already a summary when an attachment is added. This is why I was wondering if it was making sense to add a second summary for attachments. Now Attachments do have a versioning store (AttachmentVersioningStore) so it’s possible to consider it a summary for that store, and displayed for the viewattachrev action (e.g. http://localhost:8080/xwiki/bin/viewattachrev/Sandbox/WebHome/XWikiLogo.png).

However, if we do this, then it doesn’t make sense to have that summary displayed in the LD for attachments in the extradoc section at bottom of pages (since that LD is not related to attachment revision metadata). To view it differently, we don’t display the summary for a page in the Pages LD in Page Index.

It would make sense to display it in this extradoc attachment LD if it were a description or title for the attachment though. And in this case it would not make that much sense to display the attachment desc/title in the viewattachrev action viewer, since that desc/title would be attached to an attachment name (but it’s probably acceptable to display it if we want). This would also probably mean that we’d offer an LD action in the extradoc attachment table to edit/change the descriptiont/title for the attachment instead of an input box to be used when uploading the attachment.

AFAIK the requirements you mentioned are not something that was discussed here and my understanding is that they can be changed.

#8

Ok, I see your point now.

We should probably ask for @Jsd 's input on this part, however, as the original reporter.

#9

Hey everyone.

For the layout on the upload fields, you could just move the description field above the file selector. At least to give the user a chance of writing something before uploading (as it is automatic).

Otherwise, it would be best to give this whole section an “upload” button. So the user can select the files, write a summary, then click upload. For this specific discussion, maybe this is too much of a change, but I will try to get a proposal on this specific topic later on.

#10

Thanks @tkrieck for looking into this!

Small note that we’re thinking to make this attachment upload summary optional and turned off by default (it would be shown if enabled in the xwiki config).

#11

Hello, the mockup in the ticket came from my own guesses, but I confirm that this new field should be visible in the history of attachments. It will allow to update it with new versions of each file if I understood well, which is aligned with the proposal.
To have it displayed in the livetable of the attachments is therefore less relevant.
Thanks!