diff --git a/doc/public/course_data_formats/drag_and_drop/drag-n-drop-demo.xml b/doc/public/course_data_formats/drag_and_drop/drag-n-drop-demo.xml new file mode 100644 index 0000000000..67712407a1 --- /dev/null +++ b/doc/public/course_data_formats/drag_and_drop/drag-n-drop-demo.xml @@ -0,0 +1,526 @@ + + + + +

[Anyof rule example]


+

Please label hydrogen atoms connected with left carbon atom.

+
+ + + + + + + + + + + + + + + + + + + + + + + + +

[Complex grading example]


+

Describe carbon molecule in LCAO-MO.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

[Another complex grading example]


+

Describe oxygen molecule in LCAO-MO

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

[Individual targets with outlines, One draggable per target]


+

+ Drag -Ant- to first position and -Star- to third position


+ + + + + + + + + + + + + + + + + + + + + + + +

[SMALL IMAGE, Individual targets WITHOUT outlines, One draggable + per target]


+

+ Move -Star- to the volcano opening, and -Label3- on to + the right ear of the cow. +


+ + + + + + + + + + + + + + + + + + + + + + +

[Many draggables per target]


+

Move -Star- and -Ant- to most left target + and -Label3- and -Label2- to most right target.


+ + + + + + + + + + + + + + + + + + + + + + + +

[Draggables can be placed anywhere on base image]


+

+ Place -Grass- in the middle of the image and -Ant- in the + right upper corner.


+ + + + + + + + + + + + + + + + + + + +

[Another anyof example]


+

Please identify the Carbon and Oxygen atoms in the molecule.


+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

[Again another anyof example]


+

If the element appears in this molecule, drag the label onto it

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

[Wrong base image url example] +


+ + + + + + + + + + + + + + + + + + + + + diff --git a/doc/public/course_data_formats/drag_and_drop/drag-n-drop-demo2.xml b/doc/public/course_data_formats/drag_and_drop/drag-n-drop-demo2.xml new file mode 100644 index 0000000000..6ffac18e44 --- /dev/null +++ b/doc/public/course_data_formats/drag_and_drop/drag-n-drop-demo2.xml @@ -0,0 +1,373 @@ + + + + +

[Draggable is reusable example]

+
+

Please label all hydrogen atoms.

+
+ + + + + + + + + + + + + + + + + + + + + + + + +

[Complex grading example]


+

Describe carbon molecule in LCAO-MO.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

[Many draggables per target]


+

Move two Stars and three Ants to most left target + and one Label3 and four Label2 to most right target.


+ + + + + + + + + + + + + + + + + + + + + + + +

[Draggables can be placed anywhere on base image]


+

+ Place -Grass- in the middle of the image and -Ant- in the + right upper corner.


+ + + + + + + + + + + + + + + + + + + +

[Another anyof example]


+

Please identify the Carbon and Oxygen atoms in the molecule.


+ + + + + + + + + + + + + + + + + + + + + + + + + + + +

[Exact number of draggables for a set of targets.]


+

Drag two Grass and one Star to first or second positions, and three Cloud to any of the three positions.

+
+ + + + + + + + + + + + + + + + + + + + + + + +

[As many as you like draggables for a set of targets.]


+

Drag some Grass to any of the targets, and some Stars to either first or last target.

+
+ + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/public/course_data_formats/drag_and_drop/drag_and_drop_input.rst b/doc/public/course_data_formats/drag_and_drop/drag_and_drop_input.rst new file mode 100644 index 0000000000..4d61038054 --- /dev/null +++ b/doc/public/course_data_formats/drag_and_drop/drag_and_drop_input.rst @@ -0,0 +1,323 @@ +********************************************** +XML format of drag and drop input [inputtypes] +********************************************** + +.. module:: drag_and_drop_input + +Format description +================== + +The main tag of Drag and Drop (DnD) input is:: + + ... + +``drag_and_drop_input`` can include any number of the following 2 tags: +``draggable`` and ``target``. + +drag_and_drop_input tag +----------------------- + +The main container for a single instance of DnD. The following attributes can +be specified for this tag:: + + img - Relative path to an image that will be the base image. All draggables + can be dragged onto it. + target_outline - Specify whether an outline (gray dashed line) should be + drawn around targets (if they are specified). It can be either + 'true' or 'false'. If not specified, the default value is + 'false'. + one_per_target - Specify whether to allow more than one draggable to be + placed onto a single target. It can be either 'true' or 'false'. If + not specified, the default value is 'true'. + no_labels - default is false, in default behaviour if label is not set, label + is obtained from id. If no_labels is true, labels are not automatically + populated from id, and one can not set labels and obtain only icons. + +draggable tag +------------- + +Draggable tag specifies a single draggable object which has the following +attributes:: + + id - Unique identifier of the draggable object. + label - Human readable label that will be shown to the user. + icon - Relative path to an image that will be shown to the user. + can_reuse - true or false, default is false. If true, same draggable can be + used multiple times. + +A draggable is what the user must drag out of the slider and place onto the +base image. After a drag operation, if the center of the draggable ends up +outside the rectangular dimensions of the image, it will be returned back +to the slider. + +In order for the grader to work, it is essential that a unique ID +is provided. Otherwise, there will be no way to tell which draggable is at what +coordinate, or over what target. Label and icon attributes are optional. If +they are provided they will be used, otherwise, you can have an empty +draggable. The path is relative to 'course_folder' folder, for example, +/static/images/img1.png. + +target tag +---------- + +Target tag specifies a single target object which has the following required +attributes:: + + id - Unique identifier of the target object. + x - X-coordinate on the base image where the top left corner of the target + will be positioned. + y - Y-coordinate on the base image where the top left corner of the target + will be positioned. + w - Width of the target. + h - Height of the target. + +A target specifies a place on the base image where a draggable can be +positioned. By design, if the center of a draggable lies within the target +(i.e. in the rectangle defined by [[x, y], [x + w, y + h]], then it is within +the target. Otherwise, it is outside. + +If at lest one target is provided, the behavior of the client side logic +changes. If a draggable is not dragged on to a target, it is returned back to +the slider. + +If no targets are provided, then a draggable can be dragged and placed anywhere +on the base image. + +correct answer format +--------------------- + +There are two correct answer formats: short and long +If short from correct answer is mapping of 'draggable_id' to 'target_id':: + + correct_answer = {'grass': [[300, 200], 200], 'ant': [[500, 0], 200]} + correct_answer = {'name4': 't1', '7': 't2'} + +In long form correct answer is list of dicts. Every dict has 3 keys: +draggables, targets and rule. For example:: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['t5_c', 't6_c'], + 'rule': 'anyof' + }, + { + 'draggables': ['1', '2'], + 'targets': ['t2_h', 't3_h', 't4_h', 't7_h', 't8_h', 't10_h'], + 'rule': 'anyof' + }] + +Draggables is list of draggables id. Target is list of targets id, draggables +must be dragged to with considering rule. Rule is string. + +Draggables in dicts inside correct_answer list must not intersect!!! + +Wrong (for draggable id 7):: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['t5_c', 't6_c'], + 'rule': 'anyof' + }, + { + 'draggables': ['7', '2'], + 'targets': ['t2_h', 't3_h', 't4_h', 't7_h', 't8_h', 't10_h'], + 'rule': 'anyof' + }] + +Rules are: exact, anyof, unordered_equal, anyof+number, unordered_equal+number + + +.. such long lines are needed for sphinx to display lists correctly + +- Exact rule means that targets for draggable id's in user_answer are the same that targets from correct answer. For example, for draggables 7 and 8 user must drag 7 to target1 and 8 to target2 if correct_answer is:: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['tartget1', 'target2'], + 'rule': 'exact' + }] + + +- unordered_equal rule allows draggables be dragged to targets unordered. If one want to allow for student to drag 7 to target1 or target2 and 8 to target2 or target 1 and 7 and 8 must be in different targets, then correct answer must be:: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['tartget1', 'target2'], + 'rule': 'unordered_equal' + }] + + +- Anyof rule allows draggables to be dragged to any of targets. If one want to allow for student to drag 7 and 8 to target1 or target2, which means that if 7 is on target1 and 8 is on target1 or 7 on target2 and 8 on target2 or 7 on target1 and 8 on target2. Any of theese are correct which anyof rule:: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['tartget1', 'target2'], + 'rule': 'anyof' + }] + + +- If you have can_reuse true, then you, for example, have draggables a,b,c and 10 targets. These will allow you to drag 4 'a' draggables to ['target1', 'target4', 'target7', 'target10'] , you do not need to write 'a' four times. Also this will allow you to drag 'b' draggable to target2 or target5 for target5 and target2 etc..:: + + correct_answer = [ + { + 'draggables': ['a'], + 'targets': ['target1', 'target4', 'target7', 'target10'], + 'rule': 'unordered_equal' + }, + { + 'draggables': ['b'], + 'targets': ['target2', 'target5', 'target8'], + 'rule': 'anyof' + }, + { + 'draggables': ['c'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'unordered_equal' + }] + +- And sometimes you want to allow drag only two 'b' draggables, in these case you sould use 'anyof+number' of 'unordered_equal+number' rule:: + + correct_answer = [ + { + 'draggables': ['a', 'a', 'a'], + 'targets': ['target1', 'target4', 'target7'], + 'rule': 'unordered_equal+numbers' + }, + { + 'draggables': ['b', 'b'], + 'targets': ['target2', 'target5', 'target8'], + 'rule': 'anyof+numbers' + }, + { + 'draggables': ['c'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'unordered_equal' + }] + +In case if we have no multiple draggables per targets (one_per_target="true"), +for same number of draggables, anyof is equal to unordered_equal + +If we have can_reuse=true, than one must use only long form of correct answer. + + +Grading logic +------------- + +1. User answer (that comes from browser) and correct answer (from xml) are parsed to the same format:: + + group_id: group_draggables, group_targets, group_rule + + +Group_id is ordinal number, for every dict in correct answer incremental +group_id is assigned: 0, 1, 2, ... + +Draggables from user answer are added to same group_id where identical draggables +from correct answer are, for example:: + + If correct_draggables[group_0] = [t1, t2] then + user_draggables[group_0] are all draggables t1 and t2 from user answer: + [t1] or [t1, t2] or [t1, t2, t2] etc.. + +2. For every group from user answer, for that group draggables, if 'number' is in group rule, set() is applied, +if 'number' is not in rule, set is not applied:: + + set() : [t1, t2, t3, t3] -> [t1, t2, ,t3] + +For every group, at this step, draggables lists are equal. + + +3. For every group, lists of targets are compared using rule for that group. + + +Set and '+number' cases +....................... + +Set() and '+number' are needed only for case of reusable draggables, +for other cases there are no equal draggables in list, so set() does nothing. + +.. such long lines needed for sphinx to display nicely + +* Usage of set() operation allows easily create rule for case of "any number of same draggable can be dragged to some targets":: + + { + 'draggables': ['draggable_1'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'anyof' + } + + + + +* 'number' rule is used for the case of reusable draggables, when one want to fix number of draggable to drag. In this example only two instances of draggables_1 are allowed to be dragged:: + + { + 'draggables': ['draggable_1', 'draggable_1'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'anyof+number' + } + + +* Note, that in using rule 'exact', one does not need 'number', because you can't recognize from user interface which reusable draggable is on which target. Absurd example:: + + { + 'draggables': ['draggable_1', 'draggable_1', 'draggable_2'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'exact' + } + + + Correct handling of this example is to create different rules for draggable_1 and + draggable_2 + +* For 'unordered_equal' (or 'exact' too) we don't need 'number' if you have only same draggable in group, as targets length will provide constraint for the number of draggables:: + + { + 'draggables': ['draggable_1'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'unordered_equal' + } + + + This means that only three draggaggables 'draggable_1' can be dragged. + +* But if you have more that one different reusable draggable in list, you may use 'number' rule:: + + { + 'draggables': ['draggable_1', 'draggable_1', 'draggable_2'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'unordered_equal+number' + } + + + If not use number, draggables list will be setted to ['draggable_1', 'draggable_2'] + + + + +Logic flow +---------- + +(Click on image to see full size version.) + +.. image:: draganddrop_logic_flow.png + :width: 100% + :target: _images/draganddrop_logic_flow.png + + +Example +======= + +Examples of draggables that can't be reused +------------------------------------------- + +.. literalinclude:: drag-n-drop-demo.xml + +Draggables can be reused +------------------------ + +.. literalinclude:: drag-n-drop-demo2.xml diff --git a/doc/public/course_data_formats/drag_and_drop/draganddrop_logic_flow.png b/doc/public/course_data_formats/drag_and_drop/draganddrop_logic_flow.png new file mode 100644 index 0000000000..2bb1c11a41 Binary files /dev/null and b/doc/public/course_data_formats/drag_and_drop/draganddrop_logic_flow.png differ diff --git a/doc/public/course_data_formats/graphical_slider_tool/graphical_slider_tool.rst b/doc/public/course_data_formats/graphical_slider_tool/graphical_slider_tool.rst new file mode 100644 index 0000000000..3fac46e873 --- /dev/null +++ b/doc/public/course_data_formats/graphical_slider_tool/graphical_slider_tool.rst @@ -0,0 +1,563 @@ +********************************************* +XML format of graphical slider tool [xmodule] +********************************************* + +.. module:: xml_format_gst + + +Format description +================== + +Graphical slider tool (GST) main tag is:: + + BODY + +``graphical_slider_tool`` tag must have two children tags: ``render`` +and ``configuration``. + + +Render tag +---------- + +Render tag can contain usual html tags mixed with some GST specific tags:: + + - represents jQuery slider for changing a parameter's value + - represents a text input field for changing a parameter's value + - represents Flot JS plot element + +Also GST will track all elements inside ```` where ``id`` +attribute is set, and a corresponding parameter referencing that ``id`` is present +in the configuration section below. These will be referred to as dynamic elements. + +The contents of the section will be shown to the user after +all occurrences of:: + + + + + +have been converted to actual sliders, text inputs, and a plot graph. +Everything in square brackets is optional. After initialization, all +text input fields, sliders, and dynamic elements will be set to the initial +values of the parameters that they are assigned to. + +``{parameter name}`` specifies the parameter to which the slider or text +input will be attached to. + +[style="{CSS statements}"] specifies valid CSS styling. It will be passed +directly to the browser without any parsing. + +There is a one-to-one relationship between a slider and a parameter. +I.e. for one parameter you can put only one ```` in the +```` section. However, you don't have to specify a slider - they +are optional. + +There is a many-to-one relationship between text inputs and a +parameter. I.e. for one parameter you can put many '' elements in +the ```` section. However, you don't have to specify a text +input - they are optional. + +You can put only one ```` in the ```` section. It is not +required. + + +Slider tag +.......... + +Slider tag must have ``var`` attribute and optional ``style`` attribute:: + + + +After processing, slider tags will be replaced by jQuery UI sliders with applied +``style`` attribute. + +``var`` attribute must correspond to a parameter. Parameters can be used in any +of the ``function`` tags in ``functions`` tag. By moving slider, value of +parameter ``a`` will change, and so result of function, that depends on parameter +``a``, will also change. + + +Textbox tag +........... + +Texbox tag must have ``var`` attribute and optional ``style`` attribute:: + + + +After processing, textbox tags will be replaced by html text inputs with applied +``style`` attribute. If you want a readonly text input, then you should use a +dynamic element instead (see section below "HTML tagsd with ID"). + +``var`` attribute must correspond to a parameter. Parameters can be used in any +of the ``function`` tags in ``functions`` tag. By changing the value on the text input, +value of parameter ``a`` will change, and so result of function, that depends on +parameter ``a``, will also change. + + +Plot tag +........ + +Plot tag may have optional ``style`` attribute:: + + + +After processing plot tags will be replaced by Flot JS plot with applied +``style`` attribute. + + +HTML tags with ID (dynamic elements) +.................................... + +Any HTML tag with ID, e.g. ```` can be used as a +place where result of function can be inserted. To insert function result to +an element, element ID must be included in ``function`` tag as ``el_id`` attribute +and ``output`` value must be ``"element"``:: + + + function add(a, b, precision) { + var x = Math.pow(10, precision || 2); + return (Math.round(a * x) + Math.round(b * x)) / x; + } + + return add(a, b, 5); + + + +Configuration tag +----------------- + +The configuration tag contains parameter settings, graph +settings, and function definitions which are to be plotted on the +graph and that use specified parameters. + +Configuration tag contains two mandatory tag ``functions`` and ``parameters`` and +may contain another ``plot`` tag. + + +Parameters tag +.............. + +``Parameters`` tag contains ``parameter`` tags. Each ``parameter`` tag must have +``var``, ``max``, ``min``, ``step`` and ``initial`` attributes:: + + + + + + +``var`` attribute links min, max, step and initial values to parameter name. + +``min`` attribute is the minimal value that a parameter can take. Slider and input +values can not go below it. + +``max`` attribute is the maximal value that a parameter can take. Slider and input +values can not go over it. + +``step`` attribute is value of slider step. When a slider increase or decreases +the specified parameter, it will do so by the amount specified with 'step' + +``initial`` attribute is the initial value that the specified parameter should be +set to. Sliders and inputs will initially show this value. + +The parameter's name is specified by the ``var`` property. All occurrences +of sliders and/or text inputs that specify a ``var`` property, will be +connected to this parameter - i.e. they will reflect the current +value of the parameter, and will be updated when the parameter +changes. + +If at lest one of these attributes is not set, then the parameter +will not be used, slider's and/or text input elements that specify +this parameter will not be activated, and the specified functions +which use this parameter will not return a numeric value. This means +that neglecting to specify at least one of the attributes for some +parameter will have the result of the whole GST instance not working +properly. + + +Functions tag +............. + +For the GST to do something, you must defined at least one +function, which can use any of the specified parameter values. The +function expects to take the ``x`` value, do some calculations, and +return the ``y`` value. I.e. this is a 2D plot in Cartesian +coordinates. This is how the default function is meant to be used for +the graph. + +There are other special cases of functions. They are used mainly for +outputting to elements, plot labels, or for custom output. Because +the return a single value, and that value is meant for a single element, +these function are invoked only with the set of all of the parameters. +I.e. no ``x`` value is available inside them. They are useful for +showing the current value of a parameter, showing complex static +formulas where some parameter's value must change, and other useful +things. + +The different style of function is specified by the ``output`` attribute. + +Each function must be defined inside ``function`` tag in ``functions`` tag:: + + + + function add(a, b, precision) { + var x = Math.pow(10, precision || 2); + return (Math.round(a * x) + Math.round(b * x)) / x; + } + + return add(a, b, 5); + + + +The parameter names (along with their values, as provided from text +inputs and/or sliders), will be available inside all defined +functions. A defined function body string will be parsed internally +by the browser's JavaScript engine and converted to a true JS +function. + +The function's parameter list will automatically be created and +populated, and will include the ``x`` (when ``output`` is not specified or +is set to ``"graph"``), and all of the specified parameter values (from sliders +and text inputs). This means that each of the defined functions will have +access to all of the parameter values. You don't have to use them, but +they will be there. + +Examples:: + + + return x; + + + + return (x + a) * Math.sin(x * b); + + + + function helperFunc(c1) { + return c1 * c1 - a; + } + return helperFunc(x + 10 * a * b) + Math.sin(a - x); + + +Required parameters:: + + function body: + + A string composing a normal JavaScript function + except that there is no function declaration + (along with parameters), and no closing bracket. + + So if you normally would have written your + JavaScript function like this: + + function myFunc(x, a, b) { + return x * a + b; + } + + here you must specify just the function body + (everything that goes between '{' and '}'). So, + you would specify the above function like so (the + bare-bone minimum): + + return x * a + b; + + VERY IMPORTANT: Because the function will be passed + to the browser as a single string, depending on implementation + specifics, the end-of-line characters can be stripped. This + means that single line JavaScript comments (starting with "//") + can lead to the effect that everything after the first such comment + will be treated as a comment. Therefore, it is absolutely + necessary that such single line comments are not used when + defining functions for GST. You can safely use the alternative + multiple line JavaScript comments (such comments start with "/*" + and end with "*/). + + VERY IMPORTANT: If you have a large function body, and decide to + split it into several lines, than you must wrap it in "CDATA" like + so: + + + + + +Optional parameters:: + + + color: Color name ('red', 'green', etc.) or in the form of + '#FFFF00'. If not specified, a default color (different + one for each graphed function) will be given by Flot JS. + line: A string - 'true' or 'false'. Should the data points be + connected by a line on the graph? Default is 'true'. + dot: A string - 'true' or 'false'. Should points be shown for + each data point on the graph? Default is 'false'. + bar: A string - 'true' or 'false'. When set to 'true', points + will be plotted as bars. + label: A string. If provided, will be shown in the legend, along + with the color that was used to plot the function. + output: 'element', 'none', 'plot_label', or 'graph'. If not defined, + function will be plotted (same as setting 'output' to 'graph'). + If defined, and other than 'graph', function will not be + plotted, but it's output will be inserted into the element + with ID specified by 'el_id' attribute. + el_id: Id of HTML element, defined in '' section. Value of + function will be inserted as content of this element. + disable_auto_return: By default, if JavaScript function string is written + without a "return" statement, the "return" will be + prepended to it. Set to "true" to disable this + functionality. This is done so that simple functions + can be defined in an easy fashion (for example, "a", + which will be translated into "return a"). + update_on: A string - 'change', or 'slide'. Default (if not set) is + 'slide'. This defines the event on which a given function is + called, and its result is inserted into an element. This + setting is relevant only when "output" is other than "graph". + +When specifying ``el_id``, it is essential to set "output" to one of + element - GST will invoke the function, and the return of it will be + inserted into a HTML element with id specified by ``el_id``. + none - GST will simply inoke the function. It is left to the instructor + who writes the JavaScript function body to update all necesary + HTML elements inside the function, before it exits. This is done + so that extra steps can be preformed after an HTML element has + been updated with a value. Note, that because the return value + from this function is not actually used, it will be tempting to + omit the "return" statement. However, in this case, the attribute + "disable_auto_return" must be set to "true" in order to prevent + GST from inserting a "return" statement automatically. + plot_label - GST will process all plot labels (which are strings), and + will replace the all instances of substrings specified by + ``el_id`` with the returned value of the function. This is + necessary if you want a label in the graph to have some changing + number. Because of the nature of Flot JS, it is impossible to + achieve the same effect by setting the "output" attribute + to "element", and including a HTML element in the label. + +The above values for "output" will tell GST that the function is meant for an +HTML element (not for graph), and that it should not get an 'x' parameter (along +with some value). + + +[Note on MathJax and labels] +............................ + +Independently of this module, will render all TeX code +within the ```` section into nice mathematical formulas. Just +remember to wrap it in one of:: + + \( and \) - for inline formulas (formulas surrounded by + standard text) + \[ and \] - if you want the formula to be a separate line + +It is possible to define a label in standard TeX notation. The JS +library MathJax will work on these labels also because they are +inserted on top of the plot as standard HTML (text within a DIV). + +If the label is dynamic, i.e. it will contain some text (numeric, or other) +that has to be updated on a parameter's change, then one can define +a special function to handle this. The "output" of such a function must be +set to "none", and the JavaScript code inside this function must update the +MathJax element by itself. Before exiting, MathJax typeset function should +be called so that the new text will be re-rendered by MathJax. For example, + + + ... + + + ... + + + + ... + + +Plot tag +........ + +``Plot`` tag inside ``configuration`` tag defines settings for plot output. + +Required parameters:: + + xrange: 2 functions that must return value. Value is constant (3.1415) + or depend on parameter from parameters section: + + return 0; + return 30; + + or + + return -a; + return a; + + + All functions will be calculated over domain between xrange:min + and xrange:max. Xrange depending on parameter is extremely + useful when domain(s) of your function(s) depends on parameter + (like circle, when parameter is radius and you want to allow + to change it). + +Optional parameters:: + + num_points: Number of data points to generated for the plot. If + this is not set, the number of points will be + calculated as width / 5. + + bar_width: If functions are present which are to be plotted as bars, + then this parameter specifies the width of the bars. A + numeric value for this parameter is expected. + + bar_align: If functions are present which are to be plotted as bars, + then this parameter specifies how to align the bars relative + to the tick. Available values are "left" and "center". + + xticks, + yticks: 3 floating point numbers separated by commas. This + specifies how many ticks are created, what number they + start at, and what number they end at. This is different + from the 'xrange' setting in that it has nothing to do + with the data points - it control what area of the + Cartesian space you will see. The first number is the + first tick's value, the second number is the step + between each tick, the third number is the value of the + last tick. If these configurations are not specified, + Flot will chose them for you based on the data points + set that he is currently plotting. Usually, this results + in a nice graph, however, sometimes you need to fine + grain the controls. For example, when you want to show + a fixed area of the Cartesian space, even when the data + set changes. On it's own, Flot will recalculate the + ticks, which will result in a different graph each time. + By specifying the xticks, yticks configurations, only + the plotted data will change - the axes (ticks) will + remain as you have defined them. + + xticks_names, yticks_names: + A JSON string which represents a mapping of xticks, yticks + values to some defined strings. If specified, the graph will + not have any xticks, yticks except those for which a string + value has been defined in the JSON string. Note that the + matching will be string-based and not numeric. I.e. if a tick + value was "3.70" before, then inside the JSON there should be + a mapping like {..., "3.70": "Some string", ...}. Example: + + + + + + + + + + xunits, + yunits: Units values to be set on axes. Use MathJax. Example: + \(cm\) + \(m\) + + moving_label: + A way to specify a label that should be positioned dynamically, + based on the values of some parameters, or some other factors. + It is similar to a , but it is only valid for a plot + because it is drawn relative to the plot coordinate system. + + Multiple "moving_label" configurations can be provided, each one + with a unique text and a unique set of functions that determine + it's dynamic positioning. + + Each "moving_label" can have a "color" attribute (CSS color notation), + and a "weight" attribute. "weight" can be one of "normal" or "bold", + and determines the styling of moving label's text. + + Each "moving_label" function should return an object with a 'x' + and 'y properties. Within those functions, all of the parameter + names along with their value are available. + + Example (note that "return" statement is missing; it will be automatically + inserted by GST): + + + + +

Graphic slider tool: Bar graph example.

+ +

We can request the API to plot us a bar graph.

+
+

a

+ + +


+

b

+ + +
+ + + + + + + + + + 0.9) && (x<1.1)) || ((x>4.9) && (x<5.1))) { return Math.sin(a * 0.01 * Math.PI + 2.952 * x); } + else {return undefined;}]]> + + + 1.9) && (x<2.1)) || ((x>3.9) && (x<4.1))) { return Math.cos(b * 0.01 * Math.PI + 3.432 * x); } + else {return undefined;}]]> + + + 1.9) && (x<2.1)) || ((x>3.9) && (x<4.1))) { return Math.cos((b - 10 * a) * 0.01 * Math.PI + 3.432 * x); } + else {return undefined;}]]> + + + 1.9) && (x<2.1)) || ((x>3.9) && (x<4.1))) { return Math.cos((b + 7 * a) * 0.01 * Math.PI + 3.432 * x); } + else {return undefined;}]]> + + + + 15 + 5 + 0, 0.5, 6 + -1.5, 0.1, 1.5 + + + + + + + 0.4 + + + + diff --git a/doc/public/course_data_formats/graphical_slider_tool/gst_example_dynamic_labels.xml b/doc/public/course_data_formats/graphical_slider_tool/gst_example_dynamic_labels.xml new file mode 100644 index 0000000000..05cbe407fb --- /dev/null +++ b/doc/public/course_data_formats/graphical_slider_tool/gst_example_dynamic_labels.xml @@ -0,0 +1,40 @@ + + + +

Graphic slider tool: Dynamic labels.

+

There are two kinds of dynamic lables. + 1) Dynamic changing values in graph legends. + 2) Dynamic labels, which coordinates depend on parameters

+

a:

+
+

b:

+

+ + + + + + + + + + a * x + b + + a + + + 030 + 10 + 0, 6, 30 + -9, 1, 9 + + + + + + + + + + + \ No newline at end of file diff --git a/doc/public/course_data_formats/graphical_slider_tool/gst_example_dynamic_range.xml b/doc/public/course_data_formats/graphical_slider_tool/gst_example_dynamic_range.xml new file mode 100644 index 0000000000..0ce4263d62 --- /dev/null +++ b/doc/public/course_data_formats/graphical_slider_tool/gst_example_dynamic_range.xml @@ -0,0 +1,37 @@ + + + +

Graphic slider tool: Dynamic range and implicit functions.

+ +

You can make x range (not ticks of x axis) of functions to depend on + parameter value. This can be useful when function domain depends + on parameter.

+

Also implicit functons like circle can be plotted as 2 separate + functions of same color.

+
+ + +
+ + + + + + + + Math.sqrt(a * a - x * x) + -Math.sqrt(a * a - x * x) + + + + + -a + a + + 1000 + -30, 6, 30 + -30, 6, 30 + + + + diff --git a/doc/public/course_data_formats/graphical_slider_tool/gst_example_html_element_output.xml b/doc/public/course_data_formats/graphical_slider_tool/gst_example_html_element_output.xml new file mode 100644 index 0000000000..340783871a --- /dev/null +++ b/doc/public/course_data_formats/graphical_slider_tool/gst_example_html_element_output.xml @@ -0,0 +1,40 @@ + + + +

Graphic slider tool: Output to DOM element.

+ +

a + b =

+ +
+

a

+ + +
+ +
+

b

+ + +
+


+ + + + + + + + + + + function add(a, b, precision) { + var x = Math.pow(10, precision || 2); + return (Math.round(a * x) + Math.round(b * x)) / x; + } + + return add(a, b, 5); + + + + + diff --git a/doc/public/course_data_formats/graphical_slider_tool/gst_example_with_documentation.xml b/doc/public/course_data_formats/graphical_slider_tool/gst_example_with_documentation.xml new file mode 100644 index 0000000000..addada5b10 --- /dev/null +++ b/doc/public/course_data_formats/graphical_slider_tool/gst_example_with_documentation.xml @@ -0,0 +1,91 @@ + + + + +

Graphic slider tool: full example.

+

+ A simple equation + \( + y_1 = 10 \times b \times \frac{sin(a \times x) \times sin(b \times x)}{cos(b \times x) + 10} + \) + can be plotted. +

+ + +
+

Currently \(a\) is

+ + +
+ +

This one + \( + y_2 = sin(a \times x) + \) + will be overlayed on top. +

+
+

Currently \(b\) is

+ +
+
+

To change \(a\) use:

+ +
+
+

To change \(b\) use:

+ +
+ +
+

Second input for b:

+ + +
+ + + + + + + + + + + + + return 10.0 * b * Math.sin(a * x) * Math.sin(b * x) / (Math.cos(b * x) + 10); + + + + Math.sin(a * x); + + + function helperFunc(c1) { + return c1 * c1 - a; + } + + return helperFunc(x + 10 * a * b) + Math.sin(a - x); + + a + + + + + + return 0; + + 30 + + + 120 + + 0, 3, 30 + -1.5, 1.5, 13.5 + + \(cm\) + \(m\) + + + + diff --git a/doc/public/index.rst b/doc/public/index.rst index 1d8b69c33a..e97afbb957 100644 --- a/doc/public/index.rst +++ b/doc/public/index.rst @@ -11,6 +11,15 @@ These are data formats written by people to specify course structure and content course_data_formats/course_xml.rst course_data_formats/grading.rst +Specific Problem Types +^^^^^^^^^^^^^^^^^^^^^^ +.. toctree:: + :maxdepth: 1 + + course_data_formats/drag_and_drop/drag_and_drop_input.rst + course_data_formats/graphical_slider_tool/graphical_slider_tool.rst + + Internal Data Formats --------------------- These document describe how we store course structure, student state/progress, and events internally. Useful for developers or researchers who interact with our raw data exports.