Customization

H5P-Nodejs-Library
Github Twitter Homepage
Search…
README
Performance optimizations
Privacy
Forward proxy support
NPM packages
Development
Customization
An application using @lumieducation/h5p-server can customize the way H5P behaves in several ways:
You can add global custom JavaScript or CSS files to the player and editor by passing their URL to the constructor of H5PPlayer or H5PEditor. Use this method if you want to globally customize how H5P looks or behaves to make it fit into your larger application. See below for more details.
You can add global custom JavaScript or CSS files to the player and editor by specifying them in the configuration. Use and document this method if you want to allow administrators of an instance of your application to customize how H5P looks and feels in their instance. See below for more details.
You can upload addons. This makes changing how H5P looks and behaves particularly easy, but requires the creation of addons. See the addon documentation page for details.
You can alter the scripts and styles used in a single library. This allows you to change the looks and behavior of a library without forking it. See below for more details
You can alter the semantics and language files of a single library. This allows you to change the default editor of libraries without forking the library itself. See below for more details.
To get a conceptual idea of how customizing works, you can also look at the official H5P documentation pages on "Authoring tool customization" and "Change the color of the editor". Of course, all the programming guides there only apply to the PHP implementation and not this to NodeJs version, but the basic idea is the same!
Adding custom scripts and styles via constructor injection
You can add custom scripts and styles to the player by passing their URLs to the options parameter of the constructor of H5PPlayer or H5PEditor:
1
const player = new H5PPlayer(
2
    libraryStorage,
3
    contentStorage,
4
    config,
5
    integrationObjectDefaults, // set to undefined if unneeded
6
    urlGenerator, // set to undefined if unneeded
7
    translationFunction,
8
    {
9
        customization: {
10
            global: {
11
                scripts: [
12
                    '/url/of/script/1.js',
13
                    'https://example.com/external/script.js'
14
                ],
15
                styles: [
16
                    '/url/of/style/1.js',
17
                    'https://example.com/external/style.css'
18
                ]
19
            }
20
        }
21
    }
22
);
Copied!
-or-
1
const editor = new H5PEditor(
2
    cache,
3
    config,
4
    libraryStorage,
5
    contentStorage,
6
    translationCallback, // set to undefined if unneeded
7
    urlGenerator, // set to undefined if unneeded
8
    {
9
        customization: {
10
            global: {
11
                scripts: [
12
                    '/url/of/script/1.js',
13
                    'https://example.com/external/script.js'
14
                ],
15
                styles: [
16
                    '/url/of/style/1.js',
17
                    'https://example.com/external/style.css'
18
                ]
19
            }
20
        }
21
    }
22
);
Copied!
These scripts or styles will then be added to the end of the list of H5P scripts that are loaded when the player or editor are loaded. Note that the URLs in the arrays are simply appended to the list of core scripts and styles without any changes. This means that they are not passed into URL generator!
Adding custom scripts and styles via the configuration
You can add lists of global JavaScript or CSS files to the configuration like this:
1
{
2
    // ... further configuration values ...
3
    "customization": {
4
        "global": {
5
            "editor": {
6
                "scripts": [
7
                    "/url/of/script/1.js",
8
                    "https://example.com/external/script.js"
9
                ],
10
                "styles": [
11
                    "/url/of/style/1.css",
12
                    "https://example.com/external/style.css"
13
                ]
14
            },
15
            "player": {
16
                "scripts": [
17
                    "/url/of/script/1.js",
18
                    "https://example.com/external/script.js"
19
                ],
20
                "styles": [
21
                    "/url/of/style/1.css",
22
                    "https://example.com/external/style.css"
23
                ]
24
            }
25
        }
26
    }
27
    // ... further configuration values ...
28
}
Copied!
These scripts or styles will then be added to the end of the list of H5P scripts that are loaded when the player or editor are loaded. Note that the URLs in the arrays are simply appended to the list of core scripts and styles without any changes. This means that they are not passed into URL generator!
Changing JavaScript and CSS files of individual libraries
You can change the list of JavaScript and CSS files used by individual libraries to modify their looks and behavior. It is possible to add or to remove files from the lists. To do this you must pass a hook to the options object of the H5PEditor or H5PPlayer constructor.
The hook looks like this:
1
/**
2
 * This hook is called when the player creates the list of files that
3
 * are loaded when playing content with the library.
4
 * Note: This function should be immutable, so it shouldn't change the
5
 * scripts and styles parameters but create new arrays!
6
 * @param library the library that is currently being loaded
7
 * @param scripts the original list of scripts that will be loaded
8
 * @param styles the original list of styles that will be loaded
9
 * @returns the altered lists of scripts and styles
10
 */
11
const alterLibraryFilesHook = (
12
    library: ILibraryName,
13
    scripts: string[],
14
    styles: string[]
15
): { scripts: string[]; styles: string[] } => {
16
    // We only alter the files of a single library
17
    if (library.machineName === 'H5P.Example') {
18
        return {
19
            // The function should be immutable, so we re-create the arrays
20
            scripts: [...scripts, '/url/of/script.js'],
21
            styles: [...styles, '/url/of/style.css']
22
        };
23
    }
24
    // We return the original list for all other libraries.
25
    return { scripts, styles };
26
};
Copied!
It is passed to H5PPlayer like this:
1
const player = new H5PPlayer(
2
    libraryStorage,
3
    contentStorage,
4
    config,
5
    integrationObjectDefaults, // set to undefined if unneeded
6
    translationFunction,
7
    urlGenerator, // set to undefined if unneeded
8
    {
9
        customization: {
10
            alterLibraryFiles: alterLibraryFilesHook
11
        }
12
    }
13
);
Copied!
It is passed to H5PEditor like this:
1
const editor = new H5PEditor(
2
    cache,
3
    config,
4
    libraryStorage,
5
    contentStorage,
6
    translationCallback, // set to undefined if unneeded
7
    urlGenerator, // set to undefined if unneeded
8
    {
9
        customization: {
10
            alterLibraryFiles: alterLibraryFilesHook
11
        }
12
    }
13
);
Copied!
Changing the semantics of individual libraries
It is possible to change the semantic structure of individual libraries without uploading a fork of the library. This allows you to remove or add fields in the H5P Editor. You can also change what HTML tags are allowed in the CKEditor, for instance. As the structure of the language files (which include all the translations) is identical to the semantic structure of the library, you must also make sure that the language files are changed as well. @lumieducation/h5p-server allows you to pass two hooks in the options of the H5PEditor constructor to achieve this:
1
/**
2
 * This hook is called when the editor retrieves the semantics of a
3
 * library.
4
 * Note: This function should be immutable, so it shouldn't change the
5
 * semantics parameter but return a clone!
6
 * @param library the library that is currently being loaded
7
 * @param semantics the original semantic structure
8
 * @returns the changed semantic structure
9
 */
10
const alterLibrarySemanticsHook = (
11
    library: ILibraryName,
12
    semantics: ISemanticsEntry[]
13
): ISemanticsEntry[] => {
14
    // We only change the semantic structure of one library
15
    if (library.machineName === 'H5P.TrueFalse') {
16
        // We create a new array, as the function is supposed to be immutable.
17
        return [
18
            {
19
                name: 'title2',
20
                type: 'text',
21
                widget: 'html',
22
                label: 'Title 2',
23
                enterMode: 'p',
24
                tags: ['strong', 'em', 'sub', 'sup', 'h2', 'h3', 'pre', 'code']
25
            },
26
            ...semantics
27
        ];
28
    }
29
    // We return an unchanged structure for all other libraries
30
    return semantics;
31
};
32
/**
33
 * This hook is called when the editor retrieves the language file of a
34
 * library in a specific language.
35
 * Note: This function should be immutable, so it shouldn't change the
36
 * languageFile parameter but return a clone!
37
 * @param library the library that is currently being loaded
38
 * @param languageFile the original language file
39
 * @param language the language for which the entries should be changed
40
 * @returns the changed language file
41
 */
42
const alterLibraryLanguageFileHook = (
43
    library: ILibraryName,
44
    languageFile: ILanguageFileEntry[],
45
    language: string
46
): ILanguageFileEntry[] => {
47
    // We only change the language file of one library
48
    if (library.machineName === 'H5P.TrueFalse') {
49
        // We create a new array, as the function is supposed to be immutable.
50
        return [
51
            // The language file has the same structure as the semantics file
52
            // but only includes localizable fields.
53
            {
54
                name: 'title2',
55
                label: 'Title 2'
56
            },
57
            ...languageFile
58
        ];
59
    }
60
    // We return an unchanged language file for all other libraries
61
    return languageFile;
62
};
Copied!
Add these hooks to the constructor of H5PEditor like this:
1
const editor = new H5PEditor(
2
    cache,
3
    config,
4
    libraryStorage,
5
    contentStorage,
6
    translationCallback, // set to undefined if unneeded
7
    urlGenerator, // set to undefined if unneeded
8
    {
9
        customization: {
10
            alterLibraryLanguageFile: alterLibraryLanguageFileHook,
11
            alterLibrarySemantics: alterLibrarySemanticsHook
12
        }
13
    }
14
);
Copied!
The changes to the semantic structure apply system-wide to all instance of the library in the editor. It doesn't make sense to customize the player this way, as the semantic structure and language files are only used by the editor.
Exporting (downloading) and uploading content in the same application (or an application that uses the same hooks) works, but only the content.json file follows the altered semantic structure. The actual library's semantic.json file is left unchanged in the exported package. This means that if you upload an exported package with an altered semantic structure of the content to a different site, you might bump into validation errors or unexpected behavior.
Addons
Performance optimizations
Last modified 6mo ago
Copy link
Contents
Adding custom scripts and styles via constructor injection
Adding custom scripts and styles via the configuration
Changing JavaScript and CSS files of individual libraries
Changing the semantics of individual libraries