The Primary Instance of a course is a special nomination that can be given to one instance of each course at a time. It gives the instance a special URL that has the course name slug twice instead of having the course name slug followed by the instance name slug. The main use case is to be able to get a shareable link that will always point to the most recent course instance. This way links to Lovelace courses from other sites will not become obsolete whenever a new course instance is created.
Lovelace Content Model¶
Introduction¶
In order to get the most ouf of Lovelace and avoid unnecessary work it's good to understand a little about how content is organized into courses, courses instance, pages, and tasks. This article gives you the basics of how Lovelace handles its content.
Let's start by answering the most important question first. "Why is it so complicated?". The system has been designed with both parallel and historical instances in mind, and also to support sharing content between courses. Imagine you are running two versions of your course at the same time, one in the classrooms normally, and another online. Over 90% of the actual content is the same, but the two instances might have different instructions, grading rules etc. Of course you may also want to keep the students separate. However whenever you update that 90% of content that is shared between the two, you most definitely do not want to do the same edits for both instances separately.
We achieve this by separating context from content. Much like pointers in programming, a course instance in Lovelace only contains references to the actual content. You can choose which content to show in each of your course instances by arranging these pointers which we call
context nodes
into a table of contents to your liking. If you edit the content, the changes will be reflected in every course instance that has a reference to that content.Context nodes are separated into two types of nodes:
- Index nodes represent pages that are shown in the course index
- Embed nodes represent task pages, media, and terms that are embedded into top level pages
So yes, it is indeed a little bit more complicated than what you might be used to. Just keep the purpose in mind when reading through the rest of this document, and everything should make sense.
Course and Instance¶
The basic academic unit in Lovelace is a course instance. As the name suggests, it is an instance of a course. Majority of setting up teaching in Lovelace happens through a course instance. A course is the parent object that ties together instances of the same course. A course itself mostly contains only basic information such as course name, its code, and how many credits it's worth. Main responsible teacher and staff members are also configured on course level. Everything else is handled on the instance level.
A course instance usually is associated with one occurrence of teaching a course. I.e. if a course is given every Autumn, then you would have one course instance in Lovelace for every Autumn semester. A course instance has a lot of configurable parameters that can change every time the course is given. This includes but is not limited to course starting / ending dates, email list, group work setting, welcome message to new students etc. A course instance also defines what content is shown on the course pages in Lovelace. All student activity is also tied to a course instance.
Courses can currently only be created by site admins, and the first instance of a a course must also created by an admin. Contact your site admin when you need a new course to be created.
Making New Instances¶
Typically new instances of a course are created by cloning the most recent one. When an instance is cloned, you can start from the state you had previously, and you can change instance settings without affecting the original instance. It is also of course a blank slate as students, or any of their activity are left to the old instance. Making a clone will also copy all of the context nodes that make up the course content. This means the new instance will display the exact same content as the previous one, but it can change the context information related to that content (e.g. deadlines).
When using
staff mode
you can access the cloning tool from the course instance's index page. When creating the clone, you must provide a new unique name for it in all supported languages. You can also optionally provide start and end dates in ISO date format. This will determine the period during which the course instance is active. Students can only see and enroll to active course instances.Usually if you create a new instance for a new semester, you also want to do two other things: archive the previous one, and mark the new one as primary. Archiving preserves the old instance in its historical state, fully functional (with some limitations). Archiving can be done from the same management panel as cloning, in the course instance index page with the freeze form. This form only has one field: target date (ISO format). All
context nodes
in the course instance will be updated to point to the version of content that was most recent on the specified date.Normally course instances are addressed by URLs patterned as
/course-name-slug/instance-name-slug/
. Setting an instance as primary gives it a second URL where the course slug is used in place of the instance slug: /course-name-slug/course-name-slug/
. This way the primary - i.e. currently active - instance of the course can be linked from external web pages without having to change the link every semester. Setting an instance primary is done from the course instance settings form. The settings form is explained in a separate guide.Language and Translation¶
Lovelace uses Django Modeltranslation to provide content in multiple languages without the need to create separate copies for each language. This helps with managing mutlilingual content, and falling back to a default language when a translation is missing. For every field that contains displayable content, there is a version for each supported language that can be filled and then displayed based on the user's selected site language. If the field for the selected language is empty, Lovelace will automatically fall back to contents of the default language field instead. URLs are currently only based on the default language, and will not change when the site language is changed.
Please bear in mind that fallback only works towards the default language! If the default language field is empty but a translated field has content, users viewing the site with default language will see an empty page. If your intent is to only provide course material in one language, always fill your content into the default language fields even if it is not the same language as the content you are authoring. For instance, if the system default language is Finnish, and you want to create an English course material, you would need to use the Finnish content fields.
Caching¶
Due to the nature of the content, Lovelace uses caching quite aggressively. Majority of the content is static. The only dynamic content that needs to be generated every time a page is refreshed is the viewer's progression stats. Lovelace caches content indefinitely, and only regenerates the cache when some part of the content is changed. As course content typically goes unchanged for long periods of time, majority of the time Lovelace can serve all of the pregenerated HTML from cache at very fast speed. This also allows broken archived course instances to display their content as long as it remains cached (see next section).
The system is quite good at recognizing when a cache refresh is needed, but there are a few cases where this is impossible with the current database structure. For these situations, teachers can manually trigger a cache refresh for a content page or the entire course instance. One example is displaying system-enforced deadlines in pages. The system does not keep track which pages are showing the deadline. If a deadline is changed, cache refresh is not automatically triggered for pages that display the deadline. In this situation, if you remember which pages are showing the deadline, it is advised to trigger a cache refresh for those pages only. Refreshing the cache of the entire course instance can be a very expensive operation, and should be used sparingly.
Version Control and Archiving¶
Lovelace uses Django Reversion to manage revisions of all content. Whenever you save content, a new revision is created. These revisions are stored in a separate part of the database, and serve two functions.
- They can be restored to replace current content in case of making a mistake in editing, or accidental deletion of content.
- They can be retrieved to show old versions of content, and also to answer to old versions of tasks.
The latter is the main use of version control. It allows retaining past course instances in historically accurate state, fully active. Besides maintaining history for posteriority, it also has a use in a specific edge case where a student is given permission to complete studies that were started to an older course instance. Using an archived version of the old instance, the student can complete the course with their existing progresss and the requirements that were in effect when they started it.
That said, version control is not perfect. If the database changes in an update, it can become impossible to restore revisions that have become incompatible after the change. For instance, if a new mandatory field is added, old revision will not have a value for it. Similarly if the type of a field changes, old versions no longer have a valid value. In these cases the old content can still be viewed as long as it is preserved in cache, but it can no longer be interacted with.
Access Model¶
Most content in Lovelace is not directly tied to any course. Instead, access is determined by ownership and links.
Viewing Access¶
All content is viewed through a course instance. Content that is not linked to any course instance cannot be viewed unless it is a static media file (e.g. image) with a static URL. Within course instance, content viewing can further be controlled by hiding it from non-staff users, or by limiting it to enrolled users.
Editing Access¶
Editing access in Lovelace is based initially on ownership. You can only edit content that have your user account in its edit history. In other words, until content is included in a course, only the original creator can access it. When content is added to a course by its original creator, it then becomes editable by staff members of that course. In other words your content access list will always be a union of
- content that you have created and/or edited in the past
- content that is linked via index or embedded nodes to a course where you are part of the staff
Access Levels¶
Lovelace currently has three levels of staff users. Listed from lowest to highest authority.
- Staff member: A teaching assistant in a course, can edit course materials and view individual students' answers when provided with a link, but cannot access enrollment or course completion information. Also cannot perform high level course instance management (e.g. cloning and archiving)
- Responsible teacher: Each course was nominated responsible teacher. They have access to all management tools within instances of their course. They cannot create new courses, or view system-wide user records.
- Superuser: Lovelace admin who can access everything. The only role that can create new courses and manage users on the system level. Also the only role that can elevate users to staff status.