H5P Ajax Endpoints
There are two ways of handling AJAX requests: You can use the out-of-the-box Express adapter or write your own custom router:
diagram of the architecture of the H5P Ajax endpoint
Handling requests with the Express adapter
Your implementation must process requests to several endpoints and relay them to the H5PEditor or H5PPlayer objects. All Ajax endpoints are already implemented in the Express adapter, which you can use like this:
Import the Express adapter router like this:
1
import h5pAjaxExpressRouter from '@lumieducation/h5p-express';
Copied!
or in classic JS style:
1
const h5pAjaxExpressRouter = require('@lumieducation/h5p-express');
Copied!
Then add the router to your Express app like this
1
app.use(
2
// server is an object initialized with express()
3
'/h5p', // the route under which all the Ajax calls will be registered
4
h5pAjaxExpressRouter(
5
h5pEditor, // an H5P.H5PEditor object
6
path.resolve('h5p/core'), // the path to the h5p core files (of the player)
7
path.resolve('h5p/editor'), // the path to the h5p core files (of the editor)
8
routeOptions, // the options are optional and can be left out
9
languageOverride // (optional) can be used to override the language used by i18next http middleware
10
)
11
);
Copied!
Note that the Express adapter does not include pages to create, editor, view, list or delete content!
You can customize which endpoints you want to use by setting the respective flags in the
options object. By default, the adapter will handle all routes and you can turn individual ones off by setting routeXX to false. You can also turn off the error handling (handleErrors: false). Normally, the router will send back localized responses that the H5P client can understand. If you turn error handling off, the routes will throw errors that you have to handle yourself!IMPORTANT: The adapter expects the requests object of Express to be extended like this:
1
{
2
user: IUser, // must be populated with information about the user (mostly id and access rights)
3
t: (errorId: string, replacements: {[key: string]: string }) => string
4
}
Copied!
The function
t must return the string for the errorId translated into the user's or the content's language. Replacements are added to the localized string with curly braces: It is suggested you use i18next for localization, but you can use any library, as long as you make sure the function t is added to the request object.Handling requests yourself
If you use a different HTTP framework than Express, you can write your own adapter. In this case, you must instantiate
H5PAjaxEndpoint and call its methods when your routes are called.The table below shows which routes you must implement and which ones can be left out. Note that routes of the Type H5P are needed by the H5P client and must be implemented in some way. Routes of the type custom are specific to @lumieducation/h5p-server. The exact name of the routes can be configured in IH5PConfig and might be different in your setup.
HTTP Verb
Route
method in H5PAjaxEndpoint
Type
Required
GET
/ajax
getAjax
H5P
yes
GET
/content
getContentFile
H5P
depends on content storage: files in FileContentStorage can also be served statically
GET
/libraries
getLibraryFile
H5P
depends on library storage: files in FileLibraryStorage can also be served statically
GET
/temp-files
getTemporaryFile
H5P
yes
POST
/ajax
postAjax
H5P
yes
GET
/params
getContentParameters
custom
if you use the default renderer script of the editor
GET
/download
getDownload
custom
no
Consult the documentation of
H5PAjaxEndpoint for details on who to retrieve the required parameters from the HTTP requests. You can also look at the Express Ajax Adapter as an example.Configuring custom endpoint routes
The H5P client (run in the browser by the user) can be configured to use custom AJAX request endpoints. These can be configured in the config object. The relevant settings (including defaults) are:
1
const config = {
2
ajaxUrl: '/ajax?action=', // URL prefix for all AJAX requests
3
baseUrl: '/h5p', // a prefix added to all Ajax URLs
4
contentFilesUrl: '/content',// base path for content files (e.g. images, video)
5
coreUrl: '/core', // URL of static player "core files"
6
downloadUrl: '/download', // URL to download h5p packages
7
editorLibraryUrl: '/editor',// URL of static editor "core files" (not the content types!)
8
librariesUrl: '/libraries', // URL at which library files (= content types) can be retrieved
9
paramsUrl: '/params' // URL at which the parameters (= content.json) of content can be retrieved
10
playUrl: '/play' // URL at which content can be displayed
11
... // further configuration values
12
}
Copied!
Last modified 6mo ago