H5P Extractor - proof of concept

Tool that is supposed to be be usable for rendering H5P content server-side.

VERY IMPORTANT NOTE

The H5PExtractor library needs to ship with H5P core as a dependency. See https://packagist.org/packages/h5p/h5p-core. As of writing 1.26 is the latest version that has been released, but the H5P plugin for WordPress had not received proper attention for a long time, and used and required 1.24. API changes from 1.24 to 1.26 were not implemented in the WordPress plugin until plugin version 1.16.

When H5PExtractor is used, it will reference H5P core 1.26 which will cause trouble if you are still using the H5P plugin in a version prior to 1.16.

In consequence, if you want to use H5PExtractor, you should update the H5P plugin for WordPress to version 1.16 at least or pin the h5p-core dependency in composer.json to 1.24.4 by changing "h5p/h5p-core": "^1.26.0" to "h5p/h5p-core": "1.24.4". If you do the latter, make sure to remember to change the dependency when you ultimately update the H5P plugin for WordPress.

Quick start (to be done properly (!))

1. Copy the library to your ow project. You can also use composer, but you will need to fetch the library from github, because it is not available via packagist (yet).

   Your composer.json file should contain

   "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/otacke/H5PExtractor"
        }
    ],
    "require": {
        "snordian/h5p-extractor": "dev-master"
   }
   

   and any other of your dependencies, of course.

2. Use require_once <path_to_h5p-extractor> . '/app/H5PExtractor.php'; to load code. It does autload everything it needs, but it is not instantiated by any autoload itself, because it it seems appropriate to only load H5PExtractor once actually needed.

3. Use $h5pExtractor = new H5PExtractor\H5PExtractor($config); to create an instance, where $config is supposed to be an optional an associative array containing configuration items, e.g.:

   $config = [
     'uploadsPath' => <path to be used for uploads relative to h5p-extractor : string>
     'renderWidth' => <the assumed viewport width : number, default: 1024>
     'renderWidths' => [
      '<machineName: string>' => <the assumed viewport width : number>,
     ]
     'target' => <specific target as option : ['print|screen'], default: 'print'>
     'scope' => <specific scope as option : ['all|initial'], default: 'all'>
     'customCssPre' => <custom CSS to be applied before H5P core/content CSS is set : string>
     'customCssPost' => <custom CSS to be applied after H5P core/content CSS is set : string>
     'h5pCoreUrl' => <full URL to `h5p-php-library/` folder to use as core asset source : string>
     'h5pLibrariesUrl' => <full URL to `libraries/` folder to use as content type asset source : string>
     'h5pContentUrl' => <full URL to `content/<id>/` folder to use author defined content as source>
   ]
   

   By default, if that value is not set or no $config argument is passed, H5PExtractor will

   • try to create/use a directory named uploads inside its main h5p-extractor directory,
   • use a default render width of 1024 pixels,
   • use the default or set render width if no machineName specific render width was set for a particular content type,
   • not apply and custom CSS,
   • return base64 encoded representations of files inside the file if no Url to core, libraries or the content is set.

   Please ensure that the respective uploads directory can be read and written by your server process.

4. Use something like

   $extract = $h5pExtractor->extract(
       [
           'file' => $file['tmp_name'],
           'format' => $_POST['format']
       ]
   );
   

   where

   • file is supposed to be the H5P file that contains the H5P content that is supposed to be rendered - here a standard temporary file generated by a form upload.
   • format specifies the desired output format (currently html (default) or text) - here the format key of the form upload.

   The return value is an associative array with the key result or error.

   • result contains the requested output format
   • error contains an error message if something went wrong.

Creating/changing generators

A generator is what creates a distinct output format from an H5P content. It will commonly be HTML or some plain text variant, but could be something different, too.

The generation process resembles how the H5P core composes H5P content from different content types, and methods such as newRunnable or attach were called that way because they have direct counterparts in H5P core/a content type. They also use the same arguments, even though they're not all required here. If you know newRunnable or attach, then you already know what they do here. And if you don't and learn what they do here, you learn something about H5P core and H5P content types as a side product :-)

TODO: Explain Structure

TODO: Explain Generator

TODO: Explain GeneratorInterface

Open issues:

• Implement handling of target and scope where needed
• Add option to display answers for questions