Hello world tutorial

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.

We recommend using Drupal and the H5P development folder, more about it 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.

Create the file H5P.GreetingCard/library.json containing the following:

{
  "title": "Greeting card",
  "description": "Displays a greeting card",
  "majorVersion": 1,
  "minorVersion": 0,
  "patchVersion": 0,
  "runnable": 1,
  "author": "Amendor AS",
  "license": "cc-by-sa",
  "machineName": "H5P.GreetingCard",
  "coreApi": {
    "majorVersion": 1,
    "minorVersion": 0
  },
  "preloadedJs": [
    { "path": "greetingcard.js" }
  ],
  "preloadedCss": [
    {"path": "greetingcard.css"}
  ]
}

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:

[ 
  { 
    "label": "Greeting text", 
    "name": "greeting", 
    "type": "text", 
    "default": "Hello world!", 
    "description": "The greeting text displayed to the end user." 
  }, 
  {
    "label": "Card image",
    "name": "image",
    "type": "image",
    "optional": true,
    "description": "Image shown on card, optional. Without this the card will show just the text."
  }
]

The semantics specifies the input data format used, as well as defining how the editor will display the fields when editing/creating a greeting card in the browser. (See example of editor below)

gc-screenshot-1.JPG

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.)

var H5P = H5P || {};

H5P.GreetingCard = (function ($) {
  /**
   * Constructor function.
   */
  function C(options, id) {
    // Extend defaults with provided options
    this.options = $.extend(true, {}, {
      greeting: 'Hello world!',
      image: null
    }, options);
    // Keep provided id.
    this.id = id;
  };

  /**
   * Attach function called by H5P framework to insert H5P content into
   * page
   *
   * @param {jQuery} $container
   */
  C.prototype.attach = function ($container) {
    // Set class on container to identify it as a greeting card
    // container.  Allows for styling later.
    $container.addClass("h5p-greetingcard");
    // Add image if provided.
    if (this.options.image && this.options.image.path) {
      $container.append('<img class="greeting-image" src="' + H5P.getPath(this.options.image.path, this.id) + '">');
    }
    // Add greeting text.
    $container.append('<div class="greeting-text">' + this.options.greeting + '</div>');
  };

  return C;
})(H5P.jQuery);

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:

{
  "title": "Greeting card",
  "description": "Displays a greeting card",
  "majorVersion": 1,
  "minorVersion": 0,
  "patchVersion": 1,
  "runnable": 1,
  "author": "Amendor AS",
  "license": "cc-by-sa",
  "machineName": "H5P.GreetingCard",
  "coreApi": {
    "majorVersion": 1,
    "minorVersion": 0
  },
  "preloadedJs": [
    { "path": "greetingcard.js" }
  ],
  "preloadedCss": [
    { "path": "greetingcard.css" }
  ]
}

Then create the CSS file as "H5P.GreetingCard/greetingcard.css". Add the following styles

.h5p-greetingcard {
  width: 400px;
  margin: 0 auto;
  border: 1px solid #ccc;
  box-shadow: 2px 2px 4px #ccc;
}
.h5p-greetingcard .greeting-image {
  width: 100%;
  height: auto;
}
.h5p-greetingcard .greeting-text {
  width: auto;
  margin: 16px;
  font-family: fantasy;
  font-size: 20px;
  font-weight: bold;
  line-height: 24px;
  text-align: center;
}

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! 

You may also choose to manually create an H5P package with content.

You might also want to support translations.

Good luck creating your own H5P libraries! If you get stuck, reach out to the community in the forums.