Andal.LND/edx-platform
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added initial docs for Drag and Drop.

Browse Source
This commit is contained in:
Valera Rozuvan
2012-12-28 11:00:55 +02:00
committed by Alexander Kryklia
parent f1f3b2ea8b
commit 744b7947e6
2 changed files with 243 additions and 321 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
docs/source/drag-n-drop-demo.xml Normal file
View File

@@ -0,0 +1,188 @@
<problem display_name="Drag and drop demo" >
<text>
<p>
Drag and drop pictures to proper positions.
</p>
<p>
Drag images to the cow)).
</p>
</text>
<customresponse>
<text>
<h3>Individual targets with outlines. One draggable per target.</h3>
<p> Drag ant to first and star to 3rd. </p>
<br />
</text>
<drag_and_drop_input img="cow.png" target_outline="true">
<draggable id="1" label="Label 1"/>
<draggable id="name_with_icon" label="Ant" icon="images_list/ant.jpg"/>
<draggable id="with_icon" label="Cloud" icon="images_list/cloud.jpg" />
<draggable id="5" label="Label2" />
<draggable id="2" label="Drop" icon="images_list/drop.jpg" />
<draggable id="name_label_icon3" label="Grass" icon="images_list/grass.jpg" />
<draggable id="name4" label="Star" icon="images_list/star.png" />
<draggable id="7" label="Label3" />
<target id="t1" x="20" y="20" w="90" h="90"/>
<target id="t2" x="300" y="100" w="90" h="90"/>
<target id="t3" x="150" y="40" w="50" h="50"/>
</drag_and_drop_input>
<answer type="loncapa/python"><![CDATA[
correct_answer = {'name_with_icon': 't1', 'name4': 't2'}
if draganddrop.grade(submission[0], correct_answer):
correct = ['correct']
else:
correct = ['incorrect']
]]></answer>
</customresponse>
<customresponse>
<text>
<h3>
Individual targets WITHOUT outlines. Move Star to the
volcano opening, and Label3 on to the right ear of the cow.
One draggable per target.
</h3>
<br />
</text>
<drag_and_drop_input img="cow.png" target_outline="false">
<draggable id="1" label="Label 1"/>
<draggable id="name_with_icon" label="Ant" icon="images_list/ant.jpg"/>
<draggable id="with_icon" label="Cloud" icon="images_list/cloud.jpg" />
<draggable id="5" label="Label2" />
<draggable id="2" label="Drop" icon="images_list/drop.jpg" />
<draggable id="name_label_icon3" label="Grass" icon="images_list/grass.jpg" />
<draggable id="name4" label="Star" icon="images_list/star.png" />
<draggable id="7" label="Label3" />
<target id="t1" x="210" y="90" w="90" h="90"/>
<target id="t2" x="400" y="190" w="90" h="90"/>
</drag_and_drop_input>
<answer type="loncapa/python"><![CDATA[
correct_answer = {'name4': 't1',
'7': 't2'}
if draganddrop.grade(submission[0], correct_answer):
correct = ['correct']
else:
correct = ['incorrect']
]]></answer>
</customresponse>
<customresponse>
<text>
<h3>Many draggable per target. Move star and ant to most left target
and lable 3 and label 2 to most right target.</h3>
<br />
</text>
<drag_and_drop_input img="cow.png" target_outline="true" one_per_target="false">
<draggable id="1" label="Label 1"/>
<draggable id="name_with_icon" label="Ant" icon="images_list/ant.jpg"/>
<draggable id="with_icon" label="Cloud" icon="images_list/cloud.jpg" />
<draggable id="5" label="Label2" />
<draggable id="2" label="Drop" icon="images_list/drop.jpg" />
<draggable id="name_label_icon3" label="Grass" icon="images_list/grass.jpg" />
<draggable id="name4" label="Star" icon="images_list/star.png" />
<draggable id="7" label="Label3" />
<target id="t1" x="20" y="20" w="90" h="90"/>
<target id="t2" x="300" y="100" w="90" h="90"/>
<target id="t3" x="150" y="40" w="50" h="50"/>
</drag_and_drop_input>
<answer type="loncapa/python"><![CDATA[
correct_answer = {'name4': 't1',
'name_with_icon': 't1',
'5': 't2',
'7':'t2'}
if draganddrop.grade(submission[0], correct_answer):
correct = ['correct']
else:
correct = ['incorrect']
]]></answer>
</customresponse>
<customresponse>
<text>
<h3>Draggables can be places anywhere on base image.
Place grass in the middle of the image and ant in the
right upper corner.</h3>
<br />
</text>
<drag_and_drop_input img="cow.png" >
<draggable id="1" label="Label 1"/>
<draggable id="ant" label="Ant" icon="images_list/ant.jpg"/>
<draggable id="with_icon" label="Cloud" icon="images_list/cloud.jpg" />
<draggable id="5" label="Label2" />
<draggable id="2" label="Drop" icon="images_list/drop.jpg" />
<draggable id="grass" label="Grass" icon="images_list/grass.jpg" />
<draggable id="name4" label="Star" icon="images_list/star.png" />
<draggable id="7" label="Label3" />
</drag_and_drop_input>
<answer type="loncapa/python"><![CDATA[
correct_answer = {'grass': [[300, 200], 200],
'ant': [[500, 0], 200]}
if draganddrop.grade(submission[0], correct_answer):
correct = ['correct']
else:
correct = ['incorrect']
]]></answer>
</customresponse>
<customresponse>
<text>
<h3>Please identify the Carbon and Oxygen atoms in the molecule.</h3>
<br />
</text>
<drag_and_drop_input img="images_list/ethglycol.jpg" target_outline="true" one_per_target="true">
<draggable id="l1_c" label="Carbon" />
<draggable id="l2" label="Methane"/>
<draggable id="l3_o" label="Oxygen" />
<draggable id="l4" label="Calcium" />
<draggable id="l5" label="Methane"/>
<draggable id="l6" label="Calcium" />
<draggable id="l7" label="Hydrogen" />
<draggable id="l8_c" label="Carbon" />
<draggable id="l9" label="Hydrogen" />
<draggable id="l10_o" label="Oxygen" />
<target id="t1_o" x="10" y="67" w="100" h="100"/>
<target id="t2" x="133" y="3" w="70" h="70"/>
<target id="t3" x="2" y="384" w="70" h="70"/>
<target id="t4" x="95" y="386" w="70" h="70"/>
<target id="t5_c" x="94" y="293" w="91" h="91"/>
<target id="t6_c" x="328" y="294" w="91" h="91"/>
<target id="t7" x="393" y="463" w="70" h="70"/>
<target id="t8" x="344" y="214" w="70" h="70"/>
<target id="t9_o" x="445" y="162" w="100" h="100"/>
<target id="t10" x="591" y="132" w="70" h="70"/>
</drag_and_drop_input>
<answer type="loncapa/python"><![CDATA[
correct_answer = {'l3_o': 't1_o',
'l10_o': 't9_o',
'l1_c': 't5_c',
'l8_c': 't6_c'}
if draganddrop.grade(submission[0], correct_answer):
correct = ['correct']
else:
correct = ['incorrect']
]]></answer>
</customresponse>
</problem>

376
docs/source/drag_and_drop_input.rst
View File

@@ -7,346 +7,80 @@ Xml format of drag and drop input [inputtypes]
Format description
==================
Graphical slider tool (GST) main tag is::
The main tag of Drag and Drop (DnD) input is::
<graphical_slider_tool> BODY </graphical_slider_tool>
<drag_and_drop_input> ... </drag_and_drop_input>
``graphical_slider_tool`` tag must have two children tags: ``render``
and ``configuration``.
``drag_and_drop_input`` can include any number of the following 2 tags:
``draggable`` and ``target``.
Render tag
----------
drag_and_drop_input tag
-----------------------
Render tag can contain usual html tags mixed with some GST specific tags::
The main container for a single instance of DnD. The following attributes can
be specified for this tag::
<slider/> - represents jQuery slider
<textbox/> - represents input
<plot/> - represents Flot plot
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'.
Also GST will track all elements inside ``<render></render>`` where ``id``
attribute is set.
draggable tag
-------------
The contents of the <render> section will be shown to the user after
all occurrences of::
<slider var="{parameter name}" [style="{CSS statements}"]/>
<input var="parameter name" [style="{CSS statements}"] [readonly="true" | readonly="false"]/>
<plot [style="{CSS statements}"]/>
have been converted to actual sliders, text inputs, and a plot graph.
Everything in square brackets is optional.
``{parameter name}`` specifies the parameter to which the slider or text
input will be attached to.
There is a one-to-one relationship between a slider and a parameter.
I.e. for one parameter you can put only one ``<slider ...<`` in the
``<render>`` 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 '<input ...<' in
the ``<render>`` section. However, you don't have to specify a text
input - they are optional.
You can put only one ``<plot ...<`` in the ``<render>`` section. It is not
required.
NOTE: MathJax, independently of this module, will render all TeX code
within the ``<render>`` 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
Slider tag
..........
Slider tag must have ``var`` attribute and optional ``style`` attribute::
<slider var='a' style="width:400px;float:left;"/>
After processing slider tags will be replaced by jQuery UI sliders with applied
``style`` attribute.
``Var`` attribute must correspond to parameter in one of ``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 change.
Textbox tag
...........
Texbox tag must have ``var`` attribute and optional ``style`` and ``readonly``
Draggable tag specifies a single draggable object which has the following
attributes::
<textbox var="b" readonly="true" style="width:50px; float:left; margin-left:10px;"/>
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.
After processing tetbox tags will be replaced by html inputs with applied
``style`` attribute. If ``readonly`` is set to ``true`` input will be
not-editable, default is ``false``.
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.
``Var`` attribute must correspond to parameter in one of ``function`` tags in
``functions`` tag. By entering value in input, value of parameter ``b`` will change, and so
result of function, that depends on parameter ``b``, will change.
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/static/images/' folder.
Plot tag
........
target tag
----------
Plot tag may have optional ``style`` attribute::
Target tag specifies a single target object which has the following required
attributes::
<plot style="width:50px; float:left; margin-left:10px;"/>
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.
After processing plot tags will be replaced by Flot plot with applied
``style`` attribute.
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.
HTML tags with id
.................
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.
Any html tag with id, e.g. ``<span id="answer_span_1">`` will be counted as
place where result of function can be rendered. To render function result to
element, element id must be included in ``function`` tag as ``el_id`` attribute
and ``output`` value must be ``"element"``::
<function output="element" el_id="answer_span_1">
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);
</function>
Configuration tag
-----------------
The configuration tag contain sparameter 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::
<parameters>
<param var="a" min="-10.0" max="10.0" step="0.1" initial="0" />
<param var="b" min="-10.0" max="10.0" step="0.1" initial="0" />
</parameters>
``Var`` attribute links min, max, step and initial values to parameter name.
``Min`` attribute is minimal value that parameter can take. Slider and input
values can not go below it.
``Max`` attribute is maximal value that 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.
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 return a non valid 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.
Each function must be defined inside ``function`` tag in ``functions`` tag::
<functions>
<function output="element" el_id="answer_span_1">
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);
</function>
</functions>
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``, 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::
<function>
return x;
</function>
<function dot="true" label="\(y_2\)">
return (x + a) * Math.sin(x * b);
</function>
<function color="green">
function helperFunc(c1) {
return c1 * c1 - a;
}
return helperFunc(x + 10 * a * b) + Math.sin(a - x);
</function>
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):
<function>
return x * a + b;
</function>
Optional parameters::
color: Color name (red, green, etc.) or in the form of
'#FFFF00'. If not specified, a default color (different
one for each function) will be given by Flot;
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'.
label: A string. If provided, will be shown in the legend, along
with the color that was used to plot the function.
output: "element" or "plot". If not defined, function will be plotted.
If defined, function will not be plotted, but rendered to element
with id set in 'el_id' attribute.
el_id: Id of html element, defined in 'render' section. Value of
function will be rendered to content of this element.
With ``output`` and ``el_id`` set together you can update html elements with
function value, also function will not be plotted.
[note on MathJax and labels]:
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).
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:
<xrange>
<min>return 0;</min>
<max>return 30;</max>
</xrange>
or
<xrange>
<min>return -a;</min>
<max>return a;</max>
</xrange>
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.
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.
xunits,
yunits: Units values to be set on axes. Use MathJax. Example:
<xunits>\(cm\)</xunits>
<yunits>\(m\)</yunits>
If no targets are provided, then a draggable can be dragged and placed anywhere
on the base image.
Example
=======
Plotting, sliders and inputs
----------------------------
Various configuration of DnD on one page
----------------------------------------
.. literalinclude:: gst_example_with_documentation.xml
Update of html elements, no plotting
------------------------------------
.. literalinclude:: gst_example_html_element_output.xml
Circle with dynamic radius
--------------------------
.. literalinclude:: gst_example_dynamic_range.xml
.. literalinclude:: drag-n-drop-demo.xml