This document was created by Greg Price (Unlicensed) in February 2014. It was brought over from the old wiki: https://edx-wiki.atlassian.net/wiki/display/FOR/Discussion+modules |
Discussion modules have "_id.category": "discussion". The metadata field contains the following fields of interest: display_name, discussion_category, discussion_target (orfor), discussion_id (or id), sort_key.
The discussion module objects returned from the modulestore have the relevant metadata fields set as attributes (with for and id being set as discussion_target and discussion_id respectively). The object also has a unique identifier available as scope_ids.usage_id (aliased and currently used as location), and it may have some attributes that are inherited from the module's ancestors' metadata, start (containing the start date) being of particular interest. Despite the fact that certain metadata comes from the module's ancestry, the ancestry is not directly accessible. In fact, because the XBlock API does not require a block to specify contained blocks in any particular manner, it is not possible to even determine whether a particular block actually appears at any point in the course structure; the inherited metadata is applied only if the module is a descendant of a course module as indicated by the children field of various container modules.
In several places, the discussion category is treated as composed of components, which are computed from the discussion_category attribute by splitting it on '/' and trimming whitespace on the resulting strings.
Ideally, no two modules should share the same discussion_id or the same set of discussion_category components and discussion_target. No part of the system enforces such a constraint. Consequences of violating the constraints are described below.
When a thread from a discussion module is displayed in the discussion tab, a footer is added to the initial post containing a link to the courseware page containing the discussion module. The footer is computed by building a map keyed on discussion_id and then, for each thread, looking up the module corresponding to the thread's commentable_id. The link URL is built using the "jump_to" view, passing the course id and the module's location as parameters. The link text consists of the last component of discussion_category and discussion_target joined by a '/'. Note that in the process of building the map, multiple modules with the same discussion_id can conflict; whichever one is later in the list returned by the modulestore (which should be arbitrary but stable) will prevail, and the others will not be used in the link building process.
At the top of the left pane of the Discussion tab, there is a menu with which users can filter the thread list in that pane. Part of that menu is a hierarchical listing of categories from the discussion modules. The hierarchy is computed by creating a nested map with a level for each discussion_category component. Each node in the nested map contains "subcategories", pointing to the nested children in the hierarchy, and "entries" which is a map from discussion_target to module metadata (representing the leaves of the hierarchy), including start and sort_key (which is set to discussion_target if sort_key is not explicitly specified and the discussion_sort_alpha setting is true for the course). Note that the tuple of discussion_category components and discussion_target can conflict; whichever one is later in the list returned by the modulestore (which should be arbitrary but stable) will prevail, and the others will not appear in the menu. Also, if the tuple of discussion_category components and discussion_targetfor one module is a prefix of that of another module, then the menu will contain an extra entry for the former and none for the latter. Each intermediate node also has a sort key, which is the corresponding discussion_category component, and a start date, which is equal to the earliest start date of any of its leaves. The combined children ("subcategories" and "entries") are sorted by sort key and filtered by start date (without regard to staff or beta tester status of the user). When making the drop-down, the discussion_id for a given module is included in the DOM for the leaf menu items (so the front-end code can build an appropriate query when it is selected).
This is generated in the same way as the navigation menu, with slightly different DOM as a result.
Discussion modules are, of course, rendered as part of the courseware. In this context, discussion_id is used to filter the set of threads that are displayed in the module. Thus, if two modules have the same discussion_id, then the same set of threads will appear in both places. The display_nameproperty is used to generate the page title and the tooltip for the unit in the navigation bar at the top of the section.
The Studio view of a discussion module includes the ability (currently broken) to show the module's threads and write new posts. This functionality is driven by the module's discussion_id. Studio's discussion module edit dialog includes three fields labeled "Category", "Display Name", and "Subcategory", which set the module's discussion_category, display_name, and discussion_target respectively.
The names used in the UI and code for all of these "things" is quite confused at this point. Below is an attempt at clarifying some of what is there, but it may require additional review to determine if it is accurate and to get it to more completely jive with the rest of this page. This glossary is missing many terms from his page. |