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.
You can see a fully working example on integrating this client in the the H5P Caretaker server reference implementation.
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-caretakerto scope the caretaker elements. - a child element bearing the class name
dropzonethat will be filled with the dropzone for uploading files and - a child element bearing the class name
filter-treethat will be filled with the filter for choosing contents and - a child element bearing the class name
outputthat 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.
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>
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
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
expandAllMessages: 'Expand all messages', // MessageAccordion: expand all messages
collapseAllMessages: 'Collapse all messages', // MessageAccordion: collapse all messages
allFilteredOut: 'All messages have been filtered out by content.', // MessageAccordion
reportTitleTemplate: 'H5P Caretaker report for @title', // Report: report title template
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
}
});
});
</script>
If you wish, you can implement your own language selection as seen in the reference server implementation.
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
trueif successful, elsefalse. - 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>
Will at some point learn to edit fields and to send requests to the integration to save them to an H5P file.