Skip to content

Commit 79a8360

Browse files
sr258sr258
committed
docs: typedocs
1 parent ab758fd commit 79a8360

30 files changed

+523
-440
lines changed

‎docs/README.md

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -23,25 +23,25 @@ out-of-the-box solution to get a standalone H5P server.**
2323

2424
Please note that even if most functionality of H5P works fine and the library is
2525
used by several high-volume projects, there are still some things that could be
26-
added or improved. Check out the [status page of the
27-
project](./development/status.md) for details.
26+
added or improved. Check out the [status page of the project](./development/status.md)
27+
for details.
2828

2929
## Packages
3030

3131
The main Git repository is a monorepo that contains several packages, which can
3232
be installed through NPM. The packages are meant to be combined.
3333

34-
| Package name | Functionality | used in |
35-
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------- |
36-
| {@link "@lumieducation/h5p-server"} | the core package to run H5P in NodeJS | backend |
37-
| {@link "@lumieducation/h5p-express"} | routes and controllers for Express | backend |
38-
| [@lumieducation/h5p-webcomponents](../packages/h5p-webcomponents/README.md) | native web components to display the H5P player and editor in the browser | frontend |
39-
| [@lumieducation/h5p-react](../packages/h5p-react/README.md) | React components with the same functionality as the native web components | frontend |
40-
| [@lumieducation/h5p-mongos3](../packages/h5p-mongos3/README.md) | storage classes for MongoDB and S3 | backend |
41-
| [@lumieducation/h5p-redis-lock](../packages/h5p-redis-lock/README.md) | storage class for locks with Redis | backend |
42-
| {@link "@lumieducation/h5p-html-exporter"} | an optional component that can create bundled HTML files for exporting | backend |
43-
| [**@lumieducation/h5p-svg-sanitizer**](../packages/h5p-svg-sanitizer/README.md) | an optional package that protects against XSS attack in SVGs if you want to enable SVG in content files | backend |
44-
| [**@lumieducation/h5p-clamav-scanner**](../packages/h5p-clamav-scanner/README.md) | an optional package that checks file uploads for viruses | backend |
34+
| Package name | Functionality | used in |
35+
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------- |
36+
| {@link "@lumieducation/h5p-server"} | the core package to run H5P in NodeJS | backend |
37+
| {@link "@lumieducation/h5p-express"} | routes and controllers for Express | backend |
38+
| {@link "@lumieducation/h5p-webcomponents"} | native web components to display the H5P player and editor in the browser | frontend |
39+
| {@link "@lumieducation/h5p-react"} | React components with the same functionality as the native web components | frontend |
40+
| {@link "@lumieducation/h5p-mongos3"} | storage classes for MongoDB and S3 | backend |
41+
| {@link "@lumieducation/h5p-redis-lock"} | storage class for locks with Redis | backend |
42+
| {@link "@lumieducation/h5p-html-exporter"} | an optional component that can create bundled HTML files for exporting | backend |
43+
| {@link "@lumieducation/h5p-svg-sanitizer"} | an optional package that protects against XSS attack in SVGs if you want to enable SVG in content files | backend |
44+
| {@link "@lumieducation/h5p-clamav-scanner"} | an optional package that checks file uploads for viruses | backend |
4545

4646
## Examples
4747

@@ -71,8 +71,7 @@ browser.
7171

7272
Lumi tries to improve education wherever it is possible by providing a software
7373
that connects teachers with their students. Every help is appreciated and
74-
welcome. Feel free to create pull requests. Check out the [documentation pages
75-
for developers](./development/getting-started.md) to get started.
74+
welcome. Feel free to create pull requests. Check out the [documentation pages for developers](./development/getting-started.md) to get started.
7675

7776
This project has adopted the code of conduct defined by the Contributor
7877
Covenant. It can be read in full [here](../code-of-conduct.md).
@@ -90,7 +89,7 @@ see the [tags on this repository](https://github.com/Lumieducation/Lumi/tags).
9089
## License
9190

9291
This project is licensed under the GNU GENERAL PUBLIC LICENSE v3 License - see
93-
the [LICENSE](/LICENSE) file for details
92+
the [LICENSE](../LICENSE) file for details
9493

9594
## Support
9695

‎docs/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
- [Integrating the core library](usage/integrating.md)
66
- [Handling Ajax requests](usage/ajax-endpoints.md)
77
- [Constructing H5PEditor](usage/h5p-editor-constructor.md)
8+
- Examples
89
- [REST Example](examples/rest/README.md)
910
- Advanced usage
1011
- [Authorization](advanced/authorization.md)

‎docs/advanced/addons.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ editor. There are two ways to enable it:
6969
## Customizing addon behavior
7070

7171
Addons can be configured by setting the property `libraryConfig` of your
72-
configuration implementation of {@link @lumieducation/h5p-server!IH5PConfig}.
72+
configuration implementation of {@link @lumieducation/h5p-server!IH5PConfig | IH5PConfig}.
7373
The property is a complex object with H5P library machine names as keys. The
7474
object is sent to the H5P client (run in the browser) as part of the
7575
H5PIntegration object and can be accessed in a H5P library by calling

‎docs/advanced/authorization.md

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,23 @@ Many actions users perform in the H5P system need authorization. By default the
1010
library will allow everything to every user. You can customize who can do what,
1111
but passing in an implementation of {@link
1212
@lumieducation/h5p-server!IPermissionSystem} into `options.permissionSystem` of
13-
the {@link @lumieducation/h5p-server!H5PPlayer} or {@link
14-
@lumieducation/h5p-server!H5PEditor} constructor. The library then calls the
15-
methods of {@link @lumieducation/h5p-server!IPermissionSystem} whenever a user
16-
performs an action that requires authorization.
13+
the {@link @lumieducation/h5p-server!H5PPlayer | H5PPlayer} or {@link
14+
@lumieducation/h5p-server!H5PEditor | H5PEditor} constructor. The library then
15+
calls the methods of {@link @lumieducation/h5p-server!IPermissionSystem |
16+
IPermissionSystem} whenever a user performs an action that requires
17+
authorization.
1718

18-
See the documentation of {@link @lumieducation/h5p-server!IPermissionSystem} for
19-
and the
19+
See the documentation of {@link @lumieducation/h5p-server!IPermissionSystem |
20+
IPermissionSystem} for and the
2021
[`ExamplePermissionSystem`](../../packages/h5p-rest-example-server/src/ExamplePermissionSystem.ts)
2122
for reference how to implement the permission system.
2223

23-
Note that {@link @lumieducation/h5p-server!IPermissionSystem} is a generic. You
24-
can use any sub-type of {@link @lumieducation/h5p-server!IUser} as the generic
25-
type. The call of the methods of {@link
26-
@lumieducation/h5p-server!IPermissionSystem} will include a user of the generic
27-
type. This is the user object you've injected in your controllers. That means
28-
you can add any arbitrary date to it, like roles.
24+
Note that {@link @lumieducation/h5p-server!IPermissionSystem |
25+
IPermissionSystem} is a generic. You can use any sub-type of {@link
26+
@lumieducation/h5p-server!IUser} as the generic type. The call of the methods of
27+
{@link @lumieducation/h5p-server!IPermissionSystem | IPermissionSystem} will
28+
include a user of the generic type. This is the user object you've injected in
29+
your controllers. That means you can add any arbitrary date to it, like roles.
2930

3031
## Acknowledgement
3132

‎docs/advanced/completion-tracking.md

Lines changed: 49 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,79 @@
11
---
2-
title: Basic Completion tracking
2+
title: Basic completion tracking
33
group: Documents
44
category: Features
55
---
6+
67
# Basic completion tracking
78

89
The H5P client is capable of sending a message to the server when the user has
9-
completed a content object. This includes the time when this occured, how long
10+
completed a content object. This includes the time when this occurred, how long
1011
the content was open, the achieved score and the maximum score.
1112

1213
While technically this message is derived from a xAPI statement generated by the
1314
content types, it **is not the same as xAPI** and is a completely separate
1415
system that co-exists with xAPI and a potential LRS. You can enable completion
15-
tracking and xAPI tracking indepedently.
16+
tracking and xAPI tracking independently.
1617

1718
If you want to capture all xAPI statements, which allows you to have very
1819
detailed tracking, you either have to inject your own xAPI capturing JavaScript
19-
or use the xAPI capabilities of the `H5PPlayerComponent` in the [webcomponent
20-
package](../../packages/h5p-webcomponents/README.md) (or the corresponding functionality
21-
in the [React package](../../packages/h5p-react/README.md)).
20+
or use the xAPI capabilities of the {@link
21+
@lumieducation/h5p-webcomponents!H5PPlayerComponent} in {@link
22+
"@lumieducation/h5p-webcomponents"} (or the corresponding functionality in
23+
{@link "@lumieducation/h5p-react}).
2224

2325
## How it works
2426

25-
- When the user presses "check", a xAPI statement indicating completion is
26-
generated by the content type (that supports it). The H5P client captures it
27-
and calls an AJAX route on the H5P server with basic information.
28-
- The H5P server saves the completion data in a special storage system. The
29-
server automatically deletes the data when the content object is deleted.
27+
- When the user presses "check", a xAPI statement indicating completion is
28+
generated by the content type (that supports it). The H5P client captures it
29+
and calls an AJAX route on the H5P server with basic information.
30+
- The H5P server saves the completion data in a special storage system. The
31+
server automatically deletes the data when the content object is deleted.
3032

3133
## Limitations
3234

33-
- While the storage classes support retrieving and deleting the completion data,
34-
there are no endpoints on the `h5p-express` package that implement this
35-
functionality. You have to implement these endpoints yourself.
36-
- Not all content types emit xAPI statements indicating completion and thus
37-
the tracking isn't fired.
35+
- While the storage classes support retrieving and deleting the completion
36+
data, there are no endpoints on the {@link "@lumieducation/h5p-express"}
37+
package that implement this functionality. You have to implement these
38+
endpoints yourself.
39+
- Not all content types emit xAPI statements indicating completion and thus
40+
the tracking isn't fired.
3841

3942
## Enabling completion tracking
4043

41-
- Create an instance of `IContentUserDataStorage`. The recommended storage class
42-
for production is `MongoContentUserDataStorage` in the
43-
`@lumieducation/h5p-mongos3` package. There's also a
44-
`FileContentUserDataStorageClass` in the `@lumieducation/h5p-server` package
45-
that you can use for development or testing purposes.
46-
- Pass the implementation of IContentUserDataStorage into the `H5PEditor` and
47-
`H5PPlayer` constructor.
48-
- Set `setFinishedEnabled` in `IH5PConfig` to `true`.
49-
- If you use `h5pAjaxExpressRouter` from the `@lumieducation/h5p-express`
50-
package, then the routes for the AJAX endpoint are automatically created. You
51-
can manually turn them on by setting `routeFinishedData` in the options when
52-
creating the route.
53-
- If you don't use `h5pAjaxExpressRouter`, you have to route everything
54-
manually. First get `ContentUserDataManager` from `H5PEditor` or
55-
`H5PPlayer`. Route this endpoint and return HTTP status code 200 with a JSON
56-
object that is based on `AjaxSuccessResponse` with empty payload:
57-
- POST {{setFinishedUrl}}/ -> `ContentUserDataManager.setFinished`
44+
- Create an instance of {@link
45+
@lumieducation/h5p-server!IContentUserDataStorage}. The recommended storage
46+
class for production is {@link
47+
@lumieducation/h5p-mongos3!MongoContentUserDataStorage} in the {@link
48+
"@lumieducation/h5p-mongos3"} package. There's also a {@link
49+
@lumieducation/h5p-server!fsImplementations.FileContentUserDataStorageClass}
50+
in the {@link "@lumieducation/h5p-server"} package that you can use for
51+
development or testing purposes.
52+
- Pass the implementation of {@link
53+
@lumieducation/h5p-server!IContentUserDataStorage | IContentUserDataStorage}
54+
into the {@link @lumieducation/h5p-server!H5PEditor.constructor | H5PEditor
55+
constructor} constructor and {@link
56+
@lumieducation/h5p-server!H5PPlayer.constructor | H5PPlayer constructor}.
57+
- Set `setFinishedEnabled` in {@link @lumieducation/h5p-server!IH5PConfig} to
58+
`true`.
59+
- If you use {@link @lumieducation/h5p-express!h5pAjaxExpressRouter}, then the
60+
routes for the AJAX endpoint are automatically created. You can manually turn
61+
them on by setting `routeFinishedData` in the options when creating the route.
62+
- If you don't use `h5pAjaxExpressRouter`, you have to route everything
63+
manually. First get {@link @lumieducation/h5p-server!ContentUserDataManager}
64+
from {@link @lumieducation/h5p-server!H5PEditor | H5PEditor} or {@link
65+
@lumieducation/h5p-server!H5PPlayer | H5PPlayer}. Route this endpoint and
66+
return HTTP status code 200 with a JSON object that is based on {@link
67+
@lumieducation/h5p-server!AjaxSuccessResponse} with empty payload:
68+
- POST {{setFinishedUrl}}/ -> {@link
69+
@lumieducation/h5p-server!ContentUserDataManager.setFinished}
5870

5971
## Configuration options
6072

61-
- You can customize the URL to which the AJAX calls are made by setting
62-
`setFinishedUrl` in `IH5PConfig`.
63-
- You can enable or disable the feature by setting `setFinishedEnabled` in
64-
IH5PConfig.
73+
- You can customize the URL to which the AJAX calls are made by setting
74+
`setFinishedUrl` in {@link @lumieducation/h5p-server!IH5PConfig | IH5PConfig}.
75+
- You can enable or disable the feature by setting `setFinishedEnabled` in
76+
{@link @lumieducation/h5p-server!IH5PConfig | IH5PConfig}.
6577

6678
## Security considerations
6779

‎docs/advanced/context-ids.md

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ title: Multiple user states per object
33
group: Documents
44
category: Features
55
---
6+
67
# Multiple content states per object
78

89
You can save multiple user states (= the data a learner entered, e.g. the
@@ -16,7 +17,8 @@ standard H5P PHP server version.
1617
## Usage
1718

1819
If you want to use this feature, your implementation has to provide a
19-
`contextId` in the `H5PPlayer.render` options:
20+
`contextId` in the {@link @lumieducation/h5p-server!H5PPlayer.render |
21+
H5PPlayer.render} options:
2022

2123
```js
2224
const html = await h5pPlayer.render(
@@ -37,10 +39,10 @@ Multiple contexts wouldn't make sense there.
3739
## Creating contextId
3840

3941
`contextId` is an arbitrary string value that you define in your implementing
40-
system. It is **your** job to keep it unique and to pass it the the `render`
41-
method. Typically it is associated with some other object in your database
42-
anyway (e.g. an attempt object), so you will already have a unique id that you
43-
can use here.
42+
system. It is **your** job to keep it unique and to pass it the the {@link
43+
@lumieducation/h5p-server!H5PPlayer.render | render} method. Typically it is
44+
associated with some other object in your database anyway (e.g. an attempt
45+
object), so you will already have a unique id that you can use here.
4446

4547
## Using contextIds with old data
4648

@@ -52,13 +54,16 @@ system that didn't use contextIds. You can also have user data that has a
5254

5355
The H5P Player Web Component and React component also support the context id.
5456
You can set the current context id by setting the attribute/property `contextId`
55-
to the desired value. Make sure that you implementation of `loadContentCallback`
56-
accepts `contextId` as the second parameter, that you include it in the request
57-
to the server and that your server passes the contextId to `H5PPlayer.render`.
57+
to the desired value. Make sure that you implementation of {@link
58+
@lumieducation/h5p-webcomponents!H5PPlayerComponent.loadContentCallback} accepts
59+
`contextId` as the second parameter, that you include it in the request to the
60+
server and that your server passes the contextId to {@link
61+
@lumieducation/h5p-server!H5PPlayer.render | H5PPlayer.render}.
5862

5963
## Storage support
6064

61-
Both the `FileContentUserDataStorage` and `MongoContentUserDataStorage` support
65+
{@link @lumieducation/h5p-server!fsImplementations.FileContentUserDataStorage}
66+
and {@link @lumieducation/h5p-mongos3!MongoContentUserDataStorage} support
6267
context ids.
6368

6469
## Trying it out in the examples

0 commit comments

Comments
 (0)