From 442e112d6faf7f39fb7e01666ea1b79390a416ec Mon Sep 17 00:00:00 2001 From: Valera Rozuvan Date: Tue, 15 Jan 2013 12:45:07 +0200 Subject: [PATCH] Updated documentation. Try #2. --- docs/source/graphical_slider_tool.rst | 357 +++++++++++++++++----- docs/source/gst_example_bars.rst | 64 ++++ docs/source/gst_example_dynamic_labels | 40 +++ docs/source/gst_example_dynamic_range.xml | 16 +- 4 files changed, 391 insertions(+), 86 deletions(-) create mode 100644 docs/source/gst_example_bars.rst create mode 100644 docs/source/gst_example_dynamic_labels diff --git a/docs/source/graphical_slider_tool.rst b/docs/source/graphical_slider_tool.rst index 6334c6d77e..37b17136e8 100644 --- a/docs/source/graphical_slider_tool.rst +++ b/docs/source/graphical_slider_tool.rst @@ -4,6 +4,7 @@ Xml format of graphical slider tool [xmodule] .. module:: xml_format_gst + Format description ================== @@ -14,101 +15,102 @@ Graphical slider tool (GST) main tag is:: ``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 - - represents input - - represents Flot plot + - 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. +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. +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 ```` section. It is not +You can put only one ```` in the ```` 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 +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. +``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:: -Texbox tag must have ``var`` attribute and optional ``style`` and ``readonly`` -attributes:: + - +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"). -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``. +``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. -``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. Plot tag ........ Plot tag may have optional ``style`` attribute:: - + -After processing plot tags will be replaced by Flot plot with applied +After processing plot tags will be replaced by Flot JS plot with applied ``style`` attribute. -HTML tags with id -................. -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 +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"``:: @@ -121,17 +123,17 @@ and ``output`` value must be ``"element"``:: - Configuration tag ----------------- -The configuration tag contain sparameter settings, graph +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 .............. @@ -143,30 +145,30 @@ Parameters tag -``Var`` attribute links min, max, step and initial values to parameter name. -``Min`` attribute is minimal value that parameter can take. Slider and input +``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 maximal value that parameter can take. Slider and input +``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 +``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. +``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 +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 +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 +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. @@ -175,12 +177,23 @@ 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. +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:: @@ -202,11 +215,11 @@ 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. +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:: @@ -245,43 +258,144 @@ Required parameters:: 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: + - return x * a + b; + Optional parameters:: - color: Color name (red, green, etc.) or in the form of + 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; + 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" 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. + 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, one 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"). + 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". -With ``output`` and ``el_id`` set together you can update html elements with -function value, also function will not be plotted. +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. -[note on MathJax and labels]: +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 ........ @@ -312,6 +426,15 @@ 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 @@ -333,19 +456,89 @@ Optional parameters:: 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/docs/source/gst_example_dynamic_labels b/docs/source/gst_example_dynamic_labels new file mode 100644 index 0000000000..05cbe407fb --- /dev/null +++ b/docs/source/gst_example_dynamic_labels @@ -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/docs/source/gst_example_dynamic_range.xml b/docs/source/gst_example_dynamic_range.xml index 0938e7b60b..0ce4263d62 100644 --- a/docs/source/gst_example_dynamic_range.xml +++ b/docs/source/gst_example_dynamic_range.xml @@ -3,10 +3,10 @@

Graphic slider tool: Dynamic range and implicit functions.

-

You can make x range (not ticks of x axis) of functions to depend on +

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 +

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

@@ -19,18 +19,14 @@ - return Math.sqrt(a * a - x * x); - return -Math.sqrt(a * a - x * x); + Math.sqrt(a * a - x * x) + -Math.sqrt(a * a - x * x) - - return -a; - - - return a; - + -a + a 1000 -30, 6, 30