@explorendla/h5p-caretaker-client

v1.1.2

Published

3 months ago

JavaScript reference client for using H5P Caretaker

0High
0Medium
0Low

otacke

jan_lindso

H5P maintenance

H5P Caretaker client

Reference implementation of a JavaScript client using the H5P Caretaker library. It will not do anything on its own (!), but it requires the server-side H5P Caretaker library and a server-side integration, e.g. the H5P Caretaker server reference implementation.

Usage

You can see a fully working example on integrating this client in the the H5P Caretaker server reference implementation.

Instantiation

Load the h5p-caretaker-client-*.js file from the dist folder and h5p-caretaker-client-*.css file from the dist folder, e.g. with amending your HTML page's head with

  <link rel="stylesheet" href="node_modules/@explorendla/h5p-caretaker-client/dist/@explorendla/h5p-caretaker-client-1.0.0.css" />
  <script type="module" src="node_modules/@explorendla/h5p-caretaker-client/dist/@explorendla/h5p-caretaker-client-1.0.0.js"></script>

The exact path will depend on your setup, of course. Also note that the version number will need to be set in the path if you do not have set up some auto-retrieval anyway.

In your HTML page, you will need 4 things:

an element bearing the class name h5p-caretaker to scope the caretaker elements.
a child element bearing the class name dropzone that will be filled with the dropzone for uploading files and
a child element bearing the class name filter-tree that will be filled with the filter for choosing contents and
a child element bearing the class name output that will be filled with the reports.
a tiny piece of JavaScript that runs the H5PCaretaker and passes the upload endpoint at least.

So, assuming that ./upload.php is your endpoint, a very basic setup in the <body> could be

<div class="h5p-caretaker">
  <div class="dropzone"></div>
  <div class="filter-tree"></div>
  <div class="output">
</div>

<script>
document.addEventListener('DOMContentLoaded', () => {
  new H5PCaretaker({ endpoint: './upload.php' });
});
</script>

You will have to take care of additional styling yourself.

Session key

Your platform may support session keys that can/need to be set in the form in order to prevent cross-site request forgery. You can pass the session key name (sessionKeyName) and the session key value (sessionKeyValue) to the constructor, and they will be passed to the request.

Example for moodle (to satisfy require_sesskey())

<script>
document.addEventListener('DOMContentLoaded', () => {
  new H5PCaretaker({
    // endpoint and other parameters here, too
    sessionKeyName: 'sesskey', // `sesskey` is what moodle uses
    sessionKeyValue: '<Value returned by moodle's PHP `sesskey()`>'
  });
});
</script>

Localization

The client expects the constructor to be passed an l10n object holding key-value pairs for translatable strings. The values should be the desired translation for strings that the client uses. If not set, the client will fall back to the English defaults.

Example for English (despite being default anyway)

<script>
document.addEventListener('DOMContentLoaded', () => {
  new H5PCaretaker({
    // endpoint and other parameters here, too
    l10: {
      orDragTheFileHere: 'or drag the file here', // Dropzone: call to action
      removeFile: 'Remove file', // Dropzone: remove file button
      selectYourLanguage: 'Select your language', // Language select field
      uploadProgress: 'Upload progress', // Dropzone: upload progress
      uploadYourH5Pfile: 'Upload your H5P file', // Dropzone: upload call to action
      yourFileIsBeingChecked: 'Your file is being checked', // Dropzone: file is being checked
      yourFileWasCheckedSuccessfully: 'Your file check was completed', // Dropzone: file was checked successfully
      instructions: 'Now do all the changes that you deem necessary and download the edited version of your file.', // Dropzone: instructions after check
      totalMessages: 'Total messages', // Results: total messages
      issues: 'issues', // Results: issues
      results: 'results', // Results: results
      filterBy: 'Filter by', // Results: group by
      groupBy: 'Group by', // Results: group by
      download: 'Download', // Results: download
      download: 'Download edited H5P', // Results: download edited H5P
      allFilteredOut: 'All messages have been filtered out by content.', // MessageAccordion
      contentFilter: 'Content filter', // ContentFilter: filter by content
      showAll: 'Show all', // ContentFilter: show all
      showSelected: 'Various selected contents', // ContentFilter: show selected
      showNone: 'Show none', // ContentFilter: show none
      filterByContent: 'Filter by content:', // ContentFilter: filter by content
      reset: 'Reset', // ContentFilter: reset,
      showDetails: 'Show details', // MessageContent: show details
      hideDetails: 'Hide details', // MessageContent: hide details
      unknownError: 'Something went wrong, but I dunno what, sorry!', // General error message
      checkServerLog: 'Please check the server log.', // Ask for help
      expandList: 'Expand list', // Expand list
      collapseList: 'Collapse list', // Collapse list
      changeSortingGrouping: 'Change sorting/grouping', // Select results type
      nextMessage: 'Next message', // Carousel: next message
      previousMessage: 'Previous message', // Carousel: previous message
    }
  });
});
</script>

If you wish, you can implement your own language selection as seen in the reference server implementation.

Callbacks

The 2nd constructor argument is reserved for callback functions that you may want to be called when certain things happen. H5P Caretaker currently supports these:

onInitialized: Called when initialization is done.
onUploadStarted: Called when the file upload starts.
onUploadEnded: Called when the file upload ended. Will return true if successful, else false.
onReset: Called when the user resets the client.

Given that, the instantiazitaton could e.g. look like:

<script>
document.addEventListener('DOMContentLoaded', () => {
  new H5PCaretaker(
    {
      // endpoint and other parameters here
    },
    {
      onInitialized: () => {
        // Do something after initialization
      },
      onUploadEnded: (wasSuccessful) => {
        // Do something after the upload ended depending on the value of `wasSuccessful`
      }
    }
  });
});
</script>

Future Development

The UX will probably be changed/improved at some point.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme