From 744b7947e60ea10a5dc78fe7e79ff76bd91ba56a Mon Sep 17 00:00:00 2001 From: Valera Rozuvan Date: Fri, 28 Dec 2012 11:00:55 +0200 Subject: [PATCH] Added initial docs for Drag and Drop. --- docs/source/drag-n-drop-demo.xml | 188 ++++++++++++++ docs/source/drag_and_drop_input.rst | 376 ++++------------------------ 2 files changed, 243 insertions(+), 321 deletions(-) create mode 100644 docs/source/drag-n-drop-demo.xml diff --git a/docs/source/drag-n-drop-demo.xml b/docs/source/drag-n-drop-demo.xml new file mode 100644 index 0000000000..574a188c33 --- /dev/null +++ b/docs/source/drag-n-drop-demo.xml @@ -0,0 +1,188 @@ + + + +

+ Drag and drop pictures to proper positions. +

+

+ Drag images to the cow)). +

+ + + + +

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