How to Create Dynamic Catalog Links
Have you had students confused because they looked at a program's requirements, only for you to realize they clicked on a link pointing to a three-year-old catalog?
Are you tired of updating dozens, if not hundreds, of catalog links every year when the catoid changes?
Do you enjoy automation generally?
Then this is the tutorial for you!
Important Note
These dynamic links will automatically update links for programs to point to the newest version of the catalog year-over-year. However, links will still need to be manually reviewed and updated in a few circumstances:
- Programs that undergo a title change will need to have their links updated manually once, to reflect the new program title
- Programs that are on hold, in moratorium, have been cancelled, etc will need to have links removed manually
- New programs will need to be added to otherwise automated lists of links
How it Works
Our catalog provider has an API that allows us to create links that have their attributes set based on some custom attributes.
<a href="https://catalog.wwu.edu" class="acalog" data-acalog-data="programs" data-acalog-program-name="Art History, BA" data-acalog-catalog-id="18"> Art History, BA </a>
WebTech provides a library inside our Drupal theme, Ashlar, that holds the current catalog ID and the program parameters. We can update that ID once a year, and anyone who is using the library and has the properly formatted links will automatically have their links update to point to the new catalog.
const current_catoid = "18";
$('.acalog').attr("data-acalog-data", "programs");
$('.acalog').attr("data-acalog-catalog-id", current_catoid);
$('.acalog').acalogWidgetize({
gateway: 'https://catalog.wwu.edu',
});
You have a website with these specially formatted links. You set the links once with the program titles configured, and WebTech's script adds the most current catoid.
<a href="https://catalog.wwu.edu" class="acalog" data-acalog-program-name="Art History, BA"> Art History, BA </a>
The only time you need to update or think about these links is when there is a significant change to a program (ie, the cases outlined in the Important Note box.) For the vast majority of programs, the links do not need to be edited year over year, they'll always point to the most recent catalog with the most recent program updates.
How to Add the Links
To make use of these dynamic links, you will need to attach a library from the theme containing the Javascript files that make the links work. There are two ways to do this:
- Attach the library in a view
- Enable the library site-wide
If all of your links are being created in a field and output by views, then option 1 is preferred because it will only load the Javascript on the pages that need it.
If that sounds like complete gobbledygook to you, or you just want links in text blocks, then go with option 2.
Option 1: Attach the Library in a View
First, make sure you have the module Attach Library in Views enabled under Structure > Extend
Next, open up your view. Under the Attach Library section click on Add Library
Set the library as ashlar/acalog
Save the view and you are good to go. Any links generated with this view containing the acalog class and necessary data-acalog attributes will be transformed.
Add a Link in the View
As with all things Drupal, there are many ways to configure your fields and views to make this work. A lot of details of possible set ups are outside the scope of this tutorial, but here is broad overview. Let's assume you have a plain text field called Program.
When entering the program title in this field, it is important that it match exactly with the program title in the catalog. The easiest way to achieve this is to copy and paste the H1 from the catalog directly into the field.
Now you will open your view and add this field. In the field's Rewrite Results, you will format it something like this:
<a href="https://catalog.wwu.edu/" class="acalog" data-acalog-program-name="{{ field_program }}">{{ field_program }}</a>
After you save your view, your links should now update with the newest catoid and that program's id added to the URL.
Option 2: Enable the Library Site-Wide
Go to Appearance > Settings > Ashlar (if you do not have access to this menu item, contact web.help@wwu.edu and ask for WebTech to enable this feature for you)
Click the checkbox for "Load Javascript for dynamic catalog links"
Save the configuration. Any links on the site containing the acalog class and necessary data-acalog attributes will be transformed.
Add a Dynamic Link
These links can be added in any content field or block type that uses the CKEditor interface and/or allows HTML. You will need to edit the source code to add the appropriate attribute.
First, adjust the text format on the editor to Full HTML.
Next, add your link as you normally would. Set the URL to https://catalog.wwu.edu (this will be replaced, but is a good fall back value in the event the scripting fails to load.)
Now, go into the Source of the editor and find your link. Add the following attributes to the link in question, replacing Accounting, BA with the title of the program you are linking. Note: It is important that this match the title exactly as it appears in the catalog. The easiest way to achieve this is to copy and paste the H1 from the catalog directly.
class="acalog" data-acalog-program-name="Accounting, BA"
Click back out of the source code on the editor. Then, save the block or content, and your link should now updated with the newest catoid and that program's id added to the URL.
Fallbacks & Troubleshooting Scenarios
These links do require Javascript to function. In the event that the scripting fails, the href set on the <a> tag will be the link's destination. We recommend setting this to https://catalog.wwu.edu, so that users are still sent to the most recent catalog where they can search for the program in question.
If a program name does not match, but the scripting succeeds, then the link will be replaced by the Acalog API with the full path to the most recent catalog, and will look something like this:
https://catalog.wwu.edu/index.php?catoid=20
If you see a link formatted this way, make sure your data-acalog-program-name property matches the program title in the catalog exactly.