"Find attachment usage" feature

The proposal is to add the ability to know where an attachment (e.g. from the current page) is used in the wiki.

By used I mean:

  • Either there’s a link to it
  • The attachment is an image and the image is displayed on a page
  • (Future) There’s a macro using that attachment

That is interesting for example if you just want to find the page using an image or you’d like to delete it and want to see if it’s used elsewhere, or…


  • Thanks to the “move/rename attachment” feature that was recently implemented, we already have the information about where attachments are used (except for macro usages).
  • We need to decide where in the UI we’d hook that “find usage” feature. Some ideas:
    • Inside the attachment list at bottom of pages (extradoc), add a new action button to “find usages” and this opens an “Attachment Usage” viewer (for both links and images)
    • Inside the content menu, with a new entry for the new viewer
    • (optional) Extract the new image action popup from the Lightbox extension and move it as a standard feature. Then add a new action there to list all usages of that image. Leads to the viewer.
      • Note that the idea here is to separate the Lightbox feature from the “Find usage” feature, and the popup would only be displayed if not empty (e.g. if the lightbox is off and the image is external there would be no popup)
    • (optional) Add a link to the viewer inside the lightbox
    • (optional) In the Info tab, add a link to the viewer (or use a modal?)


  • Multi wiki is not currently supported (i.e. an image referenced from another wiki will not be listed in the usages of that image).
  • Usages of attachments through macros is not supported (e.g. usage of the pdfviewer macro)




In general +1 for this feature and the extra “Attachment Usage” viewer. I would suggest to add the link in the attachment list (extradoc), inside the Lightbox and in the list of all attachments (Main/AllDocs?view=attachments). From my understanding, this viewer would be for a single attachment and thus adding it to the content menu or the info tab wouldn’t make sense without listing all attachments there. From the content menu, the list of attachments is already available and thus this “Attachment Usage” viewer is already linked there.

1 Like

I was actually considering having the same viewer vm but with query string parameter to filter for a single attachment or to list all attachments of a documents (i.e. all usages of all attachments).

To summarize, the idea would be to:


@tkrieck WDYT in term of UI/UX?

If we’re ok on the idea, I’ll create a jira issue.


+0 in general for the feature.

Regarding the UI, wouldn’t it make sense to actually have a generic UI for all details of an attachment: a page that you could access using e.g. /viewattachment/Space/Page/AttachmentRef.png and which would display various info like metadata, usage, full history etc.

We have this already with the attachment viewer (e.g. Sandbox - XWiki). It already displays metadata, summary, there’s a link for the full history (viewattachrev action). It’s just missing the usages, and thus you’ve made me realize that we need to also add the “Usage” action in that LD :slight_smile:


Not really what I had in mind: here it’s the viewer for all attachments, while I was more thinking of a viewer for a single attachment. More like what you can see in wikimedia, e.g.: File:Logo-xwikiorange.svg - Wikimedia Commons

IMO this view would allow to gather more info in the long run, that we might not want to always display in the LD of attachments, or that are not easy to display like the history of a specific attachment.

Nice feature! Displaying the file metadata would be useful as well indeed. I’m wondering if a contextual menu similar to the one we have for pages would make sense, with the following items (in addition to the “move” and “delete” actions which could remain promoted as top level buttons) (not sure, just adding this also to mention possible complementary actions in the future):

  • Actions
    • Copy
    • Share by mail
    • Download (it’s not necessarily trivial to download an image, and in some cases in requires approving a license)
    • UIX for other actions (eg “edit image”)
  • Viewers
    • Metadata
    • History
    • Usage
    • Statistics (integration with the Analytics app)
    • (or a single viewer containing all the above as mentioned by Simon in MediaWiki)

I would rename it as “Used In” or “Linked From” instead. Usage means how something is used or the way it is employed (the usage of our app increased 10%, for example). But here we are focused on a specific context, where something is being used.

But it’s a nice feature, I like it. I believe a dedicated info page, like @surli mentioned, would fit best for this. The list of pages can be extensive for a common file, so having the space to grow is important, and a LiveData table can become really cramped, really fast. In this context, the button could be called “More info”.

The button placement for now seems to be ok, but in the future if more items are added to the action’s column we will need a menu like @slauriere said (preferably automated as a LD feature).

I agree with this.

Cool idea! +1

After taking into account the feedback from everyone, here’s the new proposal:

  • In XWiki Attachments are entities (like Documents, Wikis, Spaces, xproperties, etc). Thus it makes sense to have a view page for each kind of entities. Right now we have that only for documents but it makes sense to add that for Attachments.
  • Since the Standard URL scheme is already defined and cannot be extended for the “view” action, the idea would be to add a new “viewattach” action, similar to the “view” action for documents.
  • The “viewattach” UI would look the same as for documents:
    • The content would try to display the attachment. For image attachments, the image would be displayed and for attachments that don’t have a displayer, some box around the name of the attachment would be displayed
    • There would be a content menu, with a “download” button and a “more” menu as Stephane mentioned (an initial implementation would only list 2 actions: delete and move, implemented using a UIXP). Later on, we could add other actions.
    • Add a viewer for the “history” and “used in” UIs (ie separate vms, different from the attachextra tabs).
    • There would be a “docextra” widget (called “attachextra” or “attachmentextra”) with several tabs (also implemented using a UIXP): History, Used In, Info (for metadata).
    • We could also have viewers for each “attachextra” tab.
  • The attachments LD in the document attachment tab (in docextra) will have a new action: “View” (in addition to the existing “Move” and “Delete” actions). The “View” action will use the “viewattach” action, see above.
  • (optional) Also add the “View” action to the “Page Index” Attachments tab LD
  • We then need to decide what to with the viewer=attachments UI:
    • Add a “View” or “View Details” action in the LD?
    • Remove the ability to click on the attachment name column in favor of the “View” action? or keep it but navigate to the “viewattach” UI (same as the “View” action)? Or keep it as it is (ie the user can either click on it or on the “View Details” action)?
    • Remove the display of the last version in superscript? Keep the display of the last version in superscript but remove the link on it? Keep both but when clicking navigate to the attachment history viewer (see above). I think the later is the best.
  • What do we do with the “viewattachrev” UI? I think we could implement the new attachment history viewer by reusing it.
  • For documents, we display a “Backlinks” section in the “info” tab and we should generalize this in the future, to be a “Used In” concept which would encompass both backlinks but also usages in macros (like display/include macros for example). When we do this in the future, we may want to introduce a new “Used In” docextra tab. Then we would be consistent between documents and attachments.




I would go with this.

Today, when clicking a PDF for example, a user can start scanning the document right away on the browser. If I understand correctly, if we use exclusively the new UI, two clicks would be required to do this (One for opening the new UI, another one for opening the PDF in browser).

If desired, the user can “View Details” to check metadata on the attachment.

I agree too. Note that I forgot to mention it but we need the “Attachments” tab UI in docextra to look similar too I think (the viewer is basically the same UI and used when the docextra is not visible). See Sandbox - XWiki for an example.

or the usages of the attachment, its history, etc.