Is a File Asset being used in Squiz Matrix?

7 minutes 55 seconds average read (1583 words)

I have recently been asked if there is some kind of report in Squiz MatrixCMS that can tell me whether a file is being used or linked to.

Out of the box the answer to this is no, although Squiz Matrix does have a linking table in the database (PostgreSQL) that highlights all of the relationships between assets in the CMS.

This linking data can be exposed by a Squiz Matrix Keyword Replacement, %asset_linking_info% . The output of this Keyword Replacement is:

Returns the linking information of the asset in a JSON array. This is the same information that is available on the asset's Linking screen.

An example of the return response is:

[
  {
    "linkid":"4505",
    "link_type":"8",
    "link_value":"",
    "lineage":["1916","2363","1917","3629","3637","3687","3688","3689"]
  },
  {
     "linkid":"4503",
     "link_type":"1",
     "link_value":"",
     "lineage":["1916","2363","2456","3697"]
  },
  {
    "linkid":"4513",
    "link_type":"8",
    "link_value":"",
    "lineage":["1916","2363","1917","3629","3637","3701","3702","3703"]
  }
]

So what does this data mean?

`linkid`

This is simply the unique identifier for each relationship in the system, it is required and every link (relationship) has a linkid .

`link_type`

This explains the specific link type, which I will cover further down, for this link between this asset and it's linked parent, it is required and every link (relationship) has a link_type .

`link_value`

This is an optional value and is used to add an extra description to the link, there are some system defaults or this can be set by a user.

`lineage`

This shows an array of all the parent assets of the asset in relation to the specific linkid .

Link Types

There are 4 link types within Squiz Matrix, the first 3 show a parent/child relationship, the 4th is to show a non-linear relationship between two assets. In the image below the site asset [1917] letorey.co.uk is the parent of [2403] Home, [2407] About, [2411] Blog, [2424] Speaking & [2415] Contact and they in turn are the children of the site [1917] letorey.co.uk.

example of asset map

`TYPE_1`

This is defined in the link_table, in the database as:

define('SQ_LINK_TYPE_1', 1);

This is a link_type that is shown both on the frontend and backend navigation (backend navigation refers to the asset map or assets finder). This means that we can see the structure of the assets in the asset map/finder and also in the navigation/menu of the website. In the example above [2407] About, [2411] Blog, [2424] Speaking & [2415] Contact are all TYPE_1 links and you can see them in the menu of this site.

`TYPE_2`

This is defined in the link_table, in the database as:

define('SQ_LINK_TYPE_2', 2);

This is a link_type that is shown only on the backend navigation. This means that we can see the structure of the assets in the asset map/finder but NOT in the navigation/menu of the website. In the example above [2403] Home is a TYPE_2 link, this is indicated by the orange circle with II in it on the asset icon, and you can't see them in the menu of this site.

`TYPE_3`

This is defined in the link_table, in the database as:

define('SQ_LINK_TYPE_3', 4);

This is a link_type that is NOT shown in either the frontend or backend navigation. This means that we can't see the structure of the assets in the asset map/finder and is NOT displayed in the frontend navigation/menu. This link_type can only be set by the system although a Create Link Trigger Action can also set a TYPE_3 link. There are 2 links that, by default, are created as a TYPE_3 link: Design_AREAs and Form Submissions. For Submissions are created as TYPE_3 links because we want to hide them from users by default as they could contain sensitive information.

`NOTICE`

This is defined in the link_table, in the database as:

define('SQ_LINK_NOTICE', 8);

This link_type is for information purposes only and shows a link that can not be displayed/shown as a parent/child relationship in the asset map/finder. For example, it is referenced in a href attribute of an <a> element, it is referenced in a src attribute of an <img> element, it is being used as the index page of the site or it has been assigned as the thumbnail of an asset. When it is being used for a specific reason it would have a link_value to explain that relationship, for example:

{
  "linkid":"3164",
  "link_type":"8",
  "link_value":"thumbnail",
  "lineage":["1916","2363","1917","2411","2616"]
}

In this example we see:

linkid - which is a unique identifier
link_type - in this case 8 which is a NOTICE link
link_value - in this case thumbnail which indicates that it set as the thumbnail of the last asset in the lineage
lineage - this is an array of the parents the last, 2616, being the asset this is the thumbnail of

How can we use this information?

We can look at the information in the link table to find out where an asset is linked to, specifically we can look at the linking info of file assets to find out if they are being linked to via a hyperlink of being used as a thumbnail.

Creating a List of Files and where they're used/linked

Asset List Details Screen

Asset Types to List - Image, PDF, any other types of file you want to check for. Alternatively you could choose File and inherit, which would list all types of file asset.
Root Nodes - select the root nodes (parent assets) where your file type assets live, I've selected Images & Documents folders.
Assets Per Page - I have selected 0 which would show all the file type assets in the root nodes selected. Although you could limit this and paginate the listing.

Page Contents Bodycopy

I want the output of my list to be an unordered list of files that then has an unordered list of the links where the file is being used.

<ul>%asset_listing%</ul>

This is pretty standard, if you were going to paginate the list you would put the previous and next links here.

Default Format Bodycopy

Part 1 List the files

<li>%asset_attribute_title% (<strong>#%asset_assetid% %asset_type%</strong>) linked to:</li>

Here I have a list item that contains the Title ( %asset_attribute_title% ) of the file followed by, in brackets, the asset ID (%asset_assetid%) and the file type (%asset_type%).

Part 2 Setup a default sub list

<li>%a… to:<ul id="parent%asset_assetid%"><li>Not linked anywhere</li></ul></li>

Here I have an unordered list inside my first list to create a sub-list. I've put in a default list item, <li>Not linked anywhere</li> , that will be replaced if the file is used somewhere. I've also added an id attribute, id="parent%asset_assetid%" , that I can use to target the list to insert list items.

Part 3 create a variable of links

var assetLinkingInfo = %asset_linking_info%;

Part 4 check that an array was returned

if (Array.isArray(assetLinkingInfo)){
  // if the variable returns an array do this  
}

Part 5 define where to inject the list items into

var parents = document.querySelector("#parent%asset_assetid%");

Part 6 setup an empty variable to store the list item(s)

var html = "";

Part 7 check the array (created in part 3) is not empty

if (assetLinkingInfo.length < 0) {
  // if it is not empty do this…
}

Part 8 set up a forEach loop for each link in the array

assetLinkingInfo.forEach(function(link){
  // what to do for each link
})

Part 8a check to see if the `link_type` is a `NOTICE` link " `8` "

if (link.link_type === "8") {
  // what to do if it is a NOTICE LINK
} else{
  return // go to next item in the array if there is one
}

Part 8b check to see if the `link_value` is `thumbnail`

if (link.link_value === "thumbnail") {
  // what to do if it does have a link_value of thumbnail
} else {
// what to do if it does NOT have a link_value of thumbnail  
}

Part 8b(i) what to do if it does have a link_value of thumbnail

html = html + `<li>Set as Thumbnail on <a href="./?a=${link.lineage[link.lineage.length - 1]}">asset: #${link.lineage[link.lineage.length - 1]}</a></li>`;

Add a list item to the var html that says this is a thumbnail for asset number xxx.

Part 8b(ii) what to do if it does NOT have a link_value of thumbnail

html = html + `<li>There is a link to this %asset_type% in asset <a href="./?a=${link.lineage[link.lineage.length - 1]}">asset: #${link.lineage[link.lineage.length - 1]}</a></li>`;

Add a list item to the var html that says this is linked to asset number xxx.

Part 9 if the html var is not empty insert the value into the list

if (html != "") {parents.innerHTML = html};

Whole Default Format

 <li>%asset_attribute_title% (<strong>#%asset_assetid% %asset_type%</strong>) linked to:<ul id="parent%asset_assetid%"><li>Not linked anywhere</li></ul></li>
<script>
  var assetLinkingInfo = %asset_linking_info%;
  if (Array.isArray(assetLinkingInfo)){
    var parents = document.querySelector("#parent%asset_assetid%");
    var html = "";
    if (assetLinkingInfo.length > 0) {
      assetLinkingInfo.forEach(function(link){
        if (link.link_type === "8") {
          if (link.link_value === "thumbnail") {
            html = html + `<li>Set as Thumbnail on <a href="./?a=${link.lineage[link.lineage.length - 1]}">asset: #${link.lineage[link.lineage.length - 1]}</a></li>`;
          } else {
            html = html + `<li>There is a link to this %asset_type% in asset <a href="./?a=${link.lineage[link.lineage.length - 1]}">asset: #${link.lineage[link.lineage.length - 1]}</a></li>`;
          }
        } else { return }
      })
      if (html != "") {parents.innerHTML = html};
    }
  }
</script>

Download the File Asset Usage Listing

Download File Asset Usage Listing %asset_summary_3727%

To use this file:

Download
In Squiz Matrix Click:
- Tools
- Import Assets from XML
- Choose the downloaded file
- Choose the location to add the listing
- Click Import
On the Details screen of the newly created asset list, set:
- Asset types to list
- Root Node(s)

Caveats

This should not be exposed to the frontend and just be used as an internal report.
This won't return files that appear in listings, such as an Image Gallery or a list of PDFs if their parent is set as a root node for an asset listing.

Is a File Asset being used in Squiz Matrix?

So what does this data mean?

linkid

link_type

link_value

lineage

Link Types

TYPE_1

TYPE_2

TYPE_3

NOTICE

How can we use this information?

Creating a List of Files and where they're used/linked

Asset List Details Screen

Page Contents Bodycopy

Default Format Bodycopy

Part 1 List the files

Part 2 Setup a default sub list

Part 3 create a variable of links

Part 4 check that an array was returned

Part 5 define where to inject the list items into

Part 6 setup an empty variable to store the list item(s)

Part 7 check the array (created in part 3) is not empty

Part 8 set up a forEach loop for each link in the array

Part 8a check to see if the link_type is a NOTICE link " 8 "

Part 8b check to see if the link_value is thumbnail

Part 8b(i) what to do if it does have a link_value of thumbnail

Part 8b(ii) what to do if it does NOT have a link_value of thumbnail

Part 9 if the html var is not empty insert the value into the list

Whole Default Format

Download the File Asset Usage Listing

Caveats

`linkid`

`link_type`

`link_value`

`lineage`

`TYPE_1`

`TYPE_2`

`TYPE_3`

`NOTICE`

Part 8a check to see if the `link_type` is a `NOTICE` link " `8` "

Part 8b check to see if the `link_value` is `thumbnail`