Individual targets with outlines. One draggable per target.
+
Drag ant to first and star to 3rd.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Individual targets WITHOUT outlines. Move Star to the
+ volcano opening, and Label3 on to the right ear of the cow.
+ One draggable per target.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Many draggable per target. Move star and ant to most left target
+ and lable 3 and label 2 to most right target.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Draggables can be places anywhere on base image.
+ Place grass in the middle of the image and ant in the
+ right upper corner.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Please identify the Carbon and Oxygen atoms in the molecule.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/source/drag_and_drop_input.rst b/docs/source/drag_and_drop_input.rst
index d977270269..75e77b97e2 100644
--- a/docs/source/drag_and_drop_input.rst
+++ b/docs/source/drag_and_drop_input.rst
@@ -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::
- BODY
+ ...
-``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::
- - represents jQuery slider
- - represents input
- - 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 ```` where ``id``
-attribute is set.
+draggable tag
+-------------
-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.
-
-``{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 ```` 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 '`` section. However, you don't have to specify a text
-input - they are optional.
-
-You can put only one ```` section. It is not
-required.
-
-NOTE: MathJax, 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
-
-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 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::
-
+ 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::
-
+ 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. ```` 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 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 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::
-
-
-
-
-
-
-``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::
-
-
-
- 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``, 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;
-
-
-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:
-
- 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.
- 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:
- \(cm\)
- \(m\)
+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