Web-adjustable admin settings

From Dokeos

Jump to: navigation, search

This is a software design for a new feature, that is partially implemented. The first version is usable in Dokeos 1.6, and allows to store general settings that the platform admin can change.

The advanced part of this page is now deprecated and is superseded by an improved design which is more readable, see User roles and rights.

Contents

What is this about

Admin settings are settings that only the platform admin can choose. These have an effect on the entire platform, as opposed to e.g. only on one course or user. In the past admins had to delve into code files to change settings, now we have made this possible through a web interface.

There is a simple proposal for web adjustable admin settings, and also a more complicated proposal that also allows us to deal with course and user preferences in a very clean way. This means the second proposal extends the original idea to store all settings of dokeos, not just platform admin settings.

First implementation

This section describes the implementation that is currently in Dokeos 1.6, which gives platform admins the ability to adjust platformwide settings through a web interface.

This proposal is a simple design that can be implemented rather easy. To access the preferences without too much overhead every time a tool asks a setting, we can use the script claro_init_global. There we should call an api function (api_load_admin_settings()) that reads all the admin settings and stores it into a session array. When you need a certain setting you should then call an api that reads that certain setting (api_read_specific_admin_setting("site_name")) and use the return value of this api function.

Note: this still means we load all preferences every time the user goes to another page. We can also cache the settings e.g. in the global or session arrays. (unless you do a check if the array containing the settings already exists of course => the loading occurs only once)

Database structure

We propose two tables for this feature:

  • one table settings_current to hold the current settings, if any, of properties.
  • one table settings_options to hold all possible choices for all possible settings

Note: one / both of these tables should also store how the setting should be displayed (checkbox, radio button, dropdown list, text field, ...)

First table structure proposal (by Toon Van Hoecke) 

CREATE TABLE `settings_options` (
 `id` varchar(4) NOT NULL default ,
 `name` varchar(100) NOT NULL default ,
 `key1` varchar(50) NOT NULL default '0',
 `key2` varchar(50) NOT NULL default '0',
 `value` varchar(100) NOT NULL default ,
 `description` varchar(255) NOT NULL default ,
 `default_at_setup` set('TRUE','FALSE') NOT NULL default ,
 `equal_to_id` varchar(4) NOT NULL default ,
 PRIMARY KEY  (`id`)
) TYPE=MyISAM;

CREATE TABLE `settings_current` (
 `name` varchar(100) NOT NULL default ,
 `key1` varchar(50) NOT NULL default '0',
 `key2` varchar(50) NOT NULL default '0',
 `id` varchar(4) NOT NULL default ,
 `equal_to_id` varchar(4) NOT NULL default ,
 `category` varchar(10) NOT NULL default 'General',
 `representation` set('text','checkbox','radio','dropdown') NOT NULL
default 'text',
 PRIMARY KEY  (`name`,`key1`,`key2`)
) TYPE=MyISAM;

Code design

Admin user interface

In the admin section comes a new page to edit settings. When calling this page you only get to see the different categories of settings. After selecting one category you see all the different settings in this category. This is essentially a very large html form. An algorithm generates automatically form elements for each setting available in the platform. Another algorithm takes the POST data, and stores the choices made into the current settings table

List of settings

A new Dokeos installation needs to create tables with the settings in, so these settings should come from another place than a database. We should not combine the list of settings with php code, like the course creation scripts do. It's better to have a plaintext / xml / ... file that holds the settings, and use this list only when installing (and later perhaps importing / exporting settings). Upon install the list is read and inserted into the two tables.

The tool

The implementation has been part of Dokeos since Dokeos 1.6, and all future versions still use it.


The rest of this document is unused, other designs have improved on it and are mentioned on other pages.

Advanced design - What do we want

Functionality of the advanced design

  • A "user role - rights matrix" with on one axis the different user roles, and on the other axis the different actions users can undertake.
  • Good default roles: guest, student, tutor, course admin, platform admin
  • The ability to define new roles - these also show up in the user rights matrix

Or, to put it differently: 

If you simply define an extensive set of rights, you can create a matrix of rights and roles
on the admin level that is extremely flexible. On the one hand you have the rights, on the
other hand you can define your own 'labels' for the roles you want/need in your organization.
Course roles can be defined in a similar way on the admin level with the same kind of
flexibility that makes tailor-made solutions simple to apply for any organization.


Questions

  • Do we need a distinction between "course roles" and "platform roles"?
  • Is it necessary that users can belong to different roles at once?
  • Is it necessary that indivivual users' rights can be adjusted as well?
  • If there are separate course roles, should the course admin be able to define new ones?

Proposal

We will make a distinction between platform roles and course roles.

To keep things simple, we do not allow adjusting rights for individual users directly, but this can be done by creating a role and assigning it to a specific users. E.g. a role of "student with forum moderation rights".

Design guidelines

  1. Ease of use: the Dokeos platform admins must have the ability to change settings easily, without any programming knowledge, without changing config files themselves. We will give them a web interface, extending the admin tools with a settings tool that lets them check/uncheck checkboxes, choose options from pull-down lists, etc.
  2. Extensibility: no new table for every feature. No huge awkward list of settings code that programmers have to alter every time they add a setting. Adding new settings should be as easy as possible.
  3. A good default mechanism for all settings, like the Java Preferences API. This ensures that every setting has at least a default that makes sense.
  4. avoid upgrade hell: what happens if a users who has 100 settings already, upgrades to a dokeos that assumes 150 settings. We will try to update tables as perfect as possible, but the system should not do unreasonable things because of a forgotten setting. See also #3 (default mechanism).
  5. flexibility: it should be easy to add or rename settings (where do we store them, would a developer admin web page help for this)
  6. simplicity: for tool code programmers: one function call to get a property is enough. Also, one function call to set a property is also enough.
  7. We have to take into account there are already a lot of settings (dozens), and there will be many more. As suggested below it would be a good idea to have the ability to group related settings together.
    • Platform settings (name of the platform, name of the platform administrator, allow self registration, ...)
    • User Interface (default dokeos stylesheet, allow students to switch stylesheets, ...)
    • Tool X (each individual tool can have a separate category)
    • ...

Proposal for an extended implementation

This is a more advanced and more complex settings implementation. It goes further than allowing the platform administrator to take care of the settings of the platform (the admin settings). It also takes care of the course settings (for instance open/closed course, course language, can students add links themselves or create new forums...) and the user settings (for instance the stylesheet the user is using). Although it is much more complex than the first implementation we should consider this option. It gives us a lot of flexibility and brings unites a lot of Dokeos features code into one consistent whole.

It is important to see the difference between a user role and a specific user. For example, we want to be able set the default stylesheet for the student role, and also specify wether or not the individual student can edit that setting - thus selecting a personal stylesheet.

The design below this was based on an older design by Jan Bols. Changing it to include our new ideas turned out to be difficult and made the text quite incoherent and difficult to read. We're starting again in a new page: User roles and rights.

User Roles

If we built a good system to let platform admins easily adjust settings through a web interface, we might as well extend the mechanism to all users.

Example: do I want to be informed of replies to messages I posted in the forum, new topics in the forum...

In short, next to the platform admin settings there are also course admin settings and normal user settings.

Generalisation: we can have these predefined roles of platform admin, course admin, tutor, and student. But we can also let platform admins define additional roles, and let them set the rights for each of these roles. This will require a slightly different database design.

Who can edit which settings

The platform admin should be able to specify which settings can be edited by the course admin and normal user. The course admin in turn should (optionally?) be able to specify the settings that the user (in his course I suppose) can edit.

The settings tables should not only store what the status is of a certain setting for a certain user, but also who can edit this. In database terms this is called with admin option.

Example: some teachers want to allow the students in their courses to create new forums or add links themselves.

Scope

Next to a division in roles (platform admin, course admin, student), it's also necessary to fix the scope of a setting: certain settings are valid for the whole platform, others only for a course, still others only for a tool.

Database design

Categories

To be able to maintain an overview while presenting the various settings, we should split them up according to category (platform, course, dropbox, forum, agenda...) (see also What do we want - design guidelines, point 7 ) Organising settings into certain categories is easy and implicates only adding a new field in the table listing all possible settings. 

CREATE TABLE `setting`
(
   `id`: primary key ,
   `name`: the name of the setting, e.g. notification_by_email 
   `category`: category of the setting e.g. LDAP or forum,
   `description`: describes the setting, e.g. inform user of new forum messages
   `default`: default value when nothing is specified
   `representation`: set('text','checkbox','radio','dropdown')
   `admin_type` set('admin', 'courseadmin','courseuser') NOT NULL DEFAULT
   'admin': see explanation in 'with admin option" section
   PRIMARY KEY  (`id`)
)

CREATE TABLE `setting_option`
(
   `setting_id`: reference to primary key of setting table
   `value`: possible vaklue of this setting
   PRIMARY KEY  (`setting_id`,`value`)
)

These two tables should be in the main Dokeos database. The first table setting contains a list of all defined settings, subdivided by category, with a non-changing default value and a representation the way Toon proposed. The second table setting_option contains for all settings the different possible values.

These tables do not contain the current value of a setting, that's stored in another table.

NOTE: can't we give these tables more descriptive names? setting_info and setting_possible_values ? Roan

User roles

This is less easy. For every setting we have to take into account that it can theoretically be specified by the platform admin, AND the course admin of one course, AND a student of one course.

We start with a table that indicates which value a setting has, specified by the platform admin. 

CREATE TABLE `setting_admin`
(
   `setting_id`: ref. naar pk van setting table,
   `value`: waarde van deze setting,
   `admin` set('courseadmin','courseuser') DEFAULT NULL: zie uitleg in punt 3
   PRIMARY KEY  (`setting_id`)
   FOREIGN KEY  (`setting_id`,`value`) REFERENCES setting_option (setting_id, value)
)

This table is stored in the main Dokeos database and indicates which settings have been specified by the platform admin.

If we want to allow that course admins and students can edit settings as well we need two tables for every course: 

CREATE TABLE `setting_courseadmin`
(
   `setting_id`: ref. naar pk van setting table,
   `value`: waarde van deze setting,
   `admin` set('courseuser') DEFAULT NULL: zie uitleg in punt 3
   PRIMARY KEY  (`setting_id`)
   FOREIGN KEY  (`setting_id`,`value`) REFERENCES setting_option (setting_id, value)
)

CREATE TABLE `setting_courseuser` 
(
   `user_id`: referentie naar een user id van deze cursus
   `setting_id`: ref. naar pk van setting table,
   `value`: waarde van deze setting,
   PRIMARY KEY  (`user_id`, `setting_id`)
   FOREIGN KEY  (`setting_id`,`value`) REFERENCES setting_option (setting_id, value)
)

These 2 tables are stored in each course database. The first table setting_courseadmin shows what settings the course administrator has specified. The second table setting_courseuser shows what settings each user has specified.

Generalisation: if we want the ability to dynamically define more roles and the rights of these roles, we can use one table instead of these three, with an extra "role" field. The primary key then becomes PRIMARY KEY (`role`, setting_id`) instead of PRIMARY KEY (`setting_id`). This way rights can be passed on to roles lower in the hierarchy. For passing rights to specific users (e.g. students in a course), we need some more changes.

With admin option

There is a number of settings for which the platform admins allow the course admins to change them. Many settings a course admin has specified may not be changed by a student in the course.

For these reasons there is an extra field admin in the setting_admin table, with the following possible values:

  • null or platform_admin_only: course admin and student are not allowed to edit the value
  • course_admin: only the course admin can edit the value
  • course_user: both course admin and student can edit the value

There is also an extra field admin in the setting_courseadmin table, with the following possible values:

  • null or course_admin_only: student cannot edit value
  • course_user: student can edit value

Certain settings aren't meant to be changed by course administrators or users. So there has to be a way to specify how far a setting can percolate down the sysAdmin/courseAdmin/user hierarchy. For this there's an extra field in the table setting called adminType. This field can have the following values:

  • admin: the platform admin can never pass the editing of this setting to course admins or students. This is a setting that can only be changed by a platform admin.
  • courseadmin: the platform admin or course admin can never pass the editing of this setting to students. This is a setting that can only be changed by a platform admin or by a course admin if he has received this right by the platform admin.
  • courseuser: admin can pass editing rights of this setting to the student or course admin

Presentation layer

How these settings will be shown to the user is not discussed here. It can be through the profile, the admin page, the course settings page, ...

API

Possible api-functions that return and set a setting could look like this:

  • api_get_setting(user, course, setting_name)

This would return the value of setting setting_name for a certain user user in a certain course course. What follows is an algorithm that shows how to get this setting from the tables in the database:

1. Does the setting exist in the setting table?

no: return null or error
yes: 2. Is the setting specified in the setting_admin table?
no: use the (default) value of the setting in the setting table
yes: 3. Which value does the admin field have in the setting_admin table?
null: use the value of the setting in the setting_admin table
course_admin: 4. is the setting specified in the setting_courseadmin table?
no: use the value of the setting in the setting_admin table
yes: use the value of the setting in the setting_courseadmin table
course_user: 5. is the setting specified in the setting_courseadmin table?
no: 6. is the setting specified in the setting_courseuser table?
no: use the value of the setting in the setting_admin table
yes: use the value of the setting in the setting_courseuser table
yes: 7. what's the value of the "admin" filed in the setting_courseuser table?
null: use the value of the setting in the setting_courseadmin table
course_user: 8. is the setting specified in the setting_courseuser table?
no: use the value of the setting in the setting_courseadmin table
yes: use the value of the setting in the setting_courseuser table
  • api_set_setting(role, course, setting_name, value, admin)

Sets the setting setting_name to the value value. The parameter Role can have the following values:

  • admin - sets the setting in the setting_admin table with the specified admin value. When the value of this setting is null, it deletes the record from the setting_admin table.
  • courseadmin - sets the setting in the "setting_courseadmin" table with the specified admin value. When the value of this setting is null, it deletes the record from the setting_courseadmin table.
  • user - sets the setting in the setting_courseuser table. When the value of this setting is null, it deletes the record from the setting_courseuser table.

In all cases first we check wether the users is allowed to edit this setting.

Ending remarks

This design is still incomplete (ah, headaches...). What is still lacking is a possibility for users to define settings about the platform dokeos, not just for a specific course. Or the possibility for students of a cours to define they ant to have a certain setting for all courses that allow it (e.g. in all courses where this is allowed, I want to receive email notifications).

Perhaps there's a better or simpler scheme possible, suggestions are welcome.

Actual settings to store

For the first implementation (in Dokeos 1.6), we've gradually added and categorised many settings, also creating several new settings for things that were not adjustable before. This process is not over: there still are some settings inside the tool code files themselves, others are separated from the rest of the code already and gathered in the inc/conf/ folder . We will continue this process of improvement.

A list of all the possible settings: list of Web-adjustable admin settings (work in progress)

For the more advanced implementation, which has not started yet, we will work the same way: gradually add new settings that seem logical to the developers, are asked by users, or appear necessary when testing.

For Dokeos 1.6

There is overlap with another page: list of Web-adjustable admin settings. Perhaps move this content to that page, plus eliminate the html code on that page (html code on a wiki makes editing difficult).

The Web-adjustable admin settings for Dokeos 1.6 will follow more or less the first proposal. These are the settings that are currently configurable by the script (more will be added in the following days)

Platform category

  • Institution Title
    The name of the institution (appears in the header on the right)
  • Institution URL
    The URL of the institutions (the link that appears in the header on the right)
  • Dokeos Campus Title
    The Name of your Dokeos Campus (appears in the header on the left)
  • Platform Administrator: E-mail
    The e-mail address of the Platform Administrator (appears in the footer on the left)
  • Platform Administrator: Family Name
    The Family Name of the Platform Administrator (appears in the footer on the left)
  • Platform Administrator: First Name
    The First Name of the Platform Administrator (appears in the footer on the left)
  • Platform Administrator Information in footer
    Show the Information of the Platform Administrator in the footer?
  • Lost Password
    Is a student / teacher allowed to retrieve his/her password. If you use an external authentication method this should probably set to false
  • Allow Registration
    Can anyone create an account for the campus (= closed or open campus)
  • Allow Registration as teacher
    Can anyone create an acoount for the campus as a teacher? Can anyone create courses on your campus?
  • Server Type
    What sort of server are you running. This enables or disables some specific options. On a development server there is a translation feature functional that inidcates untranslated strings
  • Who's Online
    Display the number of persons that are online (appears in the header on the right)

Course Category

  • Homepage View
    How does the homepage of a course have to look like:
    1. Two column layout. Inactive tools are hidden
    2. Three column layout. Inactive tools are greyed out (Icons stay on their place)
  • Tool Shortcuts
    Show the tool shortcuts (the tiny icons) in the banner?
  • Student View
    Enable Student View?
  • Default Document Quotum
    What is the default quotum for the documents tool? You can override the quota for specific courses through: platform administration > Courses > modify
  • Group Categories
    Allow course admins to create categories in the group module?

User

  • profile
    Which parts of the profile can be changed by the user?
    1. name
    2. official code
    3. e-mail address
    4. picture
    5. login
    6. password
  • Registration: required fields
    which fields are also required (besides name, username and password)
    1. official code
    2. e-mail address

Tools

  • default active tools in a newly created course (checkboxes)
    Which tools are visible when you create a new course

TO DO

  • errorlevel (dunno if this will possible however)
  • is_tracking enabled (if changed from false to true => the tables have to be created: enable / disable)
  • checkEmail by hash sent
  • htaccess in document (is this config still needed???): yes / no
  • profile: language change (code for user driven language change through profile has to be added WIP)
  • display language selection: yes / no
  • users can have personal agenda: yes / no
  • default course visibility
  • default course registration
  • course registration: what fields are required
  • Allow course manager to delete
  • send e-mail upon registration of user
  • allow course manager to add users to course
  • Agenda: default sorting order
  • number of items to display per page (sortable columns)
  • show the e-mail address of the users (privacy)
  • allow_user_headings : Can a course-admin define user headings? This is now a hardcoded setting ($show_define_headings_option = false; in user.php)

see also the forum thread: http://www.dokeos.com/forum/viewtopic.php?p=12181

Retrieved from "http://www.dokeos.com/wiki/index.php/Web-adjustable_admin_settings"
Personal tools