H5P-Nodejs-Library
  • README
  • Basic usage
    • Architecture
    • Integrating the core library
    • H5P Ajax Endpoints
    • Constructing H5PEditor
    • REST Example
  • Advanced usage
    • Authorization
    • User content state
    • Multiple user states per object
    • Impersonating users
    • Basic completion tracking
    • Localization
    • Cluster
    • Addons
    • Customization
    • Performance optimizations
    • Privacy
    • Forward proxy support
    • Security
  • NPM packages
    • h5p-mongos3
      • Mongo/S3 Content Storage
      • S3 Temporary File Storage
      • Mongo Library Storage
      • Mongo/S3 Library Storage
    • h5p-webcomponents
    • h5p-react
    • h5p-redis-lock
    • h5p-svg-sanitizer
    • h5p-clamav-scanner
  • Development
    • Getting started
    • Testing & code quality
    • Core updates
    • Project Status
Powered by GitBook
On this page
  • Installation
  • Adding the library to your project
  • Handling AJAX Requests made by the core H5P client
  • Serving static H5P core files for the client
  • Creating content views
  • Writing custom interface implementations
  • Calling maintenance functions regularly
  • Handling errors
  • Localization
  • Customization
  • Compliance and privacy

Was this helpful?

  1. Basic usage

Integrating the core library

PreviousArchitectureNextH5P Ajax Endpoints

Last updated 3 years ago

Was this helpful?

Installation

Add the library to a project by executing

npm install @lumieducation/h5p-server

Adding the library to your project

Note: The example snippets below use the to simplify dealing with promises. You can still use the traditional .then(()=> {...}) style if you wish so.

After installation, you can import the library in a JavaScript file with

const H5P = require('@lumieducation/h5p-server');

and instantiate the editor with

const h5pEditor = H5P.fs(
    await new H5P.H5PConfig(
        new H5P.fsImplementations.JsonStorage(
            path.resolve('examples/config.json') // the path on the local disc
            // where the configuration file is stored
        )
    ).load(),
    path.resolve('h5p/libraries'), // the path on the local disc where libraries
    // should be stored
    path.resolve('h5p/temporary-storage'), // the path on the local disc where
    // temporary files (uploads) should
    // be stored
    path.resolve('h5p/content') // the path on the local disc where content is
    // stored
);

To render a HTML page (server-side rendering) with the editor inside (= the HTML user interface around the actual editor and the editor itself) for a specific content ID, you call

const html = await h5pEditor.render(contentId, user);
// send the html to the browser, which will display it

To use a custom renderer, change it with

h5pEditor.setRenderer(model => /** HTML string or object **/);

You can also use a custom renderer that returns a plain object with the data required to display an H5P editor instead of HTML markup. If you return this data to the browser as a response to an Ajax call, you can also create Single Page Applications that don't rely on server-side rendering.

Handling AJAX Requests made by the core H5P client

Serving static H5P core files for the client

This application doesn't include the H5P JavaScript core files for the editor and the player. These are the files that make up the editor and player that the end user interacts with in the browser. The core files must be obtained separately:

You must add a route to your implementation that serves the static files found under h5p/core and h5p/editor to the endpoint configured in config.libraryUrl. The out-of-the-box Express adapter already includes a route for this.

Creating content views

While the AJAX communication between the actual H5P editor client (running in the browser) and the server (this application) can be fully handled by the Express adapter, you must still create custom views for these purposes:

  • View that is shown when creating new content

  • View that is shown when editing existing content

  • View for deleting content

  • View that lists existing content

  • View that plays content

The reason why you have to do this on your own is that this library is unaware of other data that your system might attach to a piece of content (e.g. access rights, tags). If you want any custom UI elements around the editor and player (which is highly likely), you must put this into the views. Check out the example for how to write custom views.

Writing custom interface implementations

Several aspects of your H5P server can be customized by creating your own implementation of interfaces and passing them to the constructor of H5PEditor. That way you can use a database of your choice, cache data in Redis or store user data in an object storage system.

The interfaces that can be implemented are:

  • IContentStorage

  • IH5PConfig

  • ILibraryStorage

  • ITemporaryFileStorage

  • IUser

There are already default implementations that you can use:

  • The implementations in the fs folder store all data in the local file system and are only for demonstration purposes and not suitable to be used in a multi-user environment and not optimized for speed. You might be able to use them in a cluster setup by using a network storage.

  • There is an implementation of the library file storage for MongoDB and S3-compatible storage systems.

Calling maintenance functions regularly

The implementation needs to call several function regularly (comparable to a cronjob):

  • Call H5PEditor.temporaryFileManager.cleanUp() every 5 minutes. This checks which temporary files have expired and deletes them if necessary. It is important to do this, as temporary files are not automatically deleted when a piece of content is saved.

  • Call H5PEditor.contentTypeCache.updateIfNecessary() every 12 hours. This will download information about the available content types from the H5P Hub. If you don't do this, users won't be shown new content types or updates to existing content types when they become available.

Handling errors

Calls to the library might also throw regular Error objects. In this case the error is not caused by the business logic, but by some more basic functionality (file system, other library) or it might be an error that is addressed at the developer (i.e. because function parameters aren't correctly used).

The Express adapter already catches errors, localizes them and returns proper HTTP status codes. Check out the implementation there for a guide how to deal with errors.

Localization

Customization

Compliance and privacy

This object is a server-side component that is long-lived and includes most of the methods that must be called when by the routes of your server. To find out what these routes are and how they must call H5PEditor, you can either check out the or the .

Check out the for inspiration or customization possibilities.

See for more details on how to instantiate the editor in a more customized way.

You can create objects in a similar way and use them in a similar fashion.

The H5P client (running in the browser) sends many AJAX requests to the server (this application). While this library provides you with everything required to process the requests in the backend, your implementation must still serve the requests to these endpoints. There is an Express adapter that you can use out-of-the box for this purpose. Check out the for details.

Download the and place them into a folder called h5p/core in your project.

Download the and place them into a folder called h5p/editor in your project.

There is an implementation of the content storage for MongoDB and S3-compatible storage systems. Check out more information .

There is an implementation of the temporary file storage for S3-compatible storage systems. Check out more information .

If something goes wrong and a call to the library can't continue execution, it will normally throw either a H5PError or an AggregateH5PError (a collection of several errors). Both errors types represent errors that can be sent to the user to be displayed in the client (in the user's language). They don't include the English error message but an error id that you must translate yourself. Error ids and their English translations can be found in [/packages/h5p-server/assets/translations]. The translation strings follow the format used by , but in theory you can use any localization library.

This library supports localization. See the for more details.

An application using @lumieducation/h5p-server can customize the way H5P behaves in several ways. See for more details.

To conform with local law, you probably have to compile a privacy declaration for your application. You can check out the to find out what this library does with your users' personal data.

ES2017 async await language features
default editor renderer
the documentation page on constructing a H5PEditor object
H5PPlayer
documentation on endpoints
Core files
Editor files
in the documentation page
in the documentation page
i18next
respective documentation page
the documentation page on customization
documentation page on privacy
Express example project
section on content views in the docs