| Note |
|---|
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 blockLibrary Content Component will be implemented by enhancing the existing Randomized Content Module, which is implement by the library_content XBlock. The changes to the library_content XBlock are described in this ADR:
Rendered ADR (will work after PR merges): https://github.com/openedx/edx-platform/blob/master/xmodule/docs/decisions/0003-library-content-block-schema.rst
The
...
Library Content Component
Briefly, the Libraries LibraryContent course component includes components from content libraries into courses, and then selects some or all of those components and shows them to learners.
| Table of Contents |
|---|
Inclusion (Studio)
Each Libraries Library Content 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 Library Content 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.
...
When the Source Library, its Version, or the Mode changes, the Children may need to be re-included into the Libraries Library Content component. 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.
...
Once the course is published, the Children are pushed into the LMS instance of the Libraries Library Content component, where component selection occurs (next section).
Selection (LMS)
Given a particular Libraries Library Content 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 Library Content 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 Library Content 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.
...
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 Library Content 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?
Data flow diagram
...
(This is how components flow from the library to the learner, for a particular Library Content component instance. This isn’t a user flow diagram)
User stories
Colors are just to group related cells together; they are not significant.
User stories Start here, and then read the cells left-to-right: As a course author using a |
|---|
Library Content component in their course… | Works in… | |||||
|---|---|---|---|---|---|---|
V1? | V2? | |||||
…if no Source Library is chosen… | …then | |||||
I will see a |
prompt telling them to choose a library, and clicking it will bring |
me to the block’s settings editor. | ||||||
…if I choose a Source Library… | …then I will no longer see a prompt telling me to choose a library. | |||||
…then I be able to choose the library’s Mode. | ||||||
…then Children will be included (see below). | ||||||
…if I change the Source Library… | …then the Children will be re-included (see below). | |||||
…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 Children will be re-included (see below). | ||||||
…if I import OLX into the course… | …then for each imported Library Content component… | …the component’s Children should contain the exact set of blocks specified in the OLX and should use the the block content defined by the OLX, regardless of whether:
| ||||
| ||||
…if the OLX contains a library default settings document for this Source Library… (Later feature; not applicable to the initial V2 launch!) | …then for each Child component, it should…
| |||
..if the OLX does not contain a library default settings document for the Source Library… (Test this one--it will be the case for all OLX imports in the initial V2 launch.) | …then if the Source Library exists on the instance… | …then for each Child component, it should…
| ||
…then if the Source Library is missing from the instance… | …then for each Child component, it should…
| |||
…if the Source Library exists on the destination instance, and its latest version is the same as the Version specified in the Library Content component… | …then I will neither see a warning about missing library nor a prompt to update my Source Library Version. | |||
…if the Source Library exists on the | ||||
TBD
…if I change the Source Library…
…then the Children will be re-included.
…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.
destination instance, and its latest version is older than the Version specified in the Library Content component… | ||||||
…if the Source Library exists on the destination instance, and its latest version is newer than the Version specified in the Library Content component… | …then I will not see a warning about missing library. | |||||
…then I will be prompted to update my source Source Library Version. | ||||||
…if the Source Library does not exist on the destination instance… | …then I will be warned of this via an alert within the Library Content component editor. | |||||
…then I will not be prompted to update to a later library version. | ||||||
…then I will still be able to configure the Library Content component, and edit its children, and publish. | ||||||
…then if I import the correct Source Library into the instance… | …then the messaging will change (per other user stories) based on whether the imported library’s version matches, is older, or is newer than the configured Source Library Version. | |||||
…when the Children are re-included… | …then the updated Children will be visible in the Library Content component detail page, by clicking “View”. | |||||
…then the unit editor containing the Library Content component will indicate that the block has unpublished changes. | ||||||
…then no learner’s Selection will be changed until the unit containing the Library Content component is published. | ||||||
…and if I have edited the content of any of the existing Children… | …then my content edits will be overwritten. | |||||
…and if I have overridden the settings of any of the existing Children… | …then my setting overrides will be preserved. | |||||
…and if any of the existing Children no longer exist in the current Version of the Source Library… | …then they will be removed. | |||||
…and if any of the existing Children no longer meet the criteria to be included (e.g., they no longer meet the Problem Type filter)… | …then they will be removed. | |||||
…and if this version of the Source Library contains new components… | …and if I am using Randomized Mode… | …then the new components will be included as Children. | ||||
…and if I am using using Static Mode… | …then the new blocks will not be included as Children, but they will be visible the next time the component picker is opened. | |||||
…if I am using Static mode… | …then I cannot see the Problem Type or Count fields. | |||||
…and I change the Mode to Randomized… | …then the Children will be re-included, such that the entire library (filtered by Problem Type) is included. | |||||
…if I am |
using Randomized mode… | …and I change the Problem Type… | …then the Children will be re-included, such that the entire library (filtered by Problem Type) is included. | ||||
…and I change the Count… | …then the Children will not be re-included, as it is unecessary. | |||||
…and I change the Mode to Static… | …then the the library component picker dialog will be shown, starting with the entire library included… | …and, based on the what the author picks, the the Children will be re-included. | ||||
…and I make any of the above changes (Problem Type, Count, or Mode)… | …then the unit will not indicate that it has unpublished changes. | |||||
…then the changes will not impact learners until published. | ||||||
… |
if I change the Mode or Count settings… | …then the |
set of included Children will |
not be affected. | |||||
…then the unit editor containing the |
Library Content component will indicate that the block has unpublished changes. | |||||
…then no learner’s Selection will be changed until the block is published. | |||||
…if I |
…then the set of included Children will not be affected.
publish a Library Content component in Static mode after either of the following have changed:
| ...then the unit editor |
will no longer indicate that the |
unit has unpublished changes. |
…then for each learner, next time they load the Library Content component… | …the learner’s Selection will |
equal the Children, both in content and ordering. | ||||
…if I publish a Library Content component in Static mode after either of the |
following have changed:
| ...then the unit editor will no longer indicate that the unit has unpublished changes. | |||||
…then for each |
…if the block is in Static mode…
…then the learner’s Selection will equal the Children, both in content and ordering.
…if the block is in Randomized mode…
learner, next time they load the Library Content component… | …if Count equals -1… | …then the learner’s Selection will |
equal the set of included Children, but in a random order. |
…if Count is greater than the number of included Children… | ||
… |
if Count is greater than zero and less than the number of included Children… | …then the learner’s Selection be will a subset of the included Children of size Count, in a random order. | |||
…and if |
the |
learner has an existing Selection |
…then those components will be removed from their Selection and their selection will be shuffled.
…and if the learner has an existing selection and Count is unchanged and 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
...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 max_count…
…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 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 max_count is greater than the number of items in the library…
…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:
whether children of this library_content block were added to, removed from, or edited in the destination course before import;
whether this library_content block existed at all in the destination course before import;
whether blocks were added to, removed from, or edited in the source library at any version;
whether the source library exists at all on the destination instance.
…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
containing components which still exist in the included Children… | …then those previously-selected components should remain in the Selection, unless it would make the Selection larger than Count, in which case the appropriate number of them should be randomly removed. |