The gradebook API is intended to handle grade/assignment data. Other modules will create the UIs. With this in mind, I am trying to keep all purely UI considerations out of the design. The API is borrowed largely from the node module.
At the base of the gradebook is the gradebook object.
/
* Load a gradebook object from the database.
*
* @param $param
* Either the gid of the gradebook or an array of conditions to match against in the database query
*
* @return
* A fully-populated gradebook object.
*/
function gradebookapi_load_gradebook($param = array());
/
* Save a gradebook object into the database.
*
* @param $gradebook
* The gradebook object. If the gid member is not set, a new gradebook will be inserted into the DB.
*/
function gradebookapi_save_gradebook(&$gradebook);
/**
* Delete a gradebook.
*
* @param $gid
* The gid of the gradebook
*/
function gradebookapi_delete_gradebook($gid);The gradebook also needs to support multiple grading scales in the core functionality. This will allow a large amount of flexibility.
/
* Load a scale object from the database.
*
* @param $param
* Either the sid of the scale or an array of conditions to match against in the database query
*
* @return
* A fully-populated scale object.
*/
function gradebookapi_load_scale($param = array());
/
* Save a scale object into the database.
*
* @param $scale
* The scale object. If the sid member is not set, a new scale will be inserted into the DB.
*/
function gradebookapi_save_scale(&$scale);
/**
* Delete a scale.
*
* @param $sid
* The sid of the scale
*/
function gradebookapi_delete_scale($sid);While the gradebook defines a set of default parameters for assignments, it is useful to provide assignment categories that define their own default parameters. Categories also allow for simplified weights used in calculating results.
/
* Load a category object from the database.
*
* @param $param
* Either the sid of the category or an array of conditions to match against in the database query
*
* @return
* A fully-populated category object.
*/
function gradebookapi_load_category($param = array());
/
* Save a category object into the database.
*
* @param $category
* The category object. If the cid member is not set, a new category will be inserted into the DB.
*/
function gradebookapi_save_category(&$category);
/**
* Delete a category.
*
* @param $cid
* The cid of the category
*/
function gradebookapi_delete_category($cid);Grades are stored in the gradebook by assignment. Assignments specifiy parameters specific to the grades associated with that assignment.
/
* Load an assignment object from the database.
*
* @param $param
* Either the aid of the assignment or an array of conditions to match against in the database query
*
* @return
* A fully-populated assignment object.
*/
function gradebookapi_load_assignment($param = array());
/
* Save an assignment object into the database.
*
* @param $assignment
* The assignment object. If the aid member is not set, a new assignment will be inserted into the DB.
*/
function gradebookapi_save_assignment(&$assignment);
/**
* Delete a assignment.
*
* @param $aid
* The aid of the assignment
*/
function gradebookapi_delete_assignment($aid);Individual grades will retain information beyond aid, such as creation/modification dates.
/
* Load a grade object from the database.
*
* @param $param
* Either the did of the grade or an array of conditions to match against in the database query
*
* @return
* A fully-populated grade object.
*/
function gradebookapi_load_grade($param = array());
/
* Save a grade object into the database.
*
* @param $assignment
* The grade object. If the did member is not set, a new grade will be inserted into the DB.
*/
function gradebookapi_save_grade(&$grade);
/**
* Delete a grade.
*
* @param $did
* The did of the grade
*/
function gradebookapi_delete_grade($did);Grade results can be requested by gradebook, category, assignment, student, etc. The results object will contain detailed statistics for UI modules to deal with.
/**
* Load a totals object from the database.
*
* @param $param
* An array of conditions to match against in the database query
*
* @return
* A fully-populated totals object.
*/
gradebookapi_load_totals($param = array());The core gradebook API is designed to be UI free. However, some UI elements need to be exposed to provide a consistent UI expereince across 3rd party gradebook/assignment modules. ** TBD **
/**
* Implementation of hook_elements()
* Allows for creation of custom elements (scale element, etc) for the Form API
*/
function gradebookapi_elements();
Comments
Categories and data model?
Could you shed some light as to why you're creating gradebook-specific categories rather than using Drupal's built-in taxonomy system for this?
Also, do you have a data model worked up yet that would show the fields that an assignment and the gradebook itself will have? I'm curious to know because ideally quiz module would be able to save its results as an assignment.
The rationale behind the
The rationale behind the gradebook-specific categories, as opposed to using taxonomy, has to do with the way the gradebook categories will function -- they are more than organizational units into which assignments will be dropped -- they will also be used to assign different weights to assignments, so that when it comes time to calculate grades quizzes can be treated differently than homework, etc. So, given that the gradebook specific categories require more information than taxonomy currently allows, and that the gradebook specific categories do more than just organize, we chose to create a separate organizational structure. While we could build out taxonomy to do this, it isn't the cleanest solution.
This has an added advantage when looking at a site with multiple courses -- given that taxonomy will be used to organize content within courses, if we were also using it to set up the gradebook, we would need to carve out access to different terms in a fairly complex way. Separating data according to function (ie, one table for gradebook categories, and taxonomy terms for course organization) provides an easier means of isolating, organizing, and manipulating that data, particularly on a site with 10's or hundreds of courses.
We're sorting out the specifics of the data model -- we'll post that up shortly.
FunnyMonkey
Like he said...
The specifics on the data model are in-progress.
Another reason to keep the gradebook abstracted from existing Drupal data models is flexibility. I see the existing taxonomy system as being too tightly tied to the UI. Additionally, I see issues with being tied to taxonomy when there is the taxonomy.module and the category.module.
When we get to writing the UI module for the gradebook, that is where we will look into tieing the gradebook data model into existing Drupal data models.