The fifteenth VuFind® instructional video demonstrates how you can incorporate static content (informational screens and local messages) into your VuFind instance. This provides a simple way to customize your displays to meet the needs of your local audience, using only basic HTML or Markdown, and including support for internationalization.

Video is available as an mp4 download or through YouTube.

1. Static Pages Documentation

This is a machine-generated transcript and will be corrected as time permits.

Hello, and welcome to this month's VuFind tutorial video, which is about managing static content.

When I say static content, I'm just referring to the ability to create custom HTML pages to present information within your VuFind instance, or to embed that type of information within some of VuFind's existing displays. VuFind is, of course, not meant to be a content management system, and so I certainly wouldn't recommend using it to build your entire web presence, but sometimes it's useful to be able to place a page of custom content into the context of VuFind, and so we provide some tools to enable you to do this, and to also take advantage of VuFind's internationalization support along the way.

When you get VuFind out of the box, it ships with a couple of examples of static content, which are really just meant to be overwritten as you customize the system. These include the Ask a Librarian and FAQs pages which show in the footer and just contain placeholder information if you click through to them. So creating these static content pages is pretty easy. It's just a matter of putting templates in a particular directory within your theme, and then VuFind does the rest.

Let me quickly show you where this lives in the default theme, and then we'll move forward to creating some content of our own. So if I go into VuFind's themes directory and look under bootstrap3 in the templates/content/ directory, you'll see that we have an FAQ.phtml and ask library.phtml and a couple of other utility templates that are actually used by the content display code. But the important thing to take away here is that if you see a file that starts with FAQ, and you go to your browser and add content slash FAQ after the base URL, if you find we'll display that template to you, providing a really easy way to render custom content. VuFind also supports Markdown, so if you want to create your content using the Markdown language instead of PHP HTML templates, that's available as well, which may be more convenient if you're working with the content development team that's less comfortable with coding because the Markdown standard is widely used.

So with that background out of the way, let me do some quick demos, and I'll start by showing you how to create a Markdown-based content page in your VuFind instance. Right now we're looking at VuFind's core bootprint3 theme, so let's switch to our custom tutorial template, so we're in a better position to customize some things. I'm just going to switch to my local config viewfind config.ini file, and I'm going to comment out the bootprint3 setting to activate my tutorial setting. Now if I go back to my browser and refresh, we get to see the custom tutorial theme that we've been using in some of these videos.

Now that we're on our custom theme, creating a new content page is as simple as going into our theme folder, so under themes/tutorial/templates/, we need to create a new folder called content, since this is the first content page we're creating, and in this content folder, we can just create a new file. So as I said earlier, the file name will correspond with the URL where the content will be displayed, so I'm going to call this Markdown-demo, but the extension of the file will tell if you find how to render the content. So if I were to end this in .php, it would render as a standard PHP template, but of course I want to demonstrate Markdown, so I'm going to name the file .md instead. So now I have an empty file, and I'm going to put some Markdown in it. I'm not going to go into any depth on the Markdown standard during this video, because there are lots of tutorials and sheet sheets out there, but it's widely used, you've probably run across it somewhere, and even if you haven't, it's pretty easy to learn. In any case, I'm going to start with “# My Title”, because prefixing text with the pound is how you create a heading in Markdown, and then I'm just going to put a line of content. I'm going to say this is the “\*Markdown demo\*”, to show some formatting, and I'm going to say here is a \[link\](), and I'm going to link this to the VuFind home page just for fun, and that's it.

So I'm saving this file of Markdown. Now if I return to my browser, and I go to /content/Markdown-demo, as part of my VuFind URL, there is my Markdown, rendered in VuFind. Also, you might notice that the tab in my browser actually shows my title. The Markdown parser is smart enough to take top level headings and use those as the page title for you. And if I were to click this link, it would take me to the VuFind home page. So it's that simple. You can create Markdown to your heart's content, and serve it up through VuFind, so you can create institution specific pages, custom help screens, whatever you like.

I also mentioned earlier that the content display system supports internationalization. So if you're if you find instance supports multiple languages, you can create multiple versions of your static content, and VuFind will display the appropriate one based on the language that's currently active. The way you do this is simply to put an underscore and a language code on the end of your file names. So I'll do a quick demo of this as well. I will create a new file called i18n_en.phtml. So this is going to create a content page called i18n, the common abbreviation for internationalization. And this is going to be the English language version of that, and I'm indicating that with the \_en at the end of the file name. And this demo, I'm just going to do standard phtml templates. I could just as easily use Markdown here. It makes no difference. I'm just showing both versions for demo purposes. So then I can say in here, “this is in English”. And since this wouldn't be a very exciting demo, if I didn't have another language as well, I'm going to create another file called i18n_fr.phtml for French, and I'm going to write in here, “This is not in French, but we can pretend”. I will save that.

So now, if I go back to my browser, I need to go to the right browser. If I go back to my browser, and I edit my URL so that it is /content/i18n after the page VuFind URL, I see my, this is an English message, then if I switch my language to French: “This is not in French, but we can pretend”. It's that simple.

I should also make a quick note on how the default behavior works for these templates. If you have a number of languages, but you don't have templates for all of them. So for example, if I switch this to German, it actually says this is in English. The reason for that is that in config.ini, you're able to set a default language for your site. And if you find is unable to find a template for the requested language, it will next search for a template in the default language as a fallback. So in this example, German is not available. English is the default language configured in config.ini. So if you find decides to display the English template. If there were no English template, it would next look to see if there were simply an i18n.phtml template with no language code at all. It would use that next. And only if all of those options failed, would it give up and throw an error about content being unavailable.

In any case, that shows you all the capabilities for creating static pages in Markdown or PHP and with or without internationalization support. One thing that you might want to do though is give one of your content pages a custom URL. As you notice, by default, all of the content pages have URLs with slash content slash something in them. But through the magic of the Laminas router system, it's not very difficult at all to give these any URL you like. So I'll show you that really quickly.

First of all, let's go into the core VuFind module. So I'm going to my VuFind home module VuFind and I'm looking at the configuration here. So in my VuFind module, I'm going to the configuration directory and opening module.config.php. And at the top of this file are all of the route definitions, which we've talked about in the past. But one of these routes is called content page. And it is this route, which does all the magic resolving content for you. So it's a segment based route and it looks for slash content slash something. When it encounters a match for that pattern, it calls the content action of the content controller and passes through part of the URL as a parameter called page. So this is how you're able to type in a content URL and have few finds code map that to an appropriate template to display. But if you want to give a different URL to a content page, you can simply copy this route into your local module and make a few small changes and get the effect you want. So I'm going to do exactly that.

I'm going to copy this whole route. And then I'm going to go into my local tutorial module and into the configuration and the module config. So in here, we have a custom route that we set up in a past video. And I'm just going to paste in that content route right above it. And the formatting is a little ugly here, but I'm not going to worry about that right now, just bear with me. So first of all, we want to give every route a unique name because we don't want to override the existing content page route. We want all of our content to keep working. And if I didn't change this, this content page route would override the core version. So instead, I'm just going to call this content demo. And then I'm going to go to my options and I'm going to replace this content slash page thing with the URL that I want to use. So let's say we want to show that Markdown demo at a URL called Markdown demo. I can just put that in because there's no page placeholder anymore. I can remove that constraint. And instead, I can go into the defaults and I can just hardcode a page value here. And this is going to be Markdown demo. It's that simple. I've created a route named content demo. It's going to look for a URL that just says Markdown demo. And when it encounters that URL, it's going to call the content action of the content controller and it's going to pass it a page parameter of Markdown demo, which is exactly the same as using the other route to go to slash content slash Markdown demo.

So let me show you. If I now go here and I just put Markdown demo on the end of my VuFind URL, I get to see my Markdown page. So in this way, you can seamlessly incorporate static content into your URL structure, as long as you're careful not to collide with existing URLs or route needs. So that covers all of the standalone page content.

But what about incorporating this type of content into an existing page? If you find has something called content blocks, which are currently used on the various search home pages to drop in interesting information. So for example, if I just go to my search home screen, on I'm going to set this back to English for a moment, you will see that we have this facet information here. And this is actually being dropped in as a content block.

This is a configurable setting that you can find in searches.ini, and all of you find search back ends have a content block configuration so that you can put different content on each of their home pages. Let me show you in practice here. So if I go to you find main config, you find directory. And I look at the searches.ini file, which controls the behavior of the main default solar based search near the bottom of this file. There's a setting called content. And this is where we configure the content blocks for the home page. By default, two content blocks are set up. One is called ILS status monitor. This normally does not display anything, but it will check to see if your ILS is offline. And if it is, it will display a warning message that some functionality may be unavailable. If you're not using an ILS, or you don't want this feature, you might consider commenting this out. Following that, there's a facet list content block, which is what creates that facet list I was showing you. And again, if you don't like that, you can simply turn off this setting to get rid of it. And you can also choose from some of the other content blocks that are listed in the comments up here, or you can build your own. But for today, what I want to show you is a content block called template based, which allows you to drop static content onto your home page in much the same way as you are able to create the static content pages I just showed you.

So I am going to demonstrate that for you right now. So first of all, because this demo instance doesn't have a custom searches.ini yet, I am going to copy the core searches.ini file into my local settings directory. So I have a place to do some custom configuration. So I'm copying from if you find home config, if you find searches.ini into local config, you find searches.ini. And then I'm going to scroll down here so I can customize my content. So to turn this on, I simply need to add another content block setting. So I can say content bracket bracket. And the brackets are important because this is a repeating setting. And we want to be sure that we don't override the setting rather than adding to it. And I can say equals template based, which is the name of the content block colon i18n. We just need to give a template base name for the content block to use. In this case, I'm choosing i18n because that allows me to be really lazy and simply copy and paste the templates that I created for the earlier full page example. The only difference is what directory the files go in within my theme. So for page content, I use the content directory for content block content. I just need to create a different directory to put my files into. And that directory is content block with a capital C and a capital B. And under that, the folder called template base. So I can now just take my to i18n templates, copy them, paste them into here. And make sure that I saved my configuration properly. It's also worth noting that the order of the content settings affects the order of the display. So I've set this up so that the template will appear above the pass it list and below any ILS related messages. But I could move this line around if I wish to do things differently. And now I come back here and refresh the page. The message this is in English has appeared above my list of facets. So it is working. And if I change my language to French, it says “This is not in French, but we can pretend”.

So the template based content block follows all of the same rules and conventions as the full page templates. So you can use the language suffixes on the file names or not as you prefer. You can use PHP templates or Markdown as you prefer. It's just a nice way to be able to quickly and easily embed messages wherever you need them. The next step that might be useful would be to have similar functionality in a recommendation module so that we could put messages into search results. And as of the recording of this video, we haven't actually implemented such a thing, but it would be pretty straightforward to do so. So if anyone has a need for this, by all means feel free to open a Jira ticket and we can get that feature incorporated into a future release.

In any case, thanks for your time and for listening to this. I hope this makes it easier for you to share information through your VuFind instance and we'll have more for you next month.