Why should I upgrade existing H5P content? And how?

What is this about?

Let’s start with a quick explanation of what this post is about. You use H5P content types (libraries) like H5P.Column to create Column content. Each content type library has a specific version number, e.g. 1.1.7. This is similar to the semantic versioning scheme. The content you create knows what version of that library it was created with – at least the first two digits. So far, so good.

When things are fixed or changed in the content type, that version number is incremented in a special way to help distinguish between different versions. If the change is minor and does not affect compatibility with older versions, the last number is increased by 1. Version 1.1.7 would become 1.1.8. If you update the content type library, your existing content will automatically use this later (patch) version, because the first two numbers are still the same.

However, other changes to the code may require that the second version number be incremented by 1 and the last number be reset to 0. Version 1.1.7 would become 1.2.0. This change indicates that the functionality has been modified in a backward-compatible manner, but H5P content will require some additional effort: While newly created content would know that it was created with the new 1.2 version, your existing content would still remember that it was created with 1.1 or an earlier version, and would require and use that library version. So even if you update the content type library to a later (minor) version, your existing content remains unchanged. This has some implications.

Why is this important?

1. Newer versions of a content type library may have fewer bugs, new features, better translations, better support for accessibility features, and so on. Existing content will not benefit if it continues to use an older version.
2. Since older content still requires older versions of a content type library, common H5P integrations such as the H5P plugin for WordPress do not allow you to delete the library – otherwise your content will no longer work. This means that more disk space is needed. You could argue that disk space is cheap, but admins may still not like to clutter it up.
3. H5P compound content types like Column or Course Presentation use other content types as subcontent. Instead of creating everything from scratch, you can paste your existing content into the compound content type. However, a compound content type can only handle one specific (minor) version of each subcontent. For example, if Column requires Fill in the Blanks 1.14, you cannot paste content created with Fill in the Blanks 1.6 or Fill in the Blanks 1.13. The corresponding paste button would be ghosted. So, over time, as your content assets grow and you accumulate different versions of content type libraries, the copy&paste feature would become completely useless.

What can I do?

The solution is simple: It is possible to upgrade existing H5P content to a newer library version. Upgrading H5P content means telling it to reference the newer library. Additionally, in some cases, the parameter structure may need to be changed. The latter may be part of another developer-oriented post 🙂

The H5P core provides several ways to upgrade H5P content, but not all of them may be supported by all H5P integrations in the same way!

Edit and save existing content

This is how you may have often upgraded H5P content without even knowing it. If you edit existing content and then save it, H5P will upgrade the content to the latest library version that is available on your platform.

Upload H5P content

This is essentially the same as the previous option if the content that you upload ends up in the editor and you are then required to save it.

Some H5P integrations may allow you to upload content directly without loading it to the editor first. Then this option for upgrading only works if the developers of the respective H5P integration explicitly trigger the upgrade. Moodle’s custom H5P integration in moodle core currently does not, for instance. Content that you upload to the content bank or to an activity in a course directly will not upgrade the content but use the old library version.

Batch upgrade

Your H5P integration most likely has an administration page for H5P library management, and that’s where you usually find a batch upgrade feature. For some reason this is not documented on h5p.org even though all the H5P plugins from H5P Group support it. So let’s go into a little more detail here.

On the library management page, you will find a list of all H5P content type libraries that are installed on your platform. There’s one entry for each minor library version. Each list entry for a content type library will show some details (see the official documentation on those). Furthermore, up to three buttons may appear on the right-hand side. One of them could be an arrow facing upward. If that arrow has a green background, then it means that there is content that could be upgraded.

In the screenshot above, you can see various entries for the Branching Scenario content type, i.e. there are several different (minor) versions installed. The entry for version 1.2.0 shows an arrow button with a green background, i.e. there is content that can be updated to a newer version – up to version 1.8, the latest installed minor version.

When you click on the arrow button, a new page will open asking you to select the library version you want to update to. Usually you choose the latest available version, in this case 1.8.9. If you then click on the “Upgrade” button, H5P will upgrade all content currently using Branching Scenario 1.2.0 to version 1.8.9. This may take a moment – and you will need to keep the browser tab open – but you will be notified of the progress.

Once the process is complete, you can return to the H5P library management page and check for more content that can be updated.

Sadly, moodle’s custom H5P integration does not offer a batch upgrade feature yet. There’s a ticket in MoodleHQ’s tracker that asks to add it, but it’s close to 4 years old now. Maybe you want to vote it up?

Good to know

1. After batch upgrading H5P contents, right above the list of installed libraries on the library management page, you should now see a “Rebuild cache” button. It’s not crucial, but it’s a good idea to press it. Otherwise, the first person that views an upgraded content will have to wait a second or two longer for it to display.
2. If you upgrade existing content via the batch upgrade process, e.g. Drag the Words, then it will only upgrade standalone Drag the Words contents. It will not upgrade Drag the Words content that is used as subcontent in Column, Question Set, etc.
3. Even if you upgraded all contents to the latest version, you may not be able paste content into content types such as Column. That’s because the parent content type may not yet be able to handle the latest version of the content that you want to paste. Unfortunately, this cannot be completely ruled out as maintainers of different content types may need to update their code. They may not know about this yet (hopefully H5P Group can establish an automated mechanism for checking for those inconsistencies and inform content type contributors) or – worst case – they have abandoned the content type.
4. It could be that you cannot paste content, because it’s still using an older version than the parent content type that you want to paste to expects. In theory, H5P core could upgrade the content to be pasted automatically, but unfortunately that’s not implemented yet. You will need to upgrade the content that you want to paste first.