courses : Managing courses

The courses plugin adds functionality for managing "courses".

A tested document

This is a tested document. The following instructions are used for initialization:

>>> from lino import startup
>>> startup('lino_book.projects.min9.settings.doctests')
>>> from lino.api.doctest import *

What is a course?

A course is when a "teacher" meets more or less regularily with a group of "pupils". The pupils can be any model (e.g. a contacts.Person). When a pupil participates in a course, we create an enrolment.

A course can automatically generate calendar entries for the meetings of that course according to recurrency rules. It helps with managing these meetings: schedule exceptions and manual date changes. It can fill the guests or participants of the meetings, and the teacher can register their presence. Courses can be grouped into course lines* (series), series into topics.

The internal name "courses" is for historic reasons. There was a time when I planned to rename "courses" to "activities". Some table names remind this time. In Lino Welfare they are called "workshops", in Lino Tera they are called "dossiers", in Lino Voga they are called "activities".

See also Activities in Lino Voga, Activities in Lino Avanti, Therapies and Lino Welfare.

The Course model

class lino_xl.lib.courses.Course

Database fields:

start_date

The start date of the first meeting to be generated.

end_date

The end date of the first meeting to be generated. Leave this field empty if the meetings last less than one day.

max_date

Don't generate meeting having their start date beyond this date.

enrolments_until
max_places

Available places. The maximum number of participants to allow in this course.

free_places

Number of free places.

requested

Number of requested places.

trying

Number of trying places.

confirmed

Number of confirmed places.

class lino_xl.lib.courses.Courses

Base table for all activities.

Filter parameters:

show_exposed

Whether to show or to hide courses in an exposed state.

That is, all courses in a state that has CourseState.is_exposed set to True.

This parameter is ignored if the state parameter is also specified.

state
class lino_xl.lib.courses.MyCourses

Show the courses authored by me (i.e. where I am the responsible manager). Compare MyCoursesGiven.

class lino_xl.lib.courses.MyCoursesGiven

Show the courses given by me (i.e. where I am the teacher). Compare MyCourses.

This requires the partner field in my user settings to point to me as a teacher.

For users whose partner field is empty, this list shows all courses without teacher.

class lino_xl.lib.courses.CoursesByLine

Show the courses per course line.

class lino_xl.lib.courses.CoursesByTopic

Shows the courses of a given topic.

The Enrolment model

class lino_xl.lib.courses.Enrolment

An enrolment is when a given pupil plans to participate in a given course.

course_area
course
pupil
request_date
start_date
end_date
state

One of lino_xl.lib.courses.EnrolmentStates.

places
option
remark
confirmation_details
pupil_info

Virtual HtmlBox field showing the name and address of the participant.

class lino_xl.lib.courses.Enrolments

Base class for all tables that show Enrolment.

class lino_xl.lib.courses.AllEnrolments

Show global list of all enrolments.

class lino_xl.lib.courses.PendingRequestedEnrolments

Show all requested enrolments.

class lino_xl.lib.courses.PendingConfirmedEnrolments

Show all confirmed enrolments.

class lino_xl.lib.courses.EnrolmentsByPupil

Show all enrolments of a given pupil.

class lino_xl.lib.courses.EnrolmentsByCourse

Show the enrolments of a this course.

Notes about automatic calendar entry generation:

  • When an automatically generated entry is to be moved to another date, e.g. because it falls into a vacation period, then you simply change its date. Lino will automatically adapt all subsequent entries.

  • Marking an automatically generated event as "Cancelled" will not create a replacement event.

Enrolment workflow

The state of an enrolment can be one of the following:

>>> rt.show('courses.EnrolmentStates')
======= =========== =========== ============= ============= ==============
 value   name        text        Button text   invoiceable   Uses a place
------- ----------- ----------- ------------- ------------- --------------
 10      requested   Requested                 No            No
 11      trying      Trying                    No            Yes
 20      confirmed   Confirmed                 Yes           Yes
 30      cancelled   Cancelled                 No            No
======= =========== =========== ============= ============= ==============
class lino_xl.lib.courses.EnrolmentStates

The list of possible states of an enrolment.

The default implementation has the following values:

requested
confirmed
cancelled

The enrolment was cancelled before it even started.

ended

The enrolment was was successfully ended.

abandoned

The enrolment was abandoned.

The Slot model

class lino_xl.lib.courses.Slot

The Line model

class lino_xl.lib.courses.Line

An activity line (or series) groups courses into a configurable list of categories.

We chose the word "line" instead of "series" because it has a plural form (not sure whether this idea was so cool).

name

The designation of this activity line as seen by the user e.g. when selecting the line.

One field for every language.

excerpt_title

The text to print as title in enrolments.

See also lino_xl.lib.excerpts.mixins.ExcerptTitle.excerpt_title.

body_template

The body template to use when printing an activity of this line. Leave empty to use the site's default (defined by body_template on the lino_xl.lib.excerpts.models.ExcerptType for Course)

course_area

Pointer to CourseAreas. This is used only when an application defines several variants of EnrolmentsByPupil.

Course areas

TODO: rename "course area" to "activity layout"?

The CourseAreas choicelist is a place for defining different layouts of courses. The area of a course determines how this course is being show on screen and whether presences of the participants are being managed or not.

The default configuration contains only one choice:

>>> rt.show(courses.CourseAreas)
======= ========= ============ =================
 value   name      text         Table
------- --------- ------------ -----------------
 C       default   Activities   courses.Courses
======= ========= ============ =================

Usage examples see Activities in Lino Voga and Therapies.

class lino_xl.lib.courses.CourseAreas

The global choicelist of course areas. Every choice is an instance of CourseArea.

class lino_xl.lib.courses.CourseArea
courses_table

Which table to use for showing courses in this course area.

The state of a course

>>> rt.show(courses.CourseStates)
======= ========== ========== ========= ========== ============= =================
 value   name       text       Exposed   Editable   Invoiceable   Update calendar
------- ---------- ---------- --------- ---------- ------------- -----------------
 10      draft      Draft      Yes       Yes        No            No
 20      active     Started    Yes       No         Yes           No
 30      inactive   Inactive   No        No         No            No
 40      closed     Closed     No        No         No            No
======= ========== ========== ========= ========== ============= =================
class lino_xl.lib.courses.CourseStates
draft
active
inactive
closed

Every course state has itself some additional attributes that are used to group them at certain places.

class lino_xl.lib.courses.CourseState
is_editable
is_exposed
is_invoiceable
auto_update_calendar

For example you can retrieve a list of course states that are to be considered "exposed" (Courses.show_exposed):

>>> courses.CourseStates.filter(is_exposed=True)
[<CourseStates.draft:10>, <CourseStates.active:20>]
>>> courses.CourseStates.filter(is_exposed=False)
[<CourseStates.inactive:30>, <CourseStates.closed:40>]

As an application developer you can redefine the items of CourseStates in order to adapt it to the needs of your application.

TODO: Write a tutorial about redefining choicelists.

Actions

class lino_xl.lib.courses.ConfirmAllEnrolments

Plugin configuration

class lino_xl.lib.courses.Plugin
teacher_model = 'contacts.Person'
pupil_model = 'contacts.Person'
pupil_name_fields = "pupil__name"

The value to use as quick_search_fields for Enrolment.

Note that this remains a text string while quick_search_fields is resolved into a tuple of data elements at site startup.

Presence sheet

The presence sheet of a course is a printable document For example Presence sheet.

presence_sheet.weasy.html

The template used for printing a presence sheet of an activity (both versions pdf and html)