diff --git a/README.md b/README.md index 4c3c247..cad368c 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,12 @@ The player can be set up either by directly calling the already built scripts an new H5PStandalone.H5P(el, options); ``` - A detailed description of the H5P player arguments are provided under the [advance section](#advanced-usage) - Simple instruction on how to extract H5P zipped file provided [here](#extracting-h5p) + +A detailed description of the H5P player arguments are provided under the [advanced usage section](#advanced-usage) + +Simple instructions on how to extract H5P zipped files are provided in the [extracting H5P section](#extracting-h5p) + +If you'd like a simple, step by step setup guide to direct usage, please see the [Basic setup guide](docs/basic-setup-guide.md) ### Using ES6 Install the player using yarn diff --git a/docs/basic-setup-guide.md b/docs/basic-setup-guide.md new file mode 100644 index 0000000..1abf979 --- /dev/null +++ b/docs/basic-setup-guide.md @@ -0,0 +1,187 @@ +# H5P Standalone direct use guide + +Jan 2025 + +A simple setup / "hello world" guide to get H5P Standalone player +up and running for people not so familiar with front end web +development. We'll use the "direct use" style. + +## Basic page and a web server + +Let's get a web server up and serving a local page. + +First, create a directory for our demo to live in: + +```bash +mkdir h5p-standalone-demo +cd h5p-standalone-demo +``` + +Next we need to create an `index.html` file. Use your favourite +text editor and copy the text below: + +```html + + + + + + H5P Standalone Demo + + + + + + +

H5P container below:

+ +
+ + +``` + +You can use almost any web server but for demonstration purposes +we'll use use one of these two. + +If you have [Docker](https://docs.docker.com/engine/install/) installed +then we can use [Nginx](https://nginx.org/): + +```bash +sudo docker run -it --rm -v $(pwd):/usr/share/nginx/html -p 8080:80 nginx:stable-alpine +``` + +If you don't have docker installed but do have Python 3 available +we can use Python's built in server: + +```bash +python3 -m http.server +``` + +At this point you should be able to open a browser and go to +`http://localhost:8080/`. You should be able to see the text +"H5P container below:" on the page. + +## Add H5P Standalone + +In another terminal window or tab (so we can leave the web server +running), change into your `h5p-standalone-demo` directory +and make an `assets/h5p-standalone` directory: + +```bash +mkdir -p assets/h5p-standalone +``` + +Now we need to get the zip file from the latest [release](https://github.com/tunapanda/h5p-standalone/releases/latest). + +At the time of writing, this is 3.8.0. We can now unzip the release +into our new `assets/h5p-standalone` directory: + +```bash +unzip ~/Downloads/h5p-standalone-3.8.0.zip -d assets/h5p-standalone +``` + +This should create a directory structure something like this: +```bash +find . -type d + +. +./assets +./assets/h5p-standalone +./assets/h5p-standalone/dist +./assets/h5p-standalone/dist/fonts +./assets/h5p-standalone/dist/fonts/open-sans +./assets/h5p-standalone/dist/styles +./assets/h5p-standalone/dist/images +``` + +Now we can edit the `index.html` file to load the player. + +1) Add the ` + + + +

H5P container below:

+ +
+ + + + + +``` + +At this point we have the player all setup but we don't have any H5P +content to play, so let's get some. + +## Unzip the .h5p file + +In this example we'll use the [Question Set](https://h5p.org/question-set) +example from h5p.org. In the bottom left of the example on h5p.org +is a 'Reuse' button. Click that and choose "Download as an .h5p file". + +At the time of writing, this gives us "question-set-616.h5p". + +1) Make a directory to put the H5P content in: + +```bash +mkdir h5p +``` + +The name of this directory must match the `h5pJsonPath` value above. + +2) Unzip the h5p file into our new directory + +```bash +unzip ~/Downloads/question-set-616.h5p -d h5p +``` + +We're now left with a directory structure something like this: + +```bash +find . -type d + +. +./h5p +./h5p/content +./h5p/content/images +./h5p/H5P.QuestionSet-1.20 +./assets +./assets/h5p-standalone +./assets/h5p-standalone/dist +./assets/h5p-standalone/dist/fonts +./assets/h5p-standalone/dist/fonts/open-sans +./assets/h5p-standalone/dist/styles +./assets/h5p-standalone/dist/images +``` + +If you reload the page, you should see your H5P content! + +Hopefully by now the main [README.md](/README.md) documentation makes more sense. + +If you'd like some kind of loading indicator, see the +[Loading indicator guide](loading-indicator-guide.md). diff --git a/docs/loading-indicator-guide.md b/docs/loading-indicator-guide.md new file mode 100644 index 0000000..34d3a95 --- /dev/null +++ b/docs/loading-indicator-guide.md @@ -0,0 +1,283 @@ +# A simple loading indicator guide + +Jan 2025 + +If your users are not on a fast connection, sometimes it can take +a few seconds to load all the H5P libraries, images and videos +that you need to display the H5P content. + +In this case it can be useful to show the users that something +is happening while they wait. + +## Prerequisites + +This guide assumes that you've read the [Basic Setup Guide](basic-setup-guide.md) +and have a working H5P Standalone player. + +## Loading text + +First we need a little custom JavaScript to tell the main page when +the H5P frame has loaded. We'll add a `custom-js` directory to keep +our custom JavaScript file in: + +```bash +mkdir assets/h5p-standalone/custom-js +``` + +Now we can create the `assets/h5p-standalone/custom-js/finished-loading.js` +file, use your favourite text editor and add this: + +```javascript +// Filename: assets/h5p-standalone/custom-js/finished-loading.js +const bc = new BroadcastChannel('h5p-loading'); +bc.postMessage('h5p-finished-loading'); +``` + +Next we need to edit the `index.html` file. We'll be adding +the ` + + + +

H5P container below:

+ +
+
+

Loading ...

+
+
+ + + + + +``` + +### How does it work? + +As the H5P Standalone player loads the H5P content, it creates an +[iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) +for the content to render inside. The `customJs` option allows us +to load some custom JavaScript _inside_ the iframe. + +We can then use a [Broadcast Channel](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) +to let the parent page know that the iframe has rendered, which +means we can hide the loading message. This works because the +iframe and the parent page are running from the same [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin). + +You can think of the Broadcast Channel like a fanout in a messaging +system. Or like an FM radio broadcast, anyone that's listening +on that frequency (or in our case, the 'topic' of 'h5p-loading') +will hear the message. + +### How to see it working? + +You may find that your H5P content loads so fast that it's hard to +see the loading message, especially if you're running the web +server locally. + +Both Firefox and Chrome have a throttling feature in their developer +tools that lets you mimic a slower connection. + +If you right click on the page and choose 'inspect' this will +bring up the developer tools. + +In the 'Network' tab, you should find a drop down next to the 'Disable Cache' +checkbox that by default says 'No throttling'. If you choose a +regular 3G preset and reload the page, you should now be able to +see your loading indicator before the H5P content replaces it. + +### Tuning + +Without tuning, this could create some jumps while loading because +we don't know the height of the H5P element until it's loaded +(sometimes know as CSS jank). + +To mitigate this, you can match the `height` of your loading +box to the height of your H5P element (once you know what it is): + +```css + +``` + +## Fancier spinner + +If you'd like a fancier version, you could use some CSS animation +to spin a spinner while the H5P content loads. + +```html + + + + + + H5P Standalone Loading Spinner Demo + + + + + + + + + +

H5P container below:

+ + +
+ + + + + +``` + +This uses SVG symbols from Google's [Material Symbols](https://fonts.google.com/icons?selected=Material+Symbols+Outlined:progress_activity:FILL@0;wght@400;GRAD@0;opsz@24&icon.query=loading&icon.size=24&icon.color=%235f6368) +but you could swap these SVGs for one of your own creations, just +don't forget to add the `` (description) so that screen readers +have something to read. + +This will spin the 'dynamic' spinner image unless the user prefers +reduced motion, in which case it'll show the 'static' SVG. + +There are many ways to create loading indicators, these are just +two examples. Have fun and see what you can create!