Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Dynamic cohort rule API

A dynamic cohort is a cohort whose members are determined based on a query. The query is composed of a number of "rules". The rules are grouped together into rulesets, stored in mdl_cohort_rulesets. Within each ruleset are multiple rules, stored in mdl_cohort_rules. Each rule, in turn has two main components:

  1. A "rule type". Much like the Moodle admin tree, or report builder column & filter options, rule types are defined via an array in a PHP file. The file is cohort/rules/settings.php, and the array is the

    Code Block
    themeEmacs
    $rules

    array returned by

    Code Block
    themeEmacs
    '''cohort_rules_list()'''
  2. Several "rule parameters", which are unique to that rule instance and stored in cohort_rule_params.

Examples

Rule: All users whose language type is not French or Spanish

...

  • rule type: Course completion date
  • rule parameters:
    • operator = 'before'
    • date = October 31, 2011
    • courses = {Algebra I, Trigonometry, Advanced Swimming}

Rule types

The rule types (and thus the rule menu) are defined in the

...

  1. Identify the sqlhandler and ui you will need for your new rule type. 

    Note

    If no existing ones will work, then you'll need to implement new ones. See below.

  2. The sqlhandler and ui classes you use must have identical $params values.
  3. Add an entry to $rules
  4. If you've added a new group, define its name string, which will be

    Code Block
    themeEmacs
    get_string(''''rulegroup-\{$group\}'''', ''''local_cohort'''');
  5. . Define the rule type's name string, which will be

    Code Block
    themeEmacs
    get_string(''''rulename-\{$group\}-\{$name\}'''',''''local_cohort'''');

sqlhandlers

A little background, to explain what each sqlhandler does. The query that identifies the users in a dynamic cohort looks like this:

...

Code Block
themeEmacs
cohort_rule_sqlhandler

UIs

The cohort_rule_ui classes handle the UI for adding/editing/summarizing rules. They're pretty well described by the properties of the base class:

...

In general, each ui class represents a particular set of input fields in a dialog. For instance, there is one ui class for a dialog with a text field and a "equal/not equal" menu; there is one for a date field and a menu indicating "before/after", etc.

cohort_ui_form

The most important subclass of

...

    • This function should add elements to $mform, the same as you'd normally do in the definition() function of a Moodle form. You can also add client-side validation rules here (server-side validation rules will be ignored).

      Panel

      *addFormData()

    • Returns an array that indicates the starting values of all the elements in the form. If you're editing an existing rule (i.e. all the $this-> variables are populated) then here you'll take the parameters for that rule and clean them up for the form. If you're adding a new rule, put your defaults in here. (For some reason using the formslib "setDefault()" function overwrites the $formdata, so put defaults here instead.)

      Panel

      *$formclass

    • The name of the

      Code Block
      moodleform

      subclass to use. If you need to do server-side validation, you can write a new

      Code Block
      moodleform

      subclass with a

      Code Block
      validation()

      function you need, then use this variable to assign it to your UI class.

      Panel

      *__construct(...)

    • If you're writing a ui class that can be used for more than one rule type, you'll need a custom constructor with some parameters to change the text so that users can tell what they're seeing. For instance, changing the strings used in the rule summarry, changing the labels of form fields...

treeview ui's

There are also three "treeview" subclasses (and their subsubclasses), which all handle multi-select treeviews. These are all quite similar, but not quite similar enough to have a common "treeview" subclass. In general, you can make a new treeview ui class by taking the PHP code out of the "find" file for an existing treeview dialog from elsewhere in Totara, and putting it in the

...

  • Each form element that you want sent back should be given the class "cohorttreeviewsubmitfield".
  • If you want to perform client-side validation on the fields...
    • First surround them with a

      Code Block
      <div class="mform cohort-treeview-dialog-extrafields">

      and

      Code Block
      <fieldset>

      nested inside that; your validate form element goes inside the fieldset. (These tags make sure all the forms-related CSS matches up). One <fieldset> around each element or group of elements that should be highlighted in red if validation fails

    • *Don't put a

      Code Block
      <form>

      tag in there, though, because the treeview handler isn't able to properly capture form submits

    • In a

      Code Block
      <script>

      tag in the

      Code Block
      populate_selected_items_pane()

      function (actually, anywhere in

      Code Block
      printDialogContent()

      would probably work), add some Javascript that creates a new validation function and assigns it to the "

      Code Block
      cohort_validation_func

      " field of the element it should be validating. There is code in the cohortruletreeview handler which will call this function if the user clicks the "save" button on the dialog

    • You should also add this function to the

      Code Block
      onchange()

      handler for the element

    • The

      Code Block
      cohort_validation_func

      function should:

      • return true/false to indicate whether the element's current value is valid or not
      • if false, highlight the element by adding the "

        Code Block
        error

        " class to its surround fieldset. Also add an error message in a

        Code Block
        &lt;span class="error">

        tag inside the fieldset, to tell the user's what's wrong (if that error message isn't already there).

      • if true, remove the "

        Code Block
        error

        " class and the error message

    • See

      Code Block
      cohort_rule_ui_reportsto::getExtraSelectedItemsPaneWidgets()

      for an example of what this code should look like (eventually it would probably be good to have more code re-use on this, whether via a JS library function, or a PHP function that prints a bespoke JS function, or even a formslib form renderer...)

JS handlers

If you write a new JS handler type, take a look in ruledialog.js.php, at the function called

...