You are here

Hello world tutorial

In this short tutorial, we will create a simple H5P package containing a library to display a greeting card consisting of an image and a message. This tutorial is primarily intended for H5P library developers.

Set up development environment

H5P development itself does not require any specific development tools. Your favourite code editor will do the trick although syntax highlighting for JavaScript and JSON is recommended.

For now, just create a working directory named "H5P.GreetingCard". We will fill it in further on in the tutorial.

You do need to set up a site with H5P support. H5P backend is currently implemented for Drupal (6 and 7), WordPress (3.8 and up) and Joomla (2.5) while other backends are in progress.

See installation instructions for the various supported frameworks here.

Create an H5P library

An H5P library is the code that handles display and interaction of an H5P. An H5P may include several libraries, and libraries may have dependencies to other libraries as well. H5Ps without libraries are not currently supported, there is always a main library for an H5P. In our little tutorial package, however, we only need the basic library for a greeting card. We will call it H5P.GreetingCard.

Step 1 - Specify the library metadata (library.json)

An H5P library needs to specify some metadata, so the various modules know how to identify it. This is done in the library.json file.

This identifies the library as "Greeting card". The specified machineName will be used internally, and should match the folder name of the library.

The preloadedJs option preloads your javascript file. This file is responsible for the display of your content, and will be defined in a later section.

Note that the patchVersion needs to be increased between uploads unless the H5P framework is set in "Development mode". If the patchLevel matches (or is lower than) the currently installed version, it will not be installed.

Step 2 - Specify library data structure (semantics.json)

The greeting card library consists of an image and a text. In order to make the greeting card editable we specify this in the semantics.json file for the library.

Add the file H5P.GreetingCard/semantics.json with the following content:

Have a look at the semantics specification to get an overview of what fields you can create and use in your content type, and what field options that exist for them.

Step 3 - Add library display code (js)

The library requires a little Javascript to display its content. The library attaches itself to the overall H5P object loaded by the framework and then needs to provide at least an "attach" method that will be called to make the library render into the destination page.

Add the file H5P.GreetingCard/greetingcard.js with the following content. (The recommended code structure for this may be a little overwhelming at first.)

The "attach" function is the only required method exported from a library. It will be called to tell the library to render into the supplied container object. How to perform the actual render is up to the library itself. In our case, we simply use jQuery DOM creation methods. More advanced libraries may want to use EmbeddedJS templates or other methods.

If you're using Drupal with the development folder enabled you should be able to create a greeting card now and display it, but it will lack styling.

Note that the library class receives H5P.jQuery in its initial creation. This is because H5P bundles its own copy of jQuery 1.9 to avoid conflict with other versions of jQuery in various site setups. It is always possible when H5P is available to access this as H5P.jQuery, but for simplicity we pass it in on module creation time, so the module see it as the '$' we're used to.

If you create a library that does not initiate like this, remember to always use the H5P.jQuery, as weird behaviour may result when mixing versions of jQuery used.

Step 4 - Add styling to library (css)

The initial rendering of the greeting card looks a bit dull. Let's spice it up by adding some styling. When doing changes to our library, we need to increase the patchVersion, making the final library.json file look like this:

Now if you're using Drupal with the development folder enabled you should be able to create greeting cards right away, and they should look something like this: tutorial-greeting-card

If you're not using Drupal you'll have to zip your library folder so that the library folder is in the root of the zip. Rename the .zip to .h5p and upload it through your sites library administration. Remember that you need development mode on for updates of your library to take effect (or you must increase the patch version every time)

If you're able to upload the library and view/edit the Greeting card, you have successfully completed this tutorial!

I am not sure what your setup is like, but debugging an H5P content type usually means using the debug functionality the browser gives you. In Google Chrome, for example, you could use the Developer Tools, where you e.g. can set breakpoints in the JavaScript and so on.

Including the ability to disable the necessity for patch versions when uploading library updates? I am asking this because I could swear that I enabled that setting about a month ago on a hosted wordpress site. Now that I am working locally on the same site I can't find it.