Is a File Asset being used in Squiz Matrix?

12 minutes 10 seconds average read (2432 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 .

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:

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

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:

Caveats