This document is written from a post-V2-launch perspective. As of Sep 2023, not all of it is implemented.
The technical spec to implement this doc, via the library_content block: https://github.com/openedx/edx-platform/blob/master/xmodule/docs/decisions/0003-library-content-block-schema.rst
The Libraries Component
Briefly, the Libraries course component includes components from content libraries into courses, and then selects some or all of those components and shows them to learners.
Inclusion (Studio)
Each Libraries component can be pointed to a single Source Library, from which components will be included. Once a Source Library is chosen, components are included from the library, and saved as the Children of the Libraries component. The way components are included (e.g., include all, include a filtered set, author manually picks which to included) depends on the component’s Mode, described later.
The included Children are visible in Studio. They can individually be customized.
In the background, the Source Library is pinned to a particular Version. When a new version of the Source Library is published, the course author will be presented with the option of updating to it. This will erase any content customizations the course author has made to the individual Children, but will preserve any settings overrides they have made to them.
As a rule of thumb, neither the set of included Children, nor their content nor settings, should ever change without the course author’s intervention! This shields instructors from accidental loss of live library content and student state due to changes in the Source Library.
Once the course is published, the Children are pushed into the LMS instance of the Libraries component, where component selection occurs (next section).
Selection (LMS)
Given a particular Libraries component and a particular learner, the Selection defines the Children which the learner will actually see. The Selection could be equal to the Children; it could be the same components but in a different order; or it could be a subset of the Children. It may or may not vary from learner to learner. All of this behavior is determined by the Mode that the Libraries component is using.
The Selection is first built for a learner whenever the LMS needs to know it. That might be whenever the learner loads the unit containing the Libraries component, or it might be earlier on; for example, the LMS may need to know what a learner’s Selection contains in order to determine time estimates on their course outline.
Regardless, once a learner’s Selection is built, it remains stable, unless the course is published with a change such that:
the list of the included Children changes, or
the Mode or its parameters change.
If this either of those do happen, LMS will try to keep as many of the same components in the Selection as possible, and keep them in the same order. However, it may need to add or remove components in order to satisfy the selection criteria. (For example, if we are in Randomized mode, and the Count is reduced by one then LMS will keep all components in each learner’s existing selection except for one). The LMS aims for Selection stability, because any changes to it will impact course progress and grading.
Modes
The Libraries component can be configured to include and select blocks two different ways:
Randomized Mode (available with V1 content libraries): The entire source library is included into Studio, optionally filtered by a Problem Type. The author optionally specifies a Count. From the included components, LMS selects a randomized subset of size Count for each learner. If Count is not specified, all included components are shown in a random order to each learner.
Static Mode (new with the V2 content library launch): The author manually includes zero or more components from the source library. All components are shown in the original order
On the backend, the Libraries component has been built to allow for flexibility in defining new modes in the future, such as:
Statically-Included-Randomly-Selected Mode (needs a better name): The author manually includes zero or more components from the source library. The author optionally specifies a Count. From the included components, LMS selects a randomized subset of size Count for each learner. If Count is not specified, all included components are shown in a random order to each learner. (This really is just a generalization of Randomized and Static mode, combining the capabilities of both. It could be presented to the authors as an enhanced version of Random or Static mode).
Recommendation Mode (not fleshed out): Components are are smartly included from the source library based on tags or other metadata. TBD: How would components be selected for each learner?
User stories
User stories Start here, and then read the cells left-to-right: As a course author using a library_content block in their course… | Works in… | |||||
|---|---|---|---|---|---|---|
V1? | V2? | |||||
…if no source library is chosen… | …then the user will see a message telling them to choose a library, and clicking it will bring them to the block’s settings editor. | |||||
…if the source library does not exist on the system… | TBD | |||||
…if the source library exists on the system, but the specific version does not exist… | TBD | |||||
…if I change the source library… | TBD | |||||
…if I change the pool, mode, or max_count… | …then the updated pool will be visible in the library_content detail page. | |||||
…then the unit editor containing the library_content block will indicate that the block has unpublished changes. | ||||||
…then no learner’s selection will be changed until the block is published. | ||||||
…if I publish a change to the pool, mode, or max_count… | ...then the unit editor will no longer indicate that the unit has unpublished changes. | |||||
…then for each learner… | …if the block is in “include” mode… | …then the learner’s selection will equal the pool and its order will be the same. | ||||
…if the block is in “random” or “random-include” mode… | …if | …then the learner’s selection will contain the entire pool but its order will be random compared to other learners. | ||||
…if | …then the learner’s selection will contain random set of | |||||
…if | …then the learner’s selection will be empty. | |||||
...and if the learner has an existing selection and I removed a block from the pool which was in the that selection… | …then it will be removed from their selection and their selection will be shuffled. | |||||
…and if the learner has an existing selection and max_count is unchanged and max_count >= 0… | …then (TODO describe how blocks are kept if they can be) | |||||
…if the learner has an existing selection and the pool is unchanged and max_count is unchanged and max_count >= 0… | …then the learner’s selection will not change and it will not be shuffled. | |||||
…if the learner has an existing selection and the pool is unchanged and max_count is unchanged and max_count >= 0… | ||||||
…if the block is in “random-include” mode… | …then the learner’s selection only contain blocks from the pool. | |||||
…then TBD | ||||||
…then for each learner with an existing selection… | ...if I removed a block from the pool which was in the learner’s selection… | …then it will be removed from their selection. | ||||
…if their selection does not satisfy | …then it will be randomly filled with new blocks from the pool as needed. | |||||
…if their selection does not need to change… | …then it does not change. | |||||
…if their selection changes at all… | …then it is shuffled. | .. | ||||
…if I kept a block in the pool which was in their selection… | …then it should remain in their selection. | |||||
…TBD | ||||||
…if a user loads a courseware unit with my library_content block… | …and if they do not have one already, | …then a selection is established for them based on the library_content block’s configuration. | ||||
…TBD | ||||||
…if a new version of the source library is available… | …then my library_content block will give me the option of updating to the latest library version. | |||||
…if I select to update to the latest source library version…. | …then it will will silence the update prompt until the next source library version is available. | |||||
…then the content of the blocks in the pool will be updated with the content from the latest library version. | ||||||
…and if I have edited the content of any of the blocks in the pool… | …then my content edits will be overwritten. | |||||
…and if I have overridden the settings of any of the blocks in the pool… | …then my setting overrides will be preserved. | |||||
…and if any blocks in the pool have been deleted from the latest library version… | …then they will be deleted from the pool as well. | |||||
…and if any new blocks have been added to the latest version of the source library… | …and if the library_content block is in “random” mode… | …then the new blocks will be added to the pool. | ||||
…and if the library_content block is in “include” mode… | …then the new blocks will not be added to the pool but they will be visible in the block selection dialog. | |||||
…and if the library_content block is in “random-include” mode… | ||||||
…and if the block is in “random” mode… | …and if max_count is -1 | …then any new blocks in the library will be added to every learners' selection. | ||||
…and if max_count is greater than the number of items in the library… | ||||||
…and if max_count is less than the number of blocks in the library… | ||||||
…then if the block is in “random” mode and | ||||||
…if I do something that adds blocks to the pool… | …and if the block is in “random” mode… | TBD | ||||
…if I do something that removes blocks from the pool… | TBD | |||||
…if course content is imported from OLX… | …then for each imported library_content block… | …the block’s pool should contain the exact set of blocks specified in the OLX using the block content defined by the OLX, regardless of:
| ||||
…if the OLX contains a library default settings document… | …then blocks in the pool should calculate settings from the defaults from the document plus overrides from library_content in the OLX. |
| ||||
..then if the OLX has no library defaults document… | …then if the source library exists on the instance, then library_content block’s pool should calculate settings as the defaults from the source library’s blocks plus overrides from the OLX. | |||||
…then if the source library is missing from the instance, then the library_content block’s pool should calculate settings as the platform-defined XBlock defaults plus overrides from the OLX. | ||||||
…if the source library exists on the destination instance with the right version… | TBD | |||||
…if the source library exists on the destination instance but the right version doesn’t… | TBD | |||||
…if the source library does not exist on the destination instance… | TBD | |||||
TBD | ||||||