h5p-php-library/doc/spec_en.html

<h2>Overview</h2>
<p>H5P is a file format for content/applications made using modern, open web technlogies (HTML5). The format enables easy installation and transfer of applications/content on different CMSes, LMSes and other platforms. An H5P canbe uploaded and published on a platform in mostly the same way one would publish a Flash file today. H5P files may also be updated by simply uploading a new version of the file, the same way as one would using Flash.</p>
<p>H5P opens for extensive reuse of code and wide flexibility regarding what may be developed as an H5P.</p>
<p>The system uses package files containing all necessary files and libraries for the application to function. These files are based on open formats.</p>
<h2>Overview of package files</h2>
<p>Package files are normal <em>zip</em> files, with a naming convention of <i>&lt;filename&gt;.h5p</i> to distinguish from any random zip file. This zip file then requires a specific file structure as described below.</p>
<p>There will be a file in JSON format named h5p.json describing the contents of the package and how the system should interpret and use it. This file contains information about title, content type, usage, copyright, licensing, version, language etc. This is described in detail below.</p>
<p>There shall be a folder for each included H5P library used by the package. These generic libraries may be reused by other H5P packages. As an example, a multi-choice question task may be used as a standalone block, or be included in a larger H5P package generating a game with quizzes.</p>
<h2>Package file structure</h2>
<p>A package contains the following elements:</p>
<ol>
<li>A mandatory file in the root folder named <i>h5p.json</i></li>
<li>An optional image file named <i>h5p.jpg</i>. This is an icon or an image of the application, 512 × 512 pixels. This image may be used by the platform as a preview of the application, and could be included in OG meta tags for use with social media.</li>
<li>One content folder, named <i>content</i>. This will contain the preset configuration for the application, as well as any required media files.</li>
<li>One or more library diractories named the same as the library's internal name.</li>
</ol>
<h2>h5p.json</h2>
<p>The <i>h5p.json</i> file is a normal JSON text file containing a JSON object with the following predefined properties.</p>
<p>Mandatory properties:</p>
<ul>
<li>title - Name of the package. Would typically be used as header for a page displaying the package.</li>
<li>language - Standard language code. Use 'en' for english, 'nb' for norwegian "bokmål". Neutral content use "und".</li>
<li>machineName - Machine readable name of the library. This is the name that will be used for the library folder in the package too.</li>
<li>preloadedDependencies - Libraries that must be loaded on init. Specified as a list of objects with machineName, majorVersion and minorVersion. One would normally list all dependencies here to allow the platform displaying the package to merge JS and CSS files before returning the page.</li>
<li>embedTypes - List of ways to embed the package in the web page. Currently "div" and "iframe" are supported.</li>
</ul><p>Optional properties:</p>
<ul><li>contentType - Textual description of the type of content.</li>
<li>description - Textual description of the package.</li>
<li>author - Name of author.</li>
<li>license - Kode for the content license. Use the following creative commons codes: cc-by, cc-by-sa, cc-by-nd, cc-by-nc, cc-by-nc-sa, cc-by-nc-nd. In addition for public domain: pd, and closed license: cr. More may be added later.</li>
<li>dynamicDependencies - Libraries that may be loaded dynamically during execution.</li>
<li>width - Width of the package content in cases where the package is not dynamically resizable.</li>
<li>height - Height of the package content.</li>
<li>metaKeywords - Suggestion for keywords for the application, as a string. May be used for OG meta tags for social media.</li>
<li>metaDescription - Suggestion for application metaDescription. May be used for OG meta tags for social media.</li>
</ul>
<h3>Eksempel på h5p.json:</h3>
<code>{ <br/>
  "title": "Biologi-spillet",<br/>
  "contentType": "Game",<br/>
  "utilization": "Lær om biologi",<br/>
  "language": "nb",<br/>
  "author": "Amendor AS", <br/>
  "license": "cc-by-sa", <br/>
  "preloadedDependencies": [ <br/>
  {<br/>
    "machineName": "H5P.Boardgame", <br/>
    "majorVersion": 1, <br/>
    "minorVersion": 0<br/>
  }, {<br/>
    "machineName": "H5P.QuestionSet", <br/>
    "majorVersion": 1, <br/>
    "minorVersion": 0<br/>
  }, {<br/>
    "machineName": "H5P.MultiChoice", <br/>
    "majorVersion": 1, "minorVersion": 0<br/>
  }, {<br/>
    "machineName": "EmbeddedJS", <br/>
    "majorVersion": 1, <br/>
    "minorVersion": 0<br/>
  } ], <br/>
  "embedTypes": ["div", "iframe"], <br/>
  "w": 635, <br/>
  "h": 500 <br/>
}</code>
<h2>The content folder</h2>
<p>Contains all the content for the package and its libraries. There shall be no content inside the library folders. The content folder shall contain a file named <i>content.json</i>, containing the JSON object that will be passed to the initializer for the main package library.</p>

<p>Content required by libraries invoked from the main package library will get their contents passed from the main library. The JSON for this will be found within the main content.json for the package, and passed during initialization.</p>

<h2>Library folders</h2>

<p>A library folder contains all logic, stylesheets and graphics that will be common for all instances of a library. There shall be no content or interface text directly in these folders. All text displayed to the end user shall be passed as part of the library configuration. This make the libraries language independent.</p>

<p>The root of a library folder shall contain a file name <i>library.json</i> formatted similar to the package's <i>hp5.json</i>, but with a few differences. The library shall also have one or more images in the root folder, named <i>library.jpg</i>, <i>library1.jpg</i> etc. Image sizes 512px × 512px, and will be used in the H5P editor tool.</p>

<p>Libraries are not allowed to modify the dokument tree in ways that will have consequences for the web site or will be noticable by the user without the library explicitly being initialized from the main package library or another invoked library.</p>

<p>The library shall always include a Javascript object function named the same as the defined library <i>machineName</i> (defined in <i>library.json</i> and used as the library folder name).  This object will be instantiated with the library options as parameter. The resulting object must contain a function <i>attach(target)</i> that will be called after instantiation to attach the library DOM to the main DOM inside <i>target</i></p>

<h3>Example</h3>
<p>A library called H5P.multichoice would typically be instantiated and attached to the page like this:</p>
<code>var multichoice = new H5P.multichoice(contentFromJson, contentId); <br/>
multichoice.attach($multichoiceContainer);</code>

<h2>library.json</h2>
<p>Mandatory properties:</p>
<ul>
<li>title - Human readable name of the library. May be used in the H5P editor and overviews of installed libraries.</li>
<li>majorVersion - Version major number. (The x in x.y.z). Positive integer.</li>
<li>minorVersion - Version minor number. (The y in x.y.z). Positive integer.</li>
<li>patchVersion - Version patch number. (The z in x.y.z). Positive integer. The system will automatically update to the latest patchVersion installed for all packages that use the library with the same major and minor version number. A new patch version must therefore not change any behaviour of the library, only fix errors.</li>
<li>machineName - Machine readable name for the library. Same as the folder name used.</li>
<li>preloadedJs - List of path to the javascript files required for the library.  At least one file need to be present (the one defining the library object). Paths are relative to the library root folder.</li>
</ul>
<p>Optional properties:</p>
<ul>
<li>author - Author name as text.</li>
<li>license - Code describing the library license. Use the following creative commons codes: cc-by, cc-by-sa, cc-by-nd, cc-by-nc, cc-by-nc-sa, cc-by-nc-nd. In addition use <i>pd</i> for public domain, and <i>cr</i> for closed source</li>
<li>description - Textual description of the library.</li>
<li>preloadedDependencies - Libraries that need to be loaded for this library to work. Specified as a list of objects with <i>machineName</i>, <i>majorVersion</i> and <i>minorVersion</i> for the required libraries.</li>
<li>dynamicDependencies - Libraries that may be loaded dynamically during library execution. Specified as a list of objects like preloadedDependencies above.</li>
<li>preloadedCss - List of paths to CSS files to be loaded with the library. Paths are relative to the library root folder.</li>
<li>w - Width in pixels for libraries that use a fixed width. Mandatory if the library shall be embedded in an iframe (see embedTypes below).</li>
<li>h - Height in pixels for libraries that use a fixed height. Mandatory if the library shall be embedded in an iframe (see embedTypes below).</li>
<li>embedTypes - List of possible ways to embed the package in the page. Available values are <i>div</i> and <i>iframe</i>.</li>
</ul>
<h3>Eksempel på library.json:</h3>
<code>{<br/>
  "title": "Boardgame", <br/>
  "description": "The user is presented with a board with several hotspots. By clicking a hotspot he invokes a mini-game.", <br/>
  "majorVersion": 1, <br/>
  "minorVersion": 0, <br/>
  "patchVersion": 6, <br/>
  "runnable": 1, <br/>
  "machineName": "H5P.Boardgame", <br/>
  "author": "Amendor AS", <br/>
  "license": "cc-by-sa", <br/>
  "preloadedDependencies": [ <br/>
  {<br/>
    "machineName": "EmbeddedJS", <br/>
    "majorVersion": 1, <br/>
    "minorVersion": 0<br/>
  }, {<br/>
    "machineName": "H5P.MultiChoice",<br/>
    "majorVersion": 1,<br/>
    "minorVersion": 0<br/>
  }, {<br/>
    "machineName": "H5P.QuestionSet",<br/>
    "majorVersion": 1,<br/>
    "minorVersion": 0<br/>
  } ],<br/>
  "preloadedCss": [ {"path": "css/boardgame.css"} ], <br/>
  "preloadedJs": [ {"path": "js/boardgame.js"} ], <br/>
  "w": 635, <br/>
  "h": 500 }</code>

<h2>Allowed file types</h2>
<p>Files that require server side execution or that cannot be regarded an open standard shall not be used. Allowed file types: js, json, png, jpg, gif, svg, css, mp3, wav (audio: PCM), m4a (audio: AAC), mp4 (video: H.264, audio: AAC/MP3), ogg (video: Theora, audio: Vorbis) and webm (video VP8, audio: Vorbis). Administrators of web sites implementing H5P may open for accepting further formats. HTML files shall not be used. HTML for each library shall be inserted from the library scripts to ease code reuse. (By avoiding content being defined in said HTML).</p>
<h2>API functions</h2>
<p>The following javascript functions are available through h5p:</p>
<ul>
<li>H5P.getUserData(namespace, variable)</li>
<li>H5P.setUserData(namespace, variable, data)</li>
<li>H5P.getUserStart(namespace)</li>
<li>H5P.setUserStop(namespace)</li>
<li>H5P.deleteUserData(namespace, variable)</li>
<li>H5P.getGlobalData(namespace, variable)</li>
<li>H5P.setGlobalData(namespace, variable, data)</li>
<li>H5P.deleteGlobalData(namespace, variable)</li>
</ul>
<p>I tillegg er følgende api funksjoner tilgjengelig via ndla:</p>
<ul>
<li>H5P.setUserScore(contentId, score, maxScore)</li>
</ul>
<h2>Best practices</h2>
<p>H5P is a very open standard. This is positive for flexibility. Most content may be produces as H5P. But this also allows for bad code, security weaknesses, code that may be difficult to reuse. Therefore the following best practices should be followed to get the most from H5P:</p>
<ul>
<li>Think reusability when creating a library. H5P support depencies between libraries, so the same small quiz-library may be used in various larger packages or libraries.</li>
<li>H5P support library updates. This enables all content using a common library to be updated at once. This must be accounted for when writing new libraries. A library should be as general as possible. The content format should be thought out so there are no changes to the required content data when a library is updated. Note: Multiple versions of a library may exists at the same time, only patch level updates will be automatically installed.</li>
<li>An H5P should not interact directly with the containing web site. It shall only affect elements within its own generated DOM tree. Elements shall also only be injected within the target defined on initialization. This is to avoid depencies to a specific platform or web page.</li>
<li>Prefix objects, global functions, etc with h5p to minimize the chance of namespace conflicts with the rest of the web page. Remember that there may also be multiple H5P objects inserted on a page, so plan ahead to avoid conflicts.</li>
<li>Content should be responsive.</li>
<li>Content should be WCAG 2 AA compliant</li>
<li>All generated HTML should validate.</li>
<li>All css should validate (some browser specific non-standard CSS may at times be required)</li>
<li>Best practices for javascript, html, etc. should of course also be followed when writing an H5P.</li>
</ul>