--- doc/gutshtml/SessionTw1.html 2002/06/28 20:30:29 1.1 +++ doc/gutshtml/SessionTw1.html 2003/07/22 14:47:00 1.2 @@ -1 +1,353 @@ - Session Two: Spreadsheet and Messaging (Matthew)

Session Two: Spreadsheet and Messaging (Matthew)

Spreadsheets

The spreadsheet presents data on student performance on homework problems. Spreadsheets are handled by loncom/interface/lonspreadsheet.pm and are completely web based. A person who has selected a student role will access the spreadsheets using the [GRDS] button. A course coordinator is given access via the [SPRS] button. Students are not able to see data on anyone's performance but their own. Students are also not allowed to save spreadsheets.

Spreadsheet Structure and Hierarchy

The spreadsheets are laid out in the typical fashion, with some limitations. There can only be 52 columns, addressed [A-Za-z]. There may be any number of rows, but currently there do not exist facilities to add rows other than those automatically generated.

There are three levels of spreadsheets, as illustrated in Fig. 2.2.1.

Fig. 2.1.1 Ð Spreadsheet Hierarchy

The rightmost spreadsheets are the assessment spreadsheets. The middle spreadsheets are the student spreadsheets. The left spreadsheet is the course spreadsheet.

Export Rows

The hierarchy of spreadsheets described above allows data from the lower level spreadsheets (assessment and student) to be exported up to the higher level spreadsheets (student and course, respectively). Row 0 is the export row. Only the cells A0-Z0 are exported. Cells a0-z0 are not exported and can be used as 'scratch' space for the results exported in A0-Z0.

The export rows in the image are shown shaded in figure 2.2.1. Where the exported rows appear in the student and course spreadsheets is indicated by arrows.

Assessment Spreadsheet

The assessment spreadsheet gives data on the students performance on a specific resource in LON-CAPA (typically a *.problem resource). Parameters such as the due date, the number of tries possible, the number of attempts made, the correctness of the student solution, and any <parameter> tags inserted in the resource will be shown. Fig. 2.2.2 shows an example of an assessment spreadsheet.

Fig. 2.2.2 Ð Example Spreadsheet on Assessment Level

Student Spreadsheet

Each assessment spreadsheet exports a row into the student spreadsheet. Fig 2.2.3 shows an example student spreadsheet. The student spreadsheet exports a row to the course spreadsheet.

Fig. 2.2.3 shows the next level up spreadsheet with the exported data from this sheet.

Fig. 2.2.3 Ð Default Spreadsheet on Student Level

Course Spreadsheet

The course spreadsheet gives a summary of each students performance in the course as a whole. Fig 2.2.4 shows the default course spreadsheet.

Fig. 2.2.4 Ð Default Spreadsheet on Course Level

Spreadsheet definition

The default spreadsheets are defined via xml. Fig. 2.2.5 shows a sample definition of a spreadsheet. However, it is possible to work with spreadsheets and never edit the xml for the spreadsheet itself. By modifying the contents of cells via the web interface and saving the results, instructors can create as complicated a spreadsheet as they like. It is now possible for users to upload spreadsheets to the library server, publish them, and set them as the default sheets for their course.

[www@zaphod www]$ cat /home/httpd/html/res/adm/includes/default.assesscalc

<field col=A row=0>[stores_0_solved]</field>

<field col=B row=0>'Tries:'</field>

<field col=C row=0>[stores_0_tries]</field>

<field col=D row=0>'Timestamp:'</field>

<field col=E row=0>[timestamp]</field>

<field col=F row=0>'Duedate:'</field>

<field col=G row=0>[parameter_0_duedate]</field>

<field col=W row=0>'Available Points:'</field>

<field col=X row=0>[parameter_0_weight]</field>

<field col=Y row=0>'Awarded Points:'</field>

<field col=Z row=0>[parameter_0_weight]*[stores_0_awarded]</field>

Fig. 2.2.5 Ð Default Spreadsheet on Assessment Level

Template Row

The template row of a spreadsheets will make the contents of a given column identical for each row. The contents of the template row are shown verbatim, and not evaluated. Fig 2.2.6 shows the template row in use.

Fig. 2.2.7 Ð Customized Spreadsheet on Student Level Shows a course-customized student-level spreadsheet with many of these functions, templates and wildcards in action. In the dialog window, &SUM(Òd*Ó) is entered as the expression for cell H0, which will add up all cells in column d. The template row is used to define expressions for columns a, b, c, and d, where for b and d both the Ô#Õ wildcard and access to the EXT function is used in order to multiply the respective X and Z cells in each row with 1 or 0 depending on whether the value in G (the duedate) is smaller or larger than the system time (Ò?Ó is the standard Perl choice operator).

What goes in a cell

A cell contains either parameter data (which cannot be changed) or perl code. Additionally, cells can contain references to other cells and these references can be passed as parameters to perl functions. Parameters can be accessed via the cell they are stored in or by the parameter name.

Parameter Access

Parameters can be accessed by enclosing the parameter name in square brackets. A new feature allows the accessing of parameters by enclosing only enough information to lead to a unique parameter. "[part_0_duedate]" will give the same value as "[duedate]" if there are no other parameters which contain the string "duedate".

Addressing other cells

Cells are specified by the letter-number combination of their position in the table, for example "A5". There are also wildcards '*' and '#' which are used in ranges and templates, respectively, and symbolic names.

Valid ranges are for example "A5..C7" which is the square between cells A5 to C7, as in A5, A6, A7, B5, etc. Also, wildcards can be used, as in "A*" for column A, or "*5" for row 5. For example, &SUM("d*") will add up all cells in column d. The table below gives a brief summary of the range options.

*          all rows, all columns

B*       all rows in column B

*5        all columns in row 5

C5..F25           all cells in the rectangle between C5 and F25

The template row allows the use of "A#", which will result in "A5" in row 5, "A6" in row 6, etc.

Spreadsheet Functions

Many perl functions are available in the spreadsheet (see "The Safe Environment" below). Additionally, some spreadsheet specific functions have been defined as well. A complete list is available by executing 'perldoc loncapa/loncom/interface/lonspreadsheet.pm' on the command line. An abbreviated table appears in Fig. 2.2.7.

&NUM(range) Ð number of non-empty cells in range

&BIN(low, high, range) Ð number of non-empty cells in range with values between low and high

&SUM(range) Ð sum of the non-empty cells in range

&MEAN(range) Ð mean value of non-empty cells in range

&STDDEV(range) Ð standard deviation of non-empty cells in range

&PROD(range) Ð product of non-empty cells in range

&MAX(range) Ð maximum value of non-empty cell in range

&MIN(range) Ð minimum value of non-empty cells in range

&SUMMAX(n ,range) Ð sum of the maximum n non-empty cells in range

&SUMMIN(n, range) Ð sum of the minimum n non-empty cells in range

&EXT(expression) Ð access to EXT function in lonnet

Fig. 2.2.7 Ð Available Functions in Spreadsheet

The Safe Environment

The spreadsheet cells are evaluated in a "Safe" environment. The module Safe.pm is included in the standard systemperl RPM put out by the LON-CAPA developers, but is written by Tim Bunce and Malcolm Beattie. If you execute 'perldoc Safe' you can read the documentation for the module.

The Safe.pm module allows users to "compile and execute code in restricted compartments". We use this to allow users to implement in their spreadsheets a restricted set of perl functions, variables, and operators. No one using the spreadsheet should ever need access to the basic IO functions of Perl, for example, so these are not made available to the users.

Each cell is evaluated within the same safe space, so cells can actually contain function and declarations.

There is information the user may need which is not contained in the cells of the spreadsheet. So we poke a hole in the safe space using the Safe::Hole module. This lets us allow access to external information. Obviously this needs to be done with some degree of caution.

At the beginning of lonspreadsheet.pm we have the following code:

use Safe;

use Safe::Hole;

The function &initsheet, which is called when a spreadsheet is created or modified, defines the safe space for the execution of spreadsheet code:

sub initsheet {

    my $safeeval = new Safe(shift);

    my $safehole = new Safe::Hole;

    $safeeval->permit("entereval");

    $safeeval->permit(":base_math");

    $safeeval->permit("sort");

    $safeeval->deny(":base_io");

    $safehole->wrap(\&Apache::lonnet::EXT,$safeeval,'&EXT');

    my $code=<<'ENDDEFS';

.

functions and variables needed in the safe space are defined here

.

ENDDEFS

    $safeeval->reval($code);

    return $safeeval;

}

Change is coming

Currently the spreadsheet is scheduled to undergo major revisions by the end of the summer. The goal of these revisions is to increase the speed and add some requested functionality. We hope to add:

*          Improved exporting of the spreadsheet date to client side spreadsheets

*          Exporting of spreadsheet xml - allowing users to save spreadsheets from their classes for reuse.

*          Additional spreadsheet functions.

 

Discussion

loncapa/loncom/interface/lonfeedback.pm handles feedback on resources. Feedback can be for course discussion of a resource or to communicate with the author of the resource. In the latter case, a screenshot of the resource and (if applicable) the students previous attempts to solve the problem.

Course discussion messages appear at the bottom of the resource being discussed. There are two types of attribution in course discussion messages. Users may choose to have their LON-CAPA id shown to everyone or they may have it shown only to instructors. Complete anonymity is not an option. If the users choose to hide their LON-CAPA id (an 'anonymous' message), they can set the name given in the [PREF] page.

Figures 2.2.8 through 2.2.10 show a course discussion feedback cycle.

Fig 2.2.8 - A Simple Resource

Fig. 2.2.9 Composing Discussion Feedback 

Fig 2.2.10 The Resource with Anonymous and Non-anonymous Discussion

Messaging

 

loncapa/loncom/interface/lonmsg.pm provides functions for sending users messages. All messaging is currently done via lonmsg.pm. The following subroutines handle the sending of various types of messages:

author_res_msg

Send a message to the author of a resource.

user_crit_msg

Send a critical message to a user. Critical messages require the user to acknowledge receipt before any other action in LON-CAPA can be taken.

user_crit_received

Notify the sender of a critical message that the message has been received.

user_normal_msg

Send a non-critical message to a user.

statuschange

Change the status of a message (read, replied, forwarded, etc)

The lonmsg::handler takes care of the display and sending of messages. If you have the time, communicate with yourself! Note: Critical messages are displayed on login to LON-CAPA. Some message types are only available for course coordinators.

 

Resource Feedback

Fig. 2.2.11 Ð Example of a Feedback


\ No newline at end of file + + + + + +Session Two: Spreadsheet and Messaging (Matthew) + + + +
+

Session Two: Spreadsheet and Messaging (Matthew)

+

Spreadsheets

+

The spreadsheet presents data on student performance on + homework problems. Spreadsheets are handled by loncom/interface/lonspreadsheet.pm + and are completely web based. A person who has selected a student role will + access the spreadsheets using the [GRDS] button. A course coordinator is given + access via the [SPRS] button. Students are not able to see data on anyone's + performance but their own. Students are also not allowed to save spreadsheets. +

+

Spreadsheet Structure and Hierarchy

+

The spreadsheets are laid out in the typical fashion, + with some limitations. There can only be 52 columns, addressed [A-Za-z]. There + may be any number of rows, but currently there do not exist facilities to + add rows other than those automatically generated.

+

There are three levels of spreadsheets, as illustrated + in Fig. 2.2.1.

+

Fig. 2.1.1 Ð Spreadsheet + Hierarchy

+

The rightmost spreadsheets are the assessment spreadsheets. + The middle spreadsheets are the student spreadsheets. The left spreadsheet + is the course spreadsheet.

+

Export Rows

+

The hierarchy of spreadsheets described above allows + data from the lower level spreadsheets (assessment and student) to be exported + up to the higher level spreadsheets (student and course, respectively). Row + 0 is the export row. Only the cells A0-Z0 are exported. Cells a0-z0 are not + exported and can be used as 'scratch' space for the results exported in A0-Z0. +

+

The export rows in the image are shown shaded in + figure 2.2.1. Where the exported rows appear in the student and course spreadsheets + is indicated by arrows.

+

Assessment Spreadsheet

+

The assessment spreadsheet gives data on the students + performance on a specific resource in LON-CAPA (typically a *.problem resource). + Parameters such as the due date, the number of tries possible, the number + of attempts made, the correctness of the student solution, and any <parameter> + tags inserted in the resource will be shown. Fig. 2.2.2 + shows an example of an assessment spreadsheet.

+

+

Fig. 2.2.2 Ð Example Spreadsheet on Assessment Level

+

Student Spreadsheet

+

Each assessment spreadsheet exports a row into the student + spreadsheet. Fig 2.2.3 shows an example student spreadsheet. The student spreadsheet + exports a row to the course spreadsheet.

+

Fig. 2.2.3 shows the next level up spreadsheet with the exported + data from this sheet.

+

+

Fig. 2.2.3 + Ð Default Spreadsheet on Student Level

+

Course Spreadsheet

+

The course spreadsheet gives a summary of each students performance in the + course as a whole. Fig 2.2.4 shows the default course spreadsheet.

+

+

Fig. 2.2.4 + Ð Default Spreadsheet on Course Level

+

Spreadsheet definition

+

The default spreadsheets are defined via xml. Fig. + 2.2.5 shows a sample definition of a + spreadsheet. However, it is possible to work with spreadsheets and never edit + the xml for the spreadsheet itself. By modifying the contents of cells via + the web interface and saving the results, instructors can create as complicated + a spreadsheet as they like. It is now possible for users to upload spreadsheets + to the library server, publish them, and set them as the default sheets for + their course.

+
+

[www@zaphod www]$ cat /home/httpd/html/res/adm/includes/default.assesscalc

+

<field col=A row=0>[stores_0_solved]</field>

+

<field col=B row=0>'Tries:'</field>

+

<field col=C row=0>[stores_0_tries]</field>

+

<field col=D row=0>'Timestamp:'</field>

+

<field col=E row=0>[timestamp]</field>

+

<field col=F row=0>'Duedate:'</field>

+

<field col=G row=0>[parameter_0_duedate]</field>

+

<field col=W row=0>'Available Points:'</field>

+

<field col=X row=0>[parameter_0_weight]</field>

+

<field col=Y row=0>'Awarded Points:'</field>

+

<field col=Z row=0>[parameter_0_weight]*[stores_0_awarded]</field>

+
+

Fig. 2.2.5 + Ð Default Spreadsheet on Assessment Level

+

Template Row

+

The template row of a spreadsheets will make the contents + of a given column identical for each row. The contents of the template row + are shown verbatim, and not evaluated. Fig 2.2.6 shows the template row in + use.

+

+

Fig. 2.2.7 + Ð Customized Spreadsheet on Student Level Shows + a course-customized student-level spreadsheet with many of these functions, + templates and wildcards in action. In the dialog window, &SUM(Òd*Ó) is entered as the expression for cell H0, which will + add up all cells in column d. The template row is used to define expressions + for columns a, b, c, and d, where for b and d both the Ô#Õ wildcard and access + to the EXT function is used in order to multiply the respective X and Z cells + in each row with 1 or 0 depending on whether the value in G (the duedate) + is smaller or larger than the system time (Ò?Ó is the standard Perl choice + operator).

+

What goes in a cell

+

A cell contains either parameter data (which cannot be + changed) or perl code. Additionally, cells can contain references to other + cells and these references can be passed as parameters to perl functions. + Parameters can be accessed via the cell they are stored in or by the parameter + name.

+

Parameter Access

+

Parameters can be accessed by enclosing the parameter + name in square brackets. A new feature allows the accessing of parameters + by enclosing only enough information to lead to a unique parameter. "[part_0_duedate]" + will give the same value as "[duedate]" if there are no other parameters + which contain the string "duedate".

+

Addressing other cells

+

Cells are specified by the letter-number combination + of their position in the table, for example "A5". There are also + wildcards '*' and '#' which are used in ranges and templates, respectively, + and symbolic names.

+

Valid ranges are for example "A5..C7" + which is the square between cells A5 to C7, as in A5, A6, A7, B5, etc. Also, + wildcards can be used, as in "A*" for column A, or "*5" + for row 5. For example, &SUM("d*") will add up all cells in + column d. The table below gives a brief summary of the range options.

+

*          + all rows, all columns

+

B*       all rows + in column B

+

*5        all + columns in row 5

+

C5..F25           + all cells in the rectangle between C5 and F25

+

The template row allows the use of "A#", which will result in "A5" + in row 5, "A6" in row 6, etc.

+

Spreadsheet Functions

+

Many perl functions are available + in the spreadsheet (see "The Safe Environment" below). Additionally, + some spreadsheet specific functions have been defined as well. A complete + list is available by executing 'perldoc loncapa/loncom/interface/lonspreadsheet.pm' + on the command line. An abbreviated table appears in Fig. 2.2.7.

+
+

&NUM(range) Ð number + of non-empty cells in range

+

&BIN(low, high, range) + Ð number of non-empty cells in range + with values between low and + high

+

&SUM(range) Ð sum of + the non-empty cells in range

+

&MEAN(range) Ð mean value + of non-empty cells in range

+

&STDDEV(range) Ð standard + deviation of non-empty cells in range

+

&PROD(range) Ð product + of non-empty cells in range

+

&MAX(range) Ð maximum + value of non-empty cell in range

+

&MIN(range) Ð minimum + value of non-empty cells in range

+

&SUMMAX(n ,range) Ð sum + of the maximum n non-empty + cells in range

+

&SUMMIN(n, range) Ð sum + of the minimum n non-empty + cells in range

+

&EXT(expression) Ð access + to EXT function in lonnet

+
+

Fig. 2.2.7 + Ð Available Functions in Spreadsheet

+

The Safe Environment

+

The spreadsheet cells are evaluated in a "Safe" + environment. The module Safe.pm is included in the standard systemperl RPM + put out by the LON-CAPA developers, but is written by Tim Bunce and Malcolm + Beattie. If you execute 'perldoc Safe' you can read the documentation for + the module.

+

The Safe.pm module allows users to "compile + and execute code in restricted compartments". We use this to allow users + to implement in their spreadsheets a restricted set of perl functions, variables, + and operators. No one using the spreadsheet should ever need access to the + basic IO functions of Perl, for example, so these are not made available to + the users.

+

Each cell is evaluated within the same safe space, + so cells can actually contain function and declarations.

+

There is information the user may need which is + not contained in the cells of the spreadsheet. So we poke a hole in the safe + space using the Safe::Hole module. This lets us allow access to external information. + Obviously this needs to be done with some degree of caution.

+

At the beginning of lonspreadsheet.pm we have the + following code:

+

use Safe;

+

use Safe::Hole;

+

The function &initsheet, which is called when + a spreadsheet is created or modified, defines the safe space for the execution + of spreadsheet code:

+

sub initsheet {

+

    my + $safeeval = new Safe(shift);

+

    my + $safehole = new Safe::Hole;

+

    $safeeval->permit("entereval");

+

    $safeeval->permit(":base_math");

+

    $safeeval->permit("sort");

+

    $safeeval->deny(":base_io");

+

    $safehole->wrap(\&Apache::lonnet::EXT,$safeeval,'&EXT');

+

    my + $code=<<'ENDDEFS';

+

.

+

functions and variables + needed in the safe space are defined here

+

.

+

ENDDEFS

+

    $safeeval->reval($code);

+

    return + $safeeval;

+

}

+

Change is coming

+

Currently the spreadsheet is scheduled to undergo + major revisions by the end of the summer. The goal of these revisions is to + increase the speed and add some requested functionality. We hope to add:

+

*          + Improved exporting of the spreadsheet date to client side spreadsheets

+

*          + Exporting of spreadsheet xml - allowing users to save spreadsheets from their + classes for reuse.

+

*          + Additional spreadsheet functions.

+

 

+

Discussion

+

loncapa/loncom/interface/lonfeedback.pm handles + feedback on resources. Feedback can be for course discussion of a resource + or to communicate with the author of the resource. In the latter case, a screenshot + of the resource and (if applicable) the students previous attempts to solve + the problem.

+

Course discussion messages appear at the bottom + of the resource being discussed. There are two types of attribution in course + discussion messages. Users may choose to have their LON-CAPA id shown to everyone + or they may have it shown only to instructors. Complete anonymity is not an + option. If the users choose to hide their LON-CAPA id (an 'anonymous' message), + they can set the name given in the [PREF] page.

+

Figures 2.2.8 through 2.2.10 show + a course discussion feedback cycle.

+

+

Fig 2.2.8 - A Simple Resource

+

+

Fig. 2.2.9 Composing Discussion Feedback 

+

+

Fig 2.2.10 The Resource with Anonymous and Non-anonymous Discussion

+

Messaging

+
+

 

+

loncapa/loncom/interface/lonmsg.pm provides functions + for sending users messages. All messaging is currently done via lonmsg.pm. The + following subroutines handle the sending of various types of messages:

+

author_res_msg

+

Send a message to the author of a resource.

+

user_crit_msg

+

Send a critical message to a user. Critical messages + require the user to acknowledge receipt before any other action in LON-CAPA + can be taken.

+

user_crit_received

+

Notify the sender of a critical message that the + message has been received.

+

user_normal_msg

+

Send a non-critical message to a user.

+

statuschange

+

Change the status of a message (read, replied, forwarded, + etc)

+

The lonmsg::handler takes care of the display and + sending of messages. If you have the time, communicate with yourself! Note: + Critical messages are displayed on login to LON-CAPA. Some message types are + only available for course coordinators.

+

 

+

Resource Feedback

+

+

Fig. 2.2.11 + Ð Example of a Feedback

+
+
+ +