docs: Update installation and usage docs#175
Merged
Merged
Conversation
This commit significantly revises the "Previous state restoration"
section in README.md to provide clearer, more accurate, and
detailed guidance on managing your progress.
Key changes:
- Clearly distinguishes between user state (for saving progress)
and xAPI data (for reporting to an LRS).
- Details two distinct methods for state management:
1. Manual User State Management:
- Updated explanations on using `contentUserData` for initial
state and `window.H5PIntegration.contents['cid-{content-id}'].contentUserData`
for retrieval.
- Incorporated a comprehensive JavaScript example demonstrating
how to save and load state (e.g., using localStorage).
2. Automated User State Management:
- Added a new, detailed example of the `options` configuration,
including `saveFreq`, `ajax.contentUserDataUrl`, and the `user`
object.
- Emphasized that `saveFreq`, `ajax.contentUserDataUrl`, and
the `user` object (with `name` and `mail`) are **required**
for this method.
- Included a tip for developers to observe network requests
to understand the backend implementation requirements.
- Clarified the role and importance of the `saveFreq` option for
both methods.
- Corrected the description of the `contentUserData` option in the
main options table to expect an Array of objects.
These changes address your feedback and aim to make the process of
implementing user state persistence more understandable for developers.
This commit improves the structure and clarity of the "Installation & Usage"
section in README.md based on your feedback.
Key changes:
- Unified "Installation" and "Basic Usage" into a single, more
logical "Installation & Usage" section.
- Clearly correlated installation methods with their respective usage
patterns:
- "Using a Package Manager (Recommended)" (yarn/npm) now directly
leads to "Usage with ES6 Imports".
- "Manual Installation (Direct use in HTML)" (downloading release)
now directly leads to "Usage with Manual Installation".
- Clarified the "Usage with ES6 Imports" section:
- Renamed to "Usage with ES6 Imports (e.g., in React, Vue, Svelte, Angular projects)"
to better reflect its context.
- Added an introductory sentence explaining its suitability for
projects with module bundlers and build steps (e.g., Webpack,
Rollup used in modern JavaScript frameworks).
- Ensured headings and introductory texts provide a smooth and logical
flow for you.
- Removed a potentially confusing comment about UMD global access from
the ES6 import example.
These changes aim to make it easier for you to choose an installation
method and quickly find the corresponding setup and usage instructions.
…d on your feedback, improving its order, adding CDN usage instructions, and updating package manager information.
Key changes:
- Reordered installation methods:
- "Manual Installation (Direct use in HTML)" is now presented first, followed by "Installation using a package manager".
- Updated "Manual Installation (Direct use in HTML)" section:
- Added a new subsection "A) Using a CDN (Content Delivery Network)" with instructions and examples for using jsDelivr to link `h5p.css`, `main.bundle.js`, and `frame.bundle.js`.
- Included a recommendation to pin to specific versions in production.
- The existing download method is now under "B) Downloading and Self-Hosting Files".
- Added `charset="UTF-8"` to script tags and wrapped JS initialization in `DOMContentLoaded` for self-hosted example.
- Updated "Installation using a package manager" section:
- Removed the "(Recommended)" label from the title.
- Added `pnpm` as an example package manager alongside `yarn` and `npm`.
These changes aim to provide a more intuitive flow for you and offer more flexible installation options.
This commit incorporates several corrections and clarifications into
the README.md based on your detailed feedback.
Key changes include:
1. **CDN Asset Flexibility**: I clarified in the CDN usage example
that `frameJs` and `frameCss`, while recommended to be from the
same CDN source as `main.bundle.js` for version consistency,
can technically be sourced from different locations.
2. **Removed Endorsement**: I removed a sentence mentioning "Lumi"
from the "Working with H5P Content" section and the FAQ to avoid
specific platform endorsements.
3. **MathJax Example Relocation**:
- I moved the detailed `customJs` example for loading MathJax
(CDN, local, multiple scripts) from the "Advanced Usage"
example to the "Frequently Asked Questions (FAQ)" section.
- I simplified the `customJs` entry in the main "Advanced Usage"
example and added a reference to the FAQ for details.
4. **User State Management Refinements**:
- In "Manual User State Management", I changed the state storage
description to be more generic: "...in your preferred storage
solution anywhere."
- I simplified comments within the manual state management code
example for conciseness.
- I corrected and clarified the explanation of the content ID
variable (e.g., `H5P_STORAGE_KEY_ID`) used for uniquely
identifying player state.
- I removed an extraneous `// --- End of Required Options ---` comment.
5. **Section Renaming**:
- I renamed the "Troubleshooting" section to
"Frequently Asked Questions (FAQ)".
- I updated all internal document links to reflect this change.
These updates improve the accuracy, clarity, and neutrality of the
documentation.
This commit revises the "Manual User State Management" example in README.md to exactly match the structure and content you provided in recent feedback. Key changes: - The JavaScript example for manual state management now uses an async IIFE (Immediately Invoked Function Expression) to wrap the main logic, removing the previously added named async function and DOMContentLoaded listener to adhere to your request for a more direct script structure. - Removed commented-out `localStorage.getItem` and `localStorage.setItem` lines from within the `retrieveSavedContentState` and `saveContentState` placeholder functions. The functions now only contain the `// 👉 Your implementation...` comments and console log/warn placeholders. - Removed the "Key points from the example:" list that followed the code block, relying on the code's internal comments and brief surrounding text for explanation. This ensures the example is presented as you specified, minimizing additional abstractions or illustrative code not present in your direct feedback.
… done so far and provide feedback for Jules to continue.
|
🎉 This PR is included in version 3.8.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
fixes #173 #172 #145 #150