Skip to content

Instantly share code, notes, and snippets.

@sfentress

sfentress/sparks-authoring.html

Created August 9, 2016 18:32
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save sfentress/05c32dd68d35a167ce75670777b5d190 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save sfentress/05c32dd68d35a167ce75670777b5d190 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
sparks-authoring.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Projects: SPARKS : Breadboard Activity Authoring</title>
<link rel="stylesheet" href="styles/site.css" type="text/css" />
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
<tr>
<td valign="top" class="pagebody">
<div class="pageheader">
<span class="pagetitle">
Projects: SPARKS : Breadboard Activity Authoring
</span>
</div>
<div class="pagesubheading">
This page last changed on Sep 25, 2013 by <font color="#0050B2">phorwitz</font>.
</div>
<p>Our new breadboard activities all support authoring the entire content from an online authoring system.</p>
<p>The authoring database can be found here: <a href="http://couchdb.cosmos.concord.org/_utils/database.html?sparks">http://couchdb.cosmos.concord.org/_utils/database.html?sparks</a></p>
<p>New activity files can be created quickly, and given an id. That id then instantly becomes a url where you can find the activity you have been authoring. This is designed to be a nice, quick, iterative authoring setup.</p>
<p>If you give an activity the id X, it can be found at <a href="http://sparks.portal.concord.org/sparks-content/activities.html#X">http://sparks.portal.concord.org/sparks-content/activities.html#X</a>. So, for example, the activity file with the id series-interpretive, for instance, which can be found here: <a href="http://couchdb.cosmos.concord.org/_utils/document.html?sparks/series-interpretive">http://couchdb.cosmos.concord.org/_utils/document.html?sparks/series-interpretive</a>, will instantly create an activity which can be found at <a href="http://sparks.portal.concord.org/sparks-content/activities.html#series-interpretive">http://sparks.portal.concord.org/sparks-content/activities.html#series-interpretive</a></p>
<p><b>Note:</b> We now can author both "Activities" and "Sections" (or "Levels"). One activity is made up of several sections. Most of the information below is about authoring sections. Authoring activities is described at the bottom of this document.</p>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Table of Contents</b><br /><div>
<ul>
<li><a href='#BreadboardActivityAuthoring-SectionJSONdocuments'>Section JSON documents</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Syntax'>Syntax</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Startinganewsection'>Starting a new section</a></li>
<li><a href='#BreadboardActivityAuthoring-Levelproperties'>Level properties</a></li>
<li><a href='#BreadboardActivityAuthoring-Definingthecircuit'>Defining the circuit</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Anexamplecircuit'>An example circuit</a></li>
<li><a href='#BreadboardActivityAuthoring-Definingthepowersourceinacircuit'>Defining the power source in a circuit</a></li>
<li><a href='#BreadboardActivityAuthoring-Definingfaultsinacircuit'>Defining faults in a circuit</a></li>
<li><a href='#BreadboardActivityAuthoring-ShowingandhidingFlashelements'>Showing and hiding Flash elements</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Images'>Images</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Attachingimagestothedocument'>Attaching images to the document</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Pages'>Pages</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Definingpages'>Defining pages</a></li>
<li><a href='#BreadboardActivityAuthoring-Notes'>Notes</a></li>
<li><a href='#BreadboardActivityAuthoring-Time'>Time</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Questions'>Questions</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Definingquestions'>Defining questions</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Questionproperties'>Question properties</a></li>
<li><a href='#BreadboardActivityAuthoring-Multichoicequestions'>Multi-choice questions</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Calculatedanswerswithcircuitvariables'>Calculated answers with circuit variables</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Units'>Units</a></li>
<li><a href='#BreadboardActivityAuthoring-Moremathfunctions'>More math functions</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Questioncategories'>Question categories</a></li>
<li><a href='#BreadboardActivityAuthoring-Questionscoringscripts'>Question scoring scripts</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Thequestionobject'>The question object</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Thequestionmetaobject'>The question meta object</a></li>
<li><a href='#BreadboardActivityAuthoring-Usingthemultimeterbutton'>Using the multimeter button</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Thelogobject'>The log object</a></li>
<li><a href='#BreadboardActivityAuthoring-Parsingwrittenanswers'>Parsing written answers</a></li>
<li><a href='#BreadboardActivityAuthoring-Otherusefulfunctionsforscripts'>Other useful functions for scripts</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Questionbeforescripts'>Question before scripts</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Generalscriptingtipsandstrategies'>General scripting tips and strategies</a></li>
<ul>
<li><a href='#BreadboardActivityAuthoring-Globalvariables'>Global variables</a></li>
<li><a href='#BreadboardActivityAuthoring-Findingfaults'>Finding faults</a></li>
<li><a href='#BreadboardActivityAuthoring-Loggingtotheconsole'>Logging to the console</a></li>
</ul>
<li><a href='#BreadboardActivityAuthoring-Defininganactivity'>Defining an activity</a></li>
</ul></div></td></tr></table></div>
<h1><a name="BreadboardActivityAuthoring-SectionJSONdocuments"></a>Section JSON documents</h1>
<p>Activity sections (levels) are specified using a JavaScript syntax called JSON. The complete JSON specification can be found at <a href="http://www.json.org/">http://www.json.org/</a>, but here are the basics:</p>
<p>A JSON object is an object that is surrounded by curly braces <tt>{ }</tt> and contains keys and values. Each key must be a string, and each value can be either</p>
<ul>
<li>a primitive (A string, a number or a boolean (true/false)</li>
<li>another JSON object</li>
<li>an array containing any number of these three things (primitives, JSON and arrays), surrounded by square brackets <tt>\[ \]</tt>.</li>
</ul>
<p>as you can see, it can seem a little recursive, as you can have a property which is an array of arrays of JSON objects of arrays... but at the end there will always be primitives.</p>
<h2><a name="BreadboardActivityAuthoring-Syntax"></a>Syntax</h2>
<p>The syntax of JSON is simple, but is also easy to mess up.</p>
<ul>
<li>All strings must be surrounded by quotes. This includes property keys. If a string had quotes within it, use single quotes on the inside</li>
<li>Every value or element of an array must end in a comma, <b>except the last element</b>.<br/>
This last rule may seem strange, but it is for the same reason that we would be confused if someone defined a 3-dimensional location as <tt>(1,5,6,)</tt>. It would appear to be missing the last term.</li>
</ul>
<p>A good syntax check can be found at <a href="http://www.jsonlint.com/">http://www.jsonlint.com/</a></p>
<p>So here we have a legal JSON document (minus the comments, which are not legal):</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
<span class="code-quote">"key1"</span>: <span class="code-quote">"value"</span>, <span class="code-comment">// a string value
</span> <span class="code-quote">"key2"</span>: 2, <span class="code-comment">// a number
</span> <span class="code-quote">"key3"</span>: { <span class="code-comment">// a JSON obeject
</span> <span class="code-quote">"innerkey1"</span>: <span class="code-quote">"value"</span>,
<span class="code-quote">"innerkey2"</span>: <span class="code-quote">"value"</span>
},
<span class="code-quote">"key4"</span>: [ <span class="code-comment">// an array of strings
</span> <span class="code-quote">"array value 1"</span>,
<span class="code-quote">"array value 2"</span>
],
<span class="code-quote">"key5"</span>: [ <span class="code-comment">// an array of JSON objects
</span> {
<span class="code-quote">"innerkey1"</span>: <span class="code-quote">"value"</span>,
<span class="code-quote">"innerkey2"</span>: <span class="code-quote">"value"</span>
},
{
<span class="code-quote">"innerkey1"</span>: <span class="code-quote">"value"</span>,
<span class="code-quote">"innerkey2"</span>: <span class="code-quote">"value"</span> <span class="code-comment">// note lack of trailing commas
</span> }
]
}
</pre>
</div></div>
<h1><a name="BreadboardActivityAuthoring-Startinganewsection"></a>Starting a new section</h1>
<p>To create a new section file in the authoring database, we first create the new database entry, copy-and-paste a bare-bones, syntactically-correct activity, and then add content.</p>
<ol>
<li>Click "New Document" from the top-left of <a href="http://couchdb.cosmos.concord.org/_utils/database.html?sparks">http://couchdb.cosmos.concord.org/_utils/database.html?sparks</a></li>
<li>Modify the id to a useful name. e.g. 'series-interpretive'</li>
<li>Save the document. You will get an error. This is because CouchDB didn't notice you changed the id, and tried to show you a document with the original randomly-generated id. Ignore this annoyance, and return to the main index. You will see your activity.</li>
<li>When you open the document, you will see a new property has been added called "_rev." This is the revision number, and allows CouchDB to keep track of edits. This should not be modified</li>
<li>Paste the following between the &#95;id and the &#95;rev:</li>
</ol>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// {
</span><span class="code-comment">// <span class="code-quote">"_id"</span>: <span class="code-quote">"my-level"</span>,
</span> <span class="code-quote">"title"</span>: <span class="code-quote">"My level"</span>,
<span class="code-quote">"show_multimeter"</span>: <span class="code-quote">"<span class="code-keyword">false</span>"</span>,
<span class="code-quote">"circuit"</span>: [
],
<span class="code-quote">"pages"</span>: [
{
<span class="code-quote">"questions"</span>:
[
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"Question 1"</span>
},
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"Question 2"</span>
}
]
}
],
<span class="code-comment">// <span class="code-quote">"_rev"</span>: <span class="code-quote">"xyz123"</span>
</span><span class="code-comment">// }</span>
</pre>
</div></div>
<p>As you type, clicking off of the document will cause it to validate itself, which is a quick way to know if your syntax is correct.</p>
<p>Save the document. (Save early and often&#33;) Visit it at <a href="http://sparks.portal.concord.org/sparks-content/activities.html#my-level">http://sparks.portal.concord.org/sparks-content/activities.html#my-level</a></p>
<h1><a name="BreadboardActivityAuthoring-Levelproperties"></a>Level properties</h1>
<p>The following is a list of all the top-level properties a level may have. Each property is described in more detail below:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'>&nbsp;</th>
</tr>
<tr>
<th class='confluenceTh'> circuit </th>
<td class='confluenceTd'> The circuit model used in the level </td>
</tr>
<tr>
<th class='confluenceTh'> image </th>
<td class='confluenceTd'> An image displayed above the questions </td>
</tr>
<tr>
<th class='confluenceTh'> pages </th>
<td class='confluenceTd'> The list of pages containing questions and notes </td>
</tr>
<tr>
<th class='confluenceTh'> hide_circuit </th>
<td class='confluenceTd'> See <em>Showing and hiding Flash elements</em> </td>
</tr>
<tr>
<th class='confluenceTh'> show_multimeter </th>
<td class='confluenceTd'> Adds a DMM to the circuit. </td>
</tr>
<tr>
<th class='confluenceTh'> show_oscilloscope </th>
<td class='confluenceTd'> Adds an oscilloscope to the circuit. Only one of the previous two properties may be set. </td>
</tr>
<tr>
<th class='confluenceTh'> showComponentDrawer </th>
<td class='confluenceTd'> Adds a source of movable resistors, capacitors, inductors, and wires. </td>
</tr>
<tr>
<th class='confluenceTh'> allow_move_yellow_probe </th>
<td class='confluenceTd'> Allows the yellow probe that is normally stuck to the positive rail to be moved by the student </td>
</tr>
<tr>
<th class='confluenceTh'> disable_multimeter_position </th>
<td class='confluenceTd'> See <em>Showing and hiding Flash elements</em> </td>
</tr>
<tr>
<th class='confluenceTh'> referenceFrequency </th>
<td class='confluenceTd'> Frequency, in Hz, to be used when calculating inductance or capacitance of reactive components from a desired impedance. </td>
</tr>
</tbody></table>
<h1><a name="BreadboardActivityAuthoring-Definingthecircuit"></a>Defining the circuit</h1>
<p>The circuit is defined as an array of components. Currently we can author resistors, capacitors, inductors, and the power source</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"circuit"</span>: [
{
<span class="code-comment">// component 1
</span> },
{
<span class="code-comment">// component 2
</span> }
]
</pre>
</div></div>
<p>Each component contains a minimum of two properties: a type and a pair of connections. The following is a list of properties that circuit components may have:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Component type </th>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Values </th>
</tr>
<tr>
<th class='confluenceTh'> All </th>
<td class='confluenceTd'> type (required) </td>
<td class='confluenceTd'> wire <br clear="all" />
resistor <br clear="all" /> capacitor <br clear="all" /> inductor <br clear="all" /> battery <br clear="all" /> function generator </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> connections (required) </td>
<td class='confluenceTd'> holeName1,holeName2 <br clear="all" />
e.g. a1,b20 <br clear="all" />
left_positive20,a23 <br clear="all" />
left_negative5,b5 </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> label </td>
<td class='confluenceTd'> A label that will be shown when the user mouses over the component. Max two characters? </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> UID </td>
<td class='confluenceTd'> A unique ID for referring to this component elsewhere </td>
</tr>
<tr>
<th class='confluenceTh'> <b>Resistors</b> </th>
<td class='confluenceTd'> resistance (in ohms) </td>
<td class='confluenceTd'> If specified, the resistor will have this exact resistance. Nominal resistance (to be called rated resistance later) is calculated automatically unless otherwise specified. You can also request a random value using a 3-element array whose first element is the string "uniform". Where possible, a table of "sensible" resistor values (expanded to span the needed orders of magnitude) for the given tolerance will be used, and randomly selected from.
<br clear="all" />
<br clear="all" /> Examples:
<br clear="all" /> <tt>1000</tt> &#8211; resistance should by 1000 Ohm exactly.
<br clear="all" /> <tt>["uniform", 700, 100000]</tt> &#8211; impedance should be a randomly chosen, sensible value between 700 Ohm and 100,000 Ohm. (If the <tt>tolerance</tt> is 0.05, the list of "sensible values" will be 750, 820, 910, 1000, 1110, ..., 82000, 91000 Ohm.) </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> nominalResistance </td>
<td class='confluenceTd'> (To be called ratedResistance.) Rated resistance. If actual resistance (above) is not specified, will be randomly generated within the tolerance of the rated resistance </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> colors </td>
<td class='confluenceTd'> An array of band colors, e.g. <tt>["red","blue","green","gold"]</tt>. Equivalent to specifying nominalResistance </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> tolerance </td>
<td class='confluenceTd'> <em>To be added</em> </td>
</tr>
</tbody></table>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> resistance constrained by other resistors </td>
<td class='confluenceTd'> <em>to be added</em> </td>
</tr>
<tr>
<th class='confluenceTh'> <b>Capacitors</b> </th>
<td class='confluenceTd'> capacitance </td>
<td class='confluenceTd'> The exact capacitance of this capacitor, in Farads. <b>To access this value in a question script, use <tt>.getCapacitance()</tt> rather than <tt>.capacitance</tt></b> </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> impedance </td>
<td class='confluenceTd'> The desired impedance of this capacitor at its <tt>referenceFrequency</tt>, in Ohms. If the <tt>capacitance</tt> property is not set on this capacitor, it will be calculated from the impedance. You can specify an exact value (as a number) or request a random value using a 3-element array whose first element is the string "uniform".
<br clear="all" />
<br clear="all" /> Examples:
<br clear="all" /> <tt>1000</tt> &#8211; impedance should by 1000 Ohm at the <tt>referenceFrequency</tt>
<br clear="all" /> <tt>["uniform", 100, 1000]</tt> &#8211; impedance should be a randomly chosen value between 100 Ohm and 1000 Ohm, at the <tt>referenceFrequency</tt> </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> referenceFrequency </td>
<td class='confluenceTd'> When specifying a desired impedance instead of an exact capacitance value, this is the frequency in Hz at which the capacitor should have that impedance. This property does not need to be explicitly set on the capacitor, as the top-level <tt>referenceFrequency</tt> will be used if not overridden by defining it here. </td>
</tr>
<tr>
<th class='confluenceTh'> <b>Inductors</b> </th>
<td class='confluenceTd'> inductance </td>
<td class='confluenceTd'> The exact inductance of this inductor, in Henries. <b>To access this value in a question script, use <tt>.getInductance()</tt> rather than <tt>.inductance</tt></b> </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> impedance </td>
<td class='confluenceTd'> The desired impedance of this inductor at its <tt>referenceFrequency</tt>, in Ohms. If the <tt>inductance</tt> property is not set on this inductor, it will be calculated from the impedance. You can specify an exact value (as a number) or request a random value using a 3-element array whose first element is the string "uniform".
<br clear="all" />
<br clear="all" /> Examples:
<br clear="all" /> <tt>1000</tt> &#8211; impedance should by 1000 Ohm at the <tt>referenceFrequency</tt>
<br clear="all" /> <tt>["uniform", 100, 1000]</tt> &#8211; impedance should be a randomly chosen value between 100 Ohm and 1000 Ohm, at the <tt>referenceFrequency</tt> </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> referenceFrequency </td>
<td class='confluenceTd'> When specifying a desired impedance instead of an exact inductance value, this is the frequency in Hz at which the inductor should have that impedance. This property does not need to be explicitly set on the inductor, as the top-level <tt>referenceFrequency</tt> will be used if not overridden by defining it here. </td>
</tr>
<tr>
<th class='confluenceTh'> <b>Batteries</b> </th>
<td class='confluenceTd'> voltage (in volts) </td>
<td class='confluenceTd'> Can be either a specific voltage, or a range. A range is specified as an array. E.g.: <br clear="all" /> 9 <br clear="all" /> <tt>[8.0, 9.1]</tt> <em>-- A random voltage selected between these 8V and 9.1V</em> <br clear="all" /> <br clear="all" /> <b>Note:</b> See the section <em>Defining the power source in a circuit</em> for usage </td>
</tr>
<tr>
<th class='confluenceTh'> <b>Function generators</b> </th>
<td class='confluenceTd'> amplitude </td>
<td class='confluenceTd'> The peak amplitude, in volts. Can be a plain number or an array representing a range of values. Examples <br clear="all" /> <tt>10</tt> <em>-- A single peak amplitude of 10V</em> <br clear="all" /> <tt>[0, 10]</tt> <em>-- A range of amplitudes from 0 to 10V, initially set at 5V (halfway)</em> <br clear="all" /> <tt>[10, 100, 20]</tt> <em>-- A range from 10 to 100V, initially set at 20V</em></td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> frequencies </td>
<td class='confluenceTd'> An array representing a set of possible frequencies that the generator can produce. Examples: <br clear="all" /> <tt>[1000]</tt> <em>-- A single frequency of 1KHz. Note that it must be an array</em> <br clear="all" /> <tt>[1000, 2000, 5000]</tt> <em>three possible frequencies</em> <br clear="all" /> <tt>["linear", 1000, 10000, 5]</tt> <em>-- A range of frequencies from 1 KHz to 10 KHz, in 5 linear increments</em> <br clear="all" /> <tt>["logarithmic", 1000, 1e6, 20]</tt> <em>-- A range of frequencies from 1 KHz to 1 MHz, in 20 logarithmic increments</em> <br clear="all" /> <br clear="all" /> <b>Note:</b> See the section <em>Defining the power source in a circuit</em> for usage </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> initialFrequency </td>
<td class='confluenceTd'> <em>Optional.</em> The initial frequency setting of the function generator. If this value is set, the frequency generator will initially be set to that frequency, in the set of frequencies specified by <tt>frequencies</tt>, that is closest to <tt>initialFrequency</tt> </td>
</tr>
</tbody></table>
<h2><a name="BreadboardActivityAuthoring-Anexamplecircuit"></a>An example circuit</h2>
<p>The following in an example circuit with three resistors in series. This example should help see how to use the list of properties defined above to create your own circuits:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"circuit"</span>: [
{
<span class="code-quote">"type"</span>: <span class="code-quote">"wire"</span>, <span class="code-comment">// the type of <span class="code-keyword">this</span> first component, in <span class="code-keyword">this</span> <span class="code-keyword">case</span> a wire
</span> <span class="code-quote">"connections"</span>: <span class="code-quote">"left_positive20,a23"</span> <span class="code-comment">// the holes <span class="code-keyword">this</span> component connects to
</span> },
{
<span class="code-quote">"type"</span>: <span class="code-quote">"resistor"</span>, <span class="code-comment">// a second component, <span class="code-keyword">this</span> time the type is <span class="code-quote">"resistor"</span>
</span> <span class="code-quote">"UID"</span>: <span class="code-quote">"r1"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"b23,b17"</span>,
<span class="code-quote">"label"</span>: <span class="code-quote">"R1"</span>,
<span class="code-quote">"resistance"</span>: 2000 <span class="code-comment">// here the author is specifying the actual resistance.
</span> },
{
<span class="code-quote">"type"</span>: <span class="code-quote">"resistor"</span>,
<span class="code-quote">"UID"</span>: <span class="code-quote">"r2"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"c17,c11"</span>,
<span class="code-quote">"label"</span>: <span class="code-quote">"R2"</span>,
<span class="code-quote">"nominalResistance"</span>: 1000 <span class="code-comment">// here the author has chosen to specify the nominal resistance (colors)
</span> },
{
<span class="code-quote">"type"</span>: <span class="code-quote">"resistor"</span>, <span class="code-comment">// neither resistance nor nominalResistance has been specified here, so it will be randomized
</span> <span class="code-quote">"UID"</span>: <span class="code-quote">"r3"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"d11,d5"</span>,
<span class="code-quote">"label"</span>: <span class="code-quote">"R3"</span>
},
{
<span class="code-quote">"type"</span>: <span class="code-quote">"wire"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"left_negative3,a5"</span>
}
]
</pre>
</div></div>
<h2><a name="BreadboardActivityAuthoring-Definingthepowersourceinacircuit"></a>Defining the power source in a circuit</h2>
<p>An author can set the power source of a circuit to be either a DC battery or an AC function generator using the "battery" or "function generator" components defined in the components table above. In order for the application to understand that this component is being designated as the primary power source (connected to the power rails), this component must be given the UID <b>"source"</b>.</p>
<p>Any circuits created without a power source with the UID "source" are given a default 9V battery as their source.</p>
<p>A power source is added to a circuit just like any other component. However, as it is assumed to be connected to the power rails, it does not need to specify its connections. See the components table above to see all the properties a battery or function generator may have.</p>
<p>Examples:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"circuit"</span>: [
{
<span class="code-quote">"type"</span>: <span class="code-quote">"battery"</span>, <span class="code-comment">// adding a battery as the breadboard power source
</span> <span class="code-quote">"UID"</span>: <span class="code-quote">"source"</span>, <span class="code-comment">// we *must* define the UID as <span class="code-quote">"source"</span>
</span> <span class="code-quote">"voltage"</span>: [8.5, 9] <span class="code-comment">// setting the voltage to be between 8.5 and 9 (random)
</span> },
{
<span class="code-quote">"type"</span>: <span class="code-quote">"wire"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"left_positive20,a23"</span>
},
{
<span class="code-quote">"type"</span>: <span class="code-quote">"resistor"</span>,
<span class="code-quote">"UID"</span>: <span class="code-quote">"r1"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"b23,b17"</span>,
<span class="code-quote">"label"</span>: <span class="code-quote">"R1"</span>,
<span class="code-quote">"resistance"</span>: 2000
},
{
<span class="code-quote">"type"</span>: <span class="code-quote">"wire"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"left_negative3,a5"</span>
}
]
</pre>
</div></div>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"circuit"</span>: [
{
<span class="code-quote">"type"</span>: <span class="code-quote">"function generator"</span>, <span class="code-comment">// adding an AC function generator as the breadboard power source
</span> <span class="code-quote">"UID"</span>: <span class="code-quote">"source"</span>,
<span class="code-quote">"amplitude"</span>: 10, <span class="code-comment">// 10V peak amplitude
</span> <span class="code-quote">"frequencies"</span>: [1000] <span class="code-comment">// the frequencies array with only a single value specified
</span> },
{
<span class="code-quote">"type"</span>: <span class="code-quote">"wire"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"left_positive20,a23"</span>
},
{
<span class="code-quote">"type"</span>: <span class="code-quote">"resistor"</span>,
<span class="code-quote">"UID"</span>: <span class="code-quote">"r1"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"b23,b17"</span>,
<span class="code-quote">"label"</span>: <span class="code-quote">"R1"</span>,
<span class="code-quote">"resistance"</span>: 2000
},
{
<span class="code-quote">"type"</span>: <span class="code-quote">"wire"</span>,
<span class="code-quote">"connections"</span>: <span class="code-quote">"left_negative3,a5"</span>
}
]
</pre>
</div></div>
<p>Note: Batteries and function generators are "first-class components" which, like resistors or capacitors, could theoretically be added to the circuit anywhere by an author. This is not recommended, however, as there is no visual representation of batteries or function generators in Flash, besides the one attached to the rails.</p>
<h2><a name="BreadboardActivityAuthoring-Definingfaultsinacircuit"></a>Defining faults in a circuit</h2>
<p>SPARKS contains a very generalizable system for creating faults in a circuit. An author can</p>
<ul>
<li>specify specific faults for specific components</li>
<li>specify specific faults for any number of randomly-selected components</li>
<li>specify specific faults for any random number of components (up to an authored max)</li>
<li>specify random faults for any of the above (i.e. picking a random fault for each resistor)</li>
</ul>
<p>Currently this system is limited to creating "open" or "shorted" faults on resistors (max resistance and min (shorted) resistance respectively). However, the system is flexible enough that as we come up with new ways to break the circuit we can add them in easily to the same system.</p>
<p>Faults are defined in a new "faults" array, typically defined right after the circuit definition. The application always creates the circuit first, generating appropriate resistor values etc., and then applies the faults.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"circuit"</span>: [...],
<span class="code-quote">"faults"</span>: [...],
</pre>
</div></div>
<p>Examples in this case may be quicker to understand than a property table. The property table is below, but here are some example faults:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// creates an <span class="code-quote">"open"</span> fault on R1 and a <span class="code-quote">"shorted"</span> fault on R2
</span><span class="code-quote">"faults"</span>: [
{
<span class="code-quote">"type"</span>: <span class="code-quote">"open"</span>,
<span class="code-quote">"component"</span>: <span class="code-quote">"r1"</span>
},
{
<span class="code-quote">"type"</span>: <span class="code-quote">"shorted"</span>,
<span class="code-quote">"component"</span>: <span class="code-quote">"r2"</span>
}
]
</pre>
</div></div>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// creates an <span class="code-quote">"open"</span> fault on one random resistor
</span><span class="code-quote">"faults"</span>: [
{
<span class="code-quote">"type"</span>: <span class="code-quote">"open"</span>,
<span class="code-quote">"count"</span>: 1
}
]
</pre>
</div></div>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// creates faults on two random resistors, randomly choosing <span class="code-quote">"open"</span> or <span class="code-quote">"shorted"</span> <span class="code-keyword">for</span> each
</span><span class="code-quote">"faults"</span>: [
{
<span class="code-quote">"type"</span>: [<span class="code-quote">"open"</span>, <span class="code-quote">"shorted"</span>],
<span class="code-quote">"count"</span>: 2
}
]
</pre>
</div></div>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// creates a shorted fault on anywhere from 1 to 5 resistors, and an
</span><span class="code-comment">// open fault on R2
</span><span class="code-quote">"faults"</span>: [
{
<span class="code-quote">"type"</span>: <span class="code-quote">"shorted"</span>,
<span class="code-quote">"max"</span>: 5
},
{
<span class="code-quote">"type"</span>: <span class="code-quote">"open"</span>,
<span class="code-quote">"component"</span>: <span class="code-quote">"r2"</span>
}
]
</pre>
</div></div>
<p>As you can see, you can have multiple faults defined, and each fault can affect multiple resistors.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Meaning </th>
<th class='confluenceTh'> Possible values </th>
</tr>
<tr>
<th class='confluenceTh'> type </th>
<td class='confluenceTd'> Type of fault </td>
<td class='confluenceTd'> "open", "shorted" </td>
</tr>
<tr>
<th class='confluenceTh'>&nbsp;</th>
<td class='confluenceTd'> Array of any of the above. Randomly chooses from the array independently for each component </td>
<td class='confluenceTd'> <tt>\[...\]</tt> </td>
</tr>
<tr>
<th class='confluenceTh'> component </th>
<td class='confluenceTd'> Specific component to apply this to </td>
<td class='confluenceTd'> "r1" etc. </td>
</tr>
<tr>
<th class='confluenceTh'> count </th>
<td class='confluenceTd'> Number of components to apply this to. Specific components will be randomly chosen </td>
<td class='confluenceTd'> 1&#43; </td>
</tr>
<tr>
<th class='confluenceTh'> max </th>
<td class='confluenceTd'> Maximum number of components to apply this to, randomly chosen between 1 and max </td>
<td class='confluenceTd'> 1&#43; </td>
</tr>
</tbody></table>
<h2><a name="BreadboardActivityAuthoring-ShowingandhidingFlashelements"></a>Showing and hiding Flash elements</h2>
<p>The circuit as defined above represents the underlying <em>Javascript model</em> of the circuit. Typically, this will then be rendered by Flash and displayed to the student, along with a DMM. However, there are certain section-level properties that can control what the student sees:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Meaning </th>
<th class='confluenceTh'> Possible values, default if not specified </th>
</tr>
<tr>
<th class='confluenceTh'> hide_circuit </th>
<td class='confluenceTd'> If <b>true</b>, Flash circuit will not appear </td>
<td class='confluenceTd'> true, false (Default=false) </td>
</tr>
<tr>
<th class='confluenceTh'> show_multimeter </th>
<td class='confluenceTd'> If <b>true</b>, DMM is available for the student </td>
<td class='confluenceTd'> true, false (Default=false) </td>
</tr>
<tr>
<th class='confluenceTh'> show_oscilloscope </th>
<td class='confluenceTd'> If <b>true</b>, the oscilloscope is available for the student. (Cannot be combined with the above) </td>
<td class='confluenceTd'> true, false (Default=false) </td>
</tr>
<tr>
<th class='confluenceTh'> disable_multimeter_position </th>
<td class='confluenceTd'> Section of the DMM to be disabled </td>
<td class='confluenceTd'> Any one of "r,dcv,acv,dca,diode,hfe,c_10a,p_9v" (Default=none) </td>
</tr>
</tbody></table>
<h1><a name="BreadboardActivityAuthoring-Images"></a>Images</h1>
<p>Images can be references in two places: at the section level, and at the question level.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
<span class="code-quote">"title"</span>: <span class="code-quote">"My level"</span>,
<span class="code-quote">"image"</span>: <span class="code-quote">"http:<span class="code-comment">//..."</span>, // <span class="code-keyword">this</span> image will be at the top of every page
</span> <span class="code-quote">"pages"</span>: [
{
<span class="code-quote">"questions"</span>:
[
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"Question 1"</span>
},
{
<span class="code-quote">"image"</span>: <span class="code-quote">"http:<span class="code-comment">//..."</span>, // <span class="code-keyword">this</span> image will be displayed above <span class="code-keyword">this</span> question
</span> <span class="code-quote">"prompt"</span>: <span class="code-quote">"Question 2"</span>
}
]
}
],
}
</pre>
</div></div>
<h2><a name="BreadboardActivityAuthoring-Attachingimagestothedocument"></a>Attaching images to the document</h2>
<p>Images can be attached directly to the authoring document in CouchDB, and then referenced by name only. This makes it very easy to add new images.</p>
<ol>
<li>Give your file an easy-to-understand name. We'll assume "series-circuit.jpg"</li>
<li>From the CouchDB authoring page, click the <b>Upload attachment</b> link at the top</li>
<li>Select the file and upload it.</li>
<li>Refer to the image in the document by its name, e.g. "series-circuit.jpg"</li>
</ol>
<h1><a name="BreadboardActivityAuthoring-Pages"></a>Pages</h1>
<p>A single Sparks section consists of one circuit (or main image) and several internal "pages" of questions. Each page consists of a few questions, and as the student moves through each page within a section the main circuit will stay the same.</p>
<p>After a student completes a page, they immediately have their answers graded, and they see a mini-report of the questions on that page. At this point, they have the option of moving on to the next page (or section), or repeating the page again.</p>
<p>If they choose to repeat the page, the circuit will reload, and may contain new values for resistors or other components. This new circuit will also be used for any subsequent pages (unless the student chooses to repeat yet again).</p>
<h2><a name="BreadboardActivityAuthoring-Definingpages"></a>Defining pages</h2>
<p>Pages are defined in an <b>array</b>, and each page is a <b>JSON object</b> containing questions, optional notes for the student, and optional points for time.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"pages"</span>: [
{ <span class="code-comment">// page 1
</span> <span class="code-quote">"questions"</span>: [
{
<span class="code-comment">//question 1
</span> },
{
<span class="code-comment">//question 2
</span> }
],
<span class="code-quote">"notes"</span>: <span class="code-quote">"This message will appear on <span class="code-keyword">this</span> page <span class="code-keyword">for</span> students"</span>
<span class="code-quote">"time"</span>: { ... } <span class="code-comment">// see below
</span> },
{ <span class="code-comment">// page 2
</span> <span class="code-quote">"questions"</span>: [
{
<span class="code-comment">//question 1
</span> },
{
<span class="code-comment">//question 2
</span> }
],
<span class="code-quote">"notes"</span>: <span class="code-quote">"This message will appear on <span class="code-keyword">this</span> page <span class="code-keyword">for</span> students after they turn the page"</span>
}
]
</pre>
</div></div>
<p>Note that even if you only wish to have one page of questions, it is still necessary to define the array of pages - the array would just have one page in it. An example of a one-page level can be found in the section <b>Starting a new section</b> above.</p>
<h2><a name="BreadboardActivityAuthoring-Notes"></a>Notes</h2>
<p>Anything in the "notes" property of the page will show up in a box to the right of the questions (we can play with layout later if necessary). Notes can contain any plain text, HTML, and will also perform circuit calculations, to allow authors to use variables from the current circuit. For information on using calculations, please see the section <b>Calculated answers with circuit variables</b> below.</p>
<p>Example note:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"note"</span>: <span class="code-quote">"The value of R1 is [${r1.nominalResistance}] ohms. &lt;br/&gt; The value of R2 is [${r2.nominalResistance}] ohms."</span>
</pre>
</div></div>
<h2><a name="BreadboardActivityAuthoring-Time"></a>Time</h2>
<p>An author can specify that a student should gain points for completing a page in a certain amount of time. The author can specify the "best" time to complete it in, in which case they score full points, and the "worst" time to complete it in, in which case they score zero bonus points. The points decline linearly between the two times.</p>
<p>Example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"time"</span>: {
<span class="code-quote">"best"</span>: 60,
<span class="code-quote">"worst"</span>: 120,
<span class="code-quote">"points"</span>: 5
}
</pre>
</div></div>
<h1><a name="BreadboardActivityAuthoring-Questions"></a>Questions</h1>
<p>Each page contains an array of questions. All questions (at the moment) are automatically graded as soon as a student submits their answer, and are tabulated in a report at the end of each page.</p>
<p>Most questions have a specific "correct" answer. In multiple-choice questions, this correct answer is defined <em>implicitly</em> by the score assigned to that response. For an open-response question, the correct answer must be defined <em>explicitly</em> in the question.</p>
<h2><a name="BreadboardActivityAuthoring-Definingquestions"></a>Defining questions</h2>
<p>The questions definition is an <em>array</em> of questions, and each question may optionally contain an <em>array</em> of subquestions.</p>
<p>The example below shows the syntax using plain open-response questions (which are simpler) for clarity.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"questions"</span>: [
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the answer to question 1?"</span>,
<span class="code-quote">"correct_answer"</span>: <span class="code-quote">"The answer"</span>
},
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the answer to"</span>,
<span class="code-quote">"subquestions"</span>: [
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"question 2?"</span>,
<span class="code-quote">"correct_answer"</span>: <span class="code-quote">"Answer 2"</span>
},
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"question 3?"</span>,
<span class="code-quote">"correct_answer"</span>: <span class="code-quote">"Answer 3"</span>
}
]
},
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the answer to question 4?"</span>,
<span class="code-quote">"correct_answer"</span>: <span class="code-quote">"The answer"</span>,
<span class="code-quote">"category"</span>: <span class="code-quote">"Questions about the number 4"</span>
}
]
</pre>
</div></div>
<p>Each "subquestion" is actually a unique question, and is graded as if it were its own question. Visually, however, a subquestion is nested under an outer prompt, and a group of subquestions has only one submit button. So the page above would look like</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>1. What is the answer to question 1? [________] {submit}
2. What is the answer to
question 2? [________]
question 3? [________] {submit}
3. What is the answer to question 4? [________] {submit}
</pre>
</div></div>
<h3><a name="BreadboardActivityAuthoring-Questionproperties"></a>Question properties</h3>
<p>By default, all questions are open-response. That is, if the only thing specified is a prompt, the question will be styled with an input box after the prompt. The two bottom properties in this list are only used if no "options" are set, and will be ignored for multiple-choice questions.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Object </th>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Values </th>
</tr>
<tr>
<th class='confluenceTh'> Question </th>
<td class='confluenceTd'> prompt (required) </td>
<td class='confluenceTd'> The question being asked </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> shortPrompt </td>
<td class='confluenceTd'> An optional summary of the prompt for use in reports. Particularly useful for subquestions, where a subquestion prompt may be nothing more than "R1?," the shortPrompt could be "Resistance of R1." </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> options </td>
<td class='confluenceTd'> A list of options, containing the choices and the points and feedback associated with each choice. Described below. </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> radio/checkbox/ keepOrder </td>
<td class='confluenceTd'> <b>Only for multiple-choice questions</b>. Described below. </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> correct_units </td>
<td class='confluenceTd'> If specified, a units pull-down will appear. Note, only the "unit type" needs to be specified, e.g. 'V', 'A', 'ohms.' More on units below. </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> tutorial </td>
<td class='confluenceTd'> A link to the appropriate tutorial: a button will show in the report table if the question is answered incorrectly </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> correct_answer </td>
<td class='confluenceTd'> <b>Only for open-response questions</b>. If a correct answer is specified, an exact match will be scored as correct. </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> points </td>
<td class='confluenceTd'> <b>Only for open-response questions</b>. Max points for this question, given to student if answer is correct </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> category </td>
<td class='confluenceTd'> <b>deprecated</b> Marks the question as being a member of a category, for reporting back to the student and teacher. <b>NOTE</b>: Now just setting the tutorial will automatically set the category </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> show_read_multimeter_button </td>
<td class='confluenceTd'> Adds a "read multimeter" button, instead of a text box, that reads the multimeter into the answer box. If the circuit is an AC circuit, the frequency and amplitude of the source are additionally (but invisibly) recorded as part of the answer and are available to question scripts; see below. </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> scoring </td>
<td class='confluenceTd'> A script used to grade a question and provide feedback. See <b>Question scoring scripts</b> below </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> beforeScript </td>
<td class='confluenceTd'> A script run when the question is first enabled. See <b>Question before scripts</b> below </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> meta </td>
<td class='confluenceTd'> An object that may contain more information about the answer for author scripts. Not settable by author, it is instead filled when a user answers a question. See <b>The question meta object</b> below </td>
</tr>
</tbody></table>
<h3><a name="BreadboardActivityAuthoring-Multichoicequestions"></a>Multi-choice questions</h3>
<p>Multi-choice questions have the advantage of being easier to score and easier to provide feedback for. Since we make it possible to provide partial credit, each possible answer can have points specified. In a report, the answer is shown as being correct if it is the answer with the highest possible points.</p>
<p>Each option is a JSON object with the option, optional feedback for picking that option, and optional points for picking that option.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Object </th>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Values </th>
</tr>
<tr>
<th class='confluenceTh'> Question </th>
<td class='confluenceTd'> options </td>
<td class='confluenceTd'> An array of options </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> radio </td>
<td class='confluenceTd'> if "true," question will shown as radio buttons. If omitted, options will be pull-down list. </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> checkbox </td>
<td class='confluenceTd'> if "true," question will shown as check boxes (multichoice). If omitted, options will be pull-down list. </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> keepOrder </td>
<td class='confluenceTd'> the order of the options is randomized by default. If keepOrder is true, the order will not be randomized </td>
</tr>
<tr>
<th class='confluenceTh'> Options </th>
<td class='confluenceTd'> option </td>
<td class='confluenceTd'> The option the student sees </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> points </td>
<td class='confluenceTd'> Points given to the student for answering that option. Zero if omitted </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> feedback </td>
<td class='confluenceTd'> Feedback shown to the student for answering that option. Nothing if omitted </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> tutorial </td>
<td class='confluenceTd'> Overrides the "tutorial" specified at the question-level for this option </td>
</tr>
</tbody></table>
<p>Example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the answer?"</span>,
<span class="code-quote">"options"</span>: [
{
<span class="code-quote">"option"</span>: <span class="code-quote">"A"</span>,
<span class="code-quote">"points"</span>: 5, <span class="code-comment">// maximum points, so <span class="code-keyword">this</span> answer is considered correct
</span> <span class="code-quote">"feedback"</span>: <span class="code-quote">"Good job!"</span>
},
{
<span class="code-quote">"option"</span>: <span class="code-quote">"B"</span>,
<span class="code-quote">"points"</span>: 1,
<span class="code-quote">"feedback"</span>: <span class="code-quote">"That's not quite right..."</span>
},
{
<span class="code-quote">"option"</span>: <span class="code-quote">"C"</span>,
<span class="code-quote">"feedback"</span>: <span class="code-quote">"Did you even read the material?"</span>,
<span class="code-quote">"tutorial"</span>: <span class="code-quote">"finding_the_answer.html"</span>
}
]
}
</pre>
</div></div>
<h2><a name="BreadboardActivityAuthoring-Calculatedanswerswithcircuitvariables"></a>Calculated answers with circuit variables</h2>
<p>Often you want an answer to use the values of the components in the specific circuit the user is viewing. For this purpose, we have a special calculation syntax that can be used both as a multi-choice option and as a correct_answer.</p>
<p>Anything in square brackets <tt>\[ \]</tt> will be run through the script parser. A script can be a simple calculation. So</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"option"</span>: <span class="code-quote">"Ten is [5*2]"</span>
</pre>
</div></div>
<p>Will be displayed as "Ten is 10." Likewise, <tt>"correct_answer": "\[(5/2) * 10\]"</tt> will score a question correct only if the student answers "25".</p>
<p><b>Circuit variables</b> are accessed in the script simply by referring to the component's UID. Each component in the circuit is accessible in the script, along with all it's properties: <tt>uuid.property</tt>. Again, it must by between square brackets <tt>\[ \]</tt> to be processed be the script parse. So</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"option"</span>: <span class="code-quote">"[r1.resistance]"</span>
</pre>
</div></div>
<p>will display the resistance of r1. Similarly, "<tt>r2.nominalResistance</tt>" would give you the nominalResistance of r2. Any numerical property from the circuit component properties defined above may be used.</p>
<p>Math and variables can be freely mixed: variables will be converted and treated as numbers. So "<tt>\[2 * r2.nominalResistance\]</tt>" will give you twice the nominal resistance of r2.</p>
<p>The code between square brackets <tt>\[ \]</tt> can, in fact, be a complete script. See more about this in the <b>Scripting</b> section below.</p>
<h3><a name="BreadboardActivityAuthoring-Units"></a>Units</h3>
<p>Adding a unit such as "V", "A" or "ohms" to the end of an option or correct_answer will immediately cause the value to be converted to engineering format.</p>
<p>So if you specify</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"option"</span>: <span class="code-quote">"[r1.resistance] ohms"</span>
</pre>
</div></div>
<p>The value will be displayed in ohms if the number is between 0 - 1000, kiloohms if the number is between 10^3 - 10^6, etc.</p>
<p>Note: for now this is the default. If we have a reason that the author needs to show "10,000 ohms" in the dropdown box, we can make this an option. For now, if the author specifies 10000 ohms as an option, it will be automatically converted to 10 kiloohms.</p>
<h3><a name="BreadboardActivityAuthoring-Moremathfunctions"></a>More math functions</h3>
<p>The parsing code (which parses everything in an answer between square brackets <tt>\[ \]</tt>) has access to the entire JavaScript library, including the JavaScript Math object: <a href="http://www.w3schools.com/jsref/jsref_obj_math.asp">http://www.w3schools.com/jsref/jsref_obj_math.asp</a>. The Math object has been extended with a couple other useful functions, <tt>Math.log10(x)</tt> and <tt>Math.powNdigits(x,n)</tt>.</p>
<p>Some other useful functions include <tt>Math.max(a,b,c...)</tt> to return the maximum of <em>n</em> values, <tt>Math.round(a)</tt> to round a value to the nearest integer, and <tt>Math.random()</tt> to get a random floating-point number between 0 and 1.</p>
<p>Some examples of this in use:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"option"</span>: <span class="code-quote">"[<span class="code-object">Math</span>.max(r1.resistance,r2.resistance)] ohms"</span> <span class="code-comment">// <span class="code-keyword">if</span> r1=100 and r2=200, <span class="code-keyword">this</span> statement would resolve to <span class="code-quote">"200 ohms"</span>
</span> <span class="code-quote">"option"</span>: <span class="code-quote">"[<span class="code-object">Math</span>.round(100 * <span class="code-object">Math</span>.random())]"</span> <span class="code-comment">// returns a random integer between 0 and 100
</span> <span class="code-quote">"option"</span>: <span class="code-quote">"[r1.resistance * <span class="code-object">Math</span>.sqrt(r2.resistance)]"</span> <span class="code-comment">// returns r1 times the square root of r2 (who knows why...)
</span> <span class="code-quote">"option"</span>: <span class="code-quote">"[<span class="code-object">Math</span>.ceil(<span class="code-object">Math</span>.log10(r1.resistance))]"</span> <span class="code-comment">// the number of digits in the resistance of r1 (<span class="code-object">Math</span>.ceil rounds up)</span>
</pre>
</div></div>
<p>Some math functions were added to Sparks that would be particularly helpful to authors:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">Math</span>.log10(x)
<span class="code-object">Math</span>.powNdigits(x,n) -- not really sure what that does. It's equivalent to: <span class="code-object">Math</span>.pow(10,<span class="code-object">Math</span>.floor(<span class="code-object">Math</span>.log(x)/<span class="code-object">Math</span>.LN10-n+1))
<span class="code-comment">// The following use the cMath (circuit <span class="code-object">Math</span>) object <span class="code-keyword">for</span> dealing with circuit variables
</span>cMath.rSeries(x,y,z,...) <span class="code-comment">// will calculate the series resistance of the named resistors. So cMath.rSeries(<span class="code-quote">"r1"</span>,<span class="code-quote">"r2"</span>) will add the resistances of r1 and r2. You can have unlimited named resistors
</span>cMath.rParallel(x,y,z,...) <span class="code-comment">// will calculate the parallel resistance of the named resistors.
</span>cMath.rNominalSeries(x,y,z...)
cMath.rNominalParallel(x,y,z...) <span class="code-comment">// will <span class="code-keyword">do</span> the same <span class="code-keyword">for</span> the nominal resistances
</span>cMath.vDiv(x,y) <span class="code-comment">// will calculate the proportion of the voltage across resistor x, <span class="code-keyword">if</span> x and y are in series.</span>
</pre>
</div></div>
<h2><a name="BreadboardActivityAuthoring-Questioncategories"></a>Question categories</h2>
<p>All questions can have categories assigned to them. The reports that are shown to a student will show the student the percentage of questions in these categories they have answered correctly. Unlike the regular scoring, these percentages take into account questions answered incorrectly, so if a student answers an "Understanding breadboards" question incorrectly on page 1, and then repeats the page and gets it right, the table will show them as having answered 50% of "Understanding breadboards" questions correctly.</p>
<p>Note that categories are just strings, and if two such string differ, even just by case, then they will be counted as two different categories.</p>
<p>Example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"questions"</span>: [
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the answer to question 1?"</span>,
<span class="code-quote">"correct_answer"</span>: <span class="code-quote">"The answer"</span>,
<span class="code-quote">"category"</span>: <span class="code-quote">"Intro questions"</span>
},
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the answer to question 2?"</span>,
<span class="code-quote">"correct_answer"</span>: <span class="code-quote">"The answer"</span>,
<span class="code-quote">"category"</span>: <span class="code-quote">"Hard questions"</span>
}
]
</pre>
</div></div>
<h2><a name="BreadboardActivityAuthoring-Questionscoringscripts"></a>Question scoring scripts</h2>
<p>All questions can use authored scripts to score answers, instead of relying on the Sparks application's inbuilt scoring system (i.e. "correct_answer" and point values for options). If a question contains a script, the script will be run when the report is generated and no other scoring or processing will be done. This means that it is up to the author to manually set the student's score, the correct answer, tutorial buttons etc, from within the script.</p>
<p>Scripts are written in JavaScript, and are added to the "scoring" property of a question.</p>
<p><b>A very simple script:</b></p>
<p>Here is a trivial script which an author would never use (as it could be done by other means), but should be illustrative of the script style.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is 1 + 1?"</span>,
<span class="code-quote">"points"</span>: 10,
<span class="code-quote">"scoring"</span>: <span class="code-quote">"<span class="code-keyword">if</span> (question.answer == 2) {question.points_earned = 10}"</span>
}
</pre>
</div></div>
<p>Here we see three things:</p>
<ul>
<li>The script has access to the <b>question</b> object, which is defined below. Furthermore, the question object has already had it's "answer" property (i.e. the student's answer) set by the system, so it can use it to score points.</li>
<li>The script can set properties on the question object, such as the points_earned. This will be the score the student earns.</li>
<li>If the points_earned is equal to (or greater than) the point-value of the question (set above the script), the question will be considered correct.</li>
</ul>
<p><b>Access to the circuit</b></p>
<p>Along with the question object, the script also has access to the circuit, using the same r1, r2 variables defined earlier. Using this, we can modify our question above:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the rated resistance of R1?"</span>,
<span class="code-quote">"points"</span>: 10,
<span class="code-quote">"scoring"</span>: <span class="code-quote">"<span class="code-keyword">if</span> (question.answer == r1.nominalResistance) {question.points_earned = 10}"</span>
}
</pre>
</div></div>
<p>Again, this isn't a script that an author would probably write, as there are simpler ways of scoring this simple question.</p>
<p>Finally, multiple-choice questions can be treated exactly the same way as the open-response questions above. question.answer will simply be set to whatever answer they picked (as a string). Using this, we can create a very simple script for a basic faulty circuit question:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"One of these resistors is faulty and is allowing no current through it. Using the fewest number of measurements, can you work out which it is?"</span>,
<span class="code-quote">"points"</span>: <span class="code-quote">"10"</span>,
<span class="code-quote">"options"</span>: [
{
<span class="code-quote">"option"</span>: <span class="code-quote">"R1"</span>
},
{
<span class="code-quote">"option"</span>: <span class="code-quote">"R2"</span>
},
{
<span class="code-quote">"option"</span>: <span class="code-quote">"R3"</span>
},
{
<span class="code-quote">"option"</span>: <span class="code-quote">"R4"</span>
}
],
<span class="code-quote">"keepOrder"</span>: <span class="code-keyword">true</span>,
<span class="code-quote">"scoring"</span>: <span class="code-quote">"<span class="code-keyword">if</span> (question.answer.toLowerCase() === breadboard.getFault().UID) {question.points_earned = 10} question.correct_answer = breadboard.getFault().UID"</span>
}
</pre>
</div></div>
<p>the script is, unfortunately, all on one line. To make it easier to follow, I will reproduce it with more typical line spacing:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> (question.answer.toLowerCase() === breadboard.getFault().UID) { <span class="code-comment">// check <span class="code-keyword">if</span> the student got the answer right
</span> question.points_earned = 10 <span class="code-comment">// <span class="code-keyword">if</span> so, award full marks
</span>}
question.correct_answer = breadboard.getFault().UID <span class="code-comment">// set correct_answer, so that <span class="code-keyword">this</span> shows up in the student's report</span>
</pre>
</div></div>
<p>Here, we create a variable called badResistorName. We then set this variable to "R1" if the bad resistor is r1, etc. Finally, we check to see if the student's answer was the badResistorName, and, if so, award full points. (If we do not set points_earned, it will be zero. In this case, if question.answer is not equals to badResistorName, no points will be earned.) We also set question.correct_answer to be the badResistorName.</p>
<p>Of course, there were numerous ways to do this. Would also have made a more complicated if-statement: <tt>if (question.answer == "R1" &amp;&amp; ${r1.resistance} &gt; 1e12) { question.points_earned = 10 } else if ....</tt>.</p>
<h3><a name="BreadboardActivityAuthoring-Thequestionobject"></a>The question object</h3>
<p>The question object in the Sparks application contains all the information needed to display a question and make a report: the prompt, the point-value, the correct_option (sometimes), and, after the question has been graded, the points earned, feedback, tutorials to be displayed and so on. You can set any property you want, which is, of course, dangerous: if you set question.answer, for instance, you will be changing the student's actual answer.</p>
<p>The following are the properties that might be relevant to a script author:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Meaning </th>
</tr>
<tr>
<th class='confluenceTh'> answer </th>
<td class='confluenceTd'> The answer the student made - either the open response they typed in or the choice they selected, or the multimeter reading. If the multimeter reading was made in an AC circuit, <tt>answer</tt> will be an <b>object</b> with properties <tt>reading</tt>, <tt>frequency</tt>, and <tt>amplitude</tt>; see below. </td>
</tr>
<tr>
<th class='confluenceTh'> points </th>
<td class='confluenceTd'> The maximum points this question is worth </td>
</tr>
<tr>
<th class='confluenceTh'> points_earned </th>
<td class='confluenceTd'> The points the student scored for this question. If equal to 'points', the question is marked correct </td>
</tr>
<tr>
<th class='confluenceTh'> feedback </th>
<td class='confluenceTd'> The feedback to be displayed (won't show if the question is answered correctly) </td>
</tr>
<tr>
<th class='confluenceTh'> tutorial </th>
<td class='confluenceTd'> The link to the tutorial button </td>
</tr>
<tr>
<th class='confluenceTh'> meta </th>
<td class='confluenceTd'> An object containing additional information. See below </td>
</tr>
</tbody></table>
<h4><a name="BreadboardActivityAuthoring-Thequestionmetaobject"></a>The question meta object</h4>
<p>Whenever a student answers a question, additional information may be saved in the question.meta object, such as the state of the circuit when the user hit "submit".</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Meaning </th>
</tr>
<tr>
<th class='confluenceTh'> question.meta.frequency </th>
<td class='confluenceTd'> The frequency of the power source when the user hit submit (AC only) </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.amplitude </th>
<td class='confluenceTd'> The amplitude of the power source when the user hit submit (AC only) </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.dmmDial </th>
<td class='confluenceTd'> The current DMM dial setting as a string </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.oscopeScaleQuality </th>
<td class='confluenceTd'> The "quality" of the current OScope scale, from 0 to 1 </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.AminusB </th>
<td class='confluenceTd'> Whether the A-B button was active at any time while the question was being answered </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.AplusB </th>
<td class='confluenceTd'> Whether the A+B button was active at any time while the question was being answered </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.val </th>
<td class='confluenceTd'> Used for multimeter-button readings (below) </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.units </th>
<td class='confluenceTd'> Used for multimeter-button readings (below)</td>
</tr>
</tbody></table>
<h4><a name="BreadboardActivityAuthoring-Usingthemultimeterbutton"></a>Using the multimeter button</h4>
<p>If the question used the "Read Multimeter" button (by setting the property <tt>show_read_multimeter_button</tt> of the question object to true), the user will be shown a button allowing them to directly enter the value from the multimeter. The question's answer property will be set to a string representing what was seen on the DMM (e.g. "20 mA"). However, just like parsing an answer (see Parsing written answers), the question will also save two additional properties in the meta object: question.meta.val will be the actual value of the reading at the base SI unit, and question.meta.units will be the units.</p>
<p>So if a student presses "Read Multimeter" when the DMM is showing "20 mA", the following properties will be saved:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Value given input of "20 mA" </th>
</tr>
<tr>
<th class='confluenceTh'> question.answer </th>
<td class='confluenceTd'> "20 mA" </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.val </th>
<td class='confluenceTd'> 0.02 </td>
</tr>
<tr>
<th class='confluenceTh'> question.meta.units </th>
<td class='confluenceTd'> "A" </td>
</tr>
</tbody></table>
<h3><a name="BreadboardActivityAuthoring-Thelogobject"></a>The log object</h3>
<p>Scripts have access to the student log, and can get the current log through the helper variable <b>log</b>. The following methods are available:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Method </th>
<th class='confluenceTh'>&nbsp;</th>
</tr>
<tr>
<th class='confluenceTh'> measurements() </th>
<td class='confluenceTd'> total number of measurements (inc. dial spinning) </td>
</tr>
<tr>
<th class='confluenceTh'> uniqueVMeasurements() </th>
<td class='confluenceTd'> unique voltage measurements </td>
</tr>
<tr>
<th class='confluenceTh'> uniqueIMeasurements() </th>
<td class='confluenceTd'> ... current </td>
</tr>
<tr>
<th class='confluenceTh'> uniqueRMeasurements() </th>
<td class='confluenceTd'> ... resistance </td>
</tr>
<tr>
<th class='confluenceTh'> connectionBreaks() </th>
<td class='confluenceTd'> number of times student broke a connection (lifted a lead) </td>
</tr>
<tr>
<th class='confluenceTh'> connectionMakes() </th>
<td class='confluenceTd'> replaced a lead </td>
</tr>
<tr>
<th class='confluenceTh'> blownFuses() </th>
<td class='confluenceTd'> number of times student blew the fuse </td>
</tr>
</tbody></table>
<h3><a name="BreadboardActivityAuthoring-Parsingwrittenanswers"></a>Parsing written answers</h3>
<p>Two in-built script functions are available to help authors decipher and score hand-written answers, "parse" and "close".</p>
<p><b>parse(question.answer)</b> will take the student's answer and return an object. That's object's <b>val</b> is the parsed value, and <b>units</b> is the parsed units.</p>
<p><b>close(num1, num3, optionalPercent)</b> will return <b>true</b> if num1 is close to num2. By default, closeness is considered to be within 5%. You can optionally put in a third parameter, so <b>close(100, 120, 20)</b> will return true, because 120 is within 20% of 100.</p>
<p>Example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">var</span> parsedAnswer = parse(question.answer);
<span class="code-keyword">var</span> valueCorrect = close(parsedAnswer.val, 5010);
<span class="code-keyword">if</span> (valueCorrect) {
question.points_earned = 10;
}
</pre>
</div></div>
<h3><a name="BreadboardActivityAuthoring-Otherusefulfunctionsforscripts"></a>Other useful functions for scripts</h3>
<p>Besides the functions "parse" and "close" described above, there are a number of other specialized functions that may be useful to script authors.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Area </th>
<th class='confluenceTh'> Function </th>
<th class='confluenceTh'> What it does </th>
<th class='confluenceTh'> Example </th>
</tr>
<tr>
<th class='confluenceTh'> Parsing, measurements and units </th>
<td class='confluenceTd'> sparks.unit.convertMeasurement(string) </td>
<td class='confluenceTd'> Converts a measurement (as a string) to engineering notation if possible </td>
<td class='confluenceTd'> ...convertMeasurement("0.0045 A") -&gt; "4.5 mA" </td>
</tr>
<tr>
<th class='confluenceTh'>&nbsp;</th>
<td class='confluenceTd'> sparks.unit.toEngineering(value, units) </td>
<td class='confluenceTd'> Converts a measurement (as a value and a string unit) to an object in engineering notation </td>
<td class='confluenceTd'> ...toEngineering(0.0045, "A") -&gt; <tt>{value: 4.5, units: "mA"}</tt> </td>
</tr>
<tr>
<th class='confluenceTh'> Math </th>
<td class='confluenceTd'> <em>See the section</em> More math functions <em>above</em> </td>
</tr>
</tbody></table>
<h2><a name="BreadboardActivityAuthoring-Questionbeforescripts"></a>Question before scripts</h2>
<p>The "beforeScript" in a question is run the moment that question is enabled. So for the first question on a page, it is run immediately when the user flips to that page, and for later questions on the page it is run when the user hits "Submit" on the question above. </p>
<p>You can do anything in these scripts, but two common actions are showing or hiding the DMM or OScope:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"Look, now the DMM has appeared! What is the rated resistance of R1?"</span>,
<span class="code-quote">"beforeScript"</span>: <span class="code-quote">"sparks.sectionController.setDMMVisibility(<span class="code-keyword">true</span>)"</span>,
},
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"Awww... now the OScope has gone!"</span>,
<span class="code-quote">"beforeScript"</span>: <span class="code-quote">"sparks.sectionController.setOScopeVisibility(<span class="code-keyword">false</span>)"</span>,
}
</pre>
</div></div>
<h1><a name="BreadboardActivityAuthoring-Generalscriptingtipsandstrategies"></a>General scripting tips and strategies</h1>
<p><b>Observations by John:</b><br/>
<em><font color="#0099CC">In my tests, scripts can be run from these locations, and are executed question by question, in this order:</font> <font color="#993333"><b>option, notes, beforeScript</b></font><font color="#0099CC"> (i.e.,before Submit), and </font><font color="#993333"><b>scoring</b></font><font color="#0099CC"> (i.e., after Submit). So, if a first-question option is to be based on scripts or variables calculated in a script, the scripts and/or variables involved all need to be embedded in that option or a prior option, e.g., the very first page 1 option.)</font></em></p>
<p><font color="#0099CC"><em>Since all authored entries are surrounded by quotes, we must use single quotes to delimit strings, or escape the quotation marks around parameters (e.g., in HTML or CSS) with a backslash. In <b>options</b> and <b>notes</b> the Java code and Java variables are parsed using the brackets, while code and variable names in the <b>beforeScript</b> and <b>scoring</b> sections are all considered to be Java code and variable names (see examples). Since the <b>option</b> and <b>notes</b> ultimately display something, e.g., a question choice, give heed to the last occurring object/value in the scripts used in these sections.</em></font></p>
<h2><a name="BreadboardActivityAuthoring-Globalvariables"></a>Global variables</h2>
<p>All scripts can set global variables using the sparks.vars.<b>X</b>, where x is any variable name.</p>
<p>Note the order that scripts are executed in: All question options are read first, one after the other, and any scripts executed. Then the Notes is read and any scripts executed. Then, after the student has subitted all the answers on a page, the scoring scripts are executed. If a variable is defined in a late-executed script, it can't be used in an earlier script.</p>
<p>Example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-quote">"questions"</span>: [
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the resistance of R1?"</span>,
<span class="code-quote">"correct_answer"</span>: <span class="code-quote">"[sparks.vars.a = 10/2; sparks.vars.a]"</span>,
<span class="code-quote">"correct_units"</span>: <span class="code-quote">"ohms"</span>
},
{
<span class="code-quote">"prompt"</span>: <span class="code-quote">"What is the resistance of R1?"</span>,
<span class="code-quote">"correct_answer"</span>: <span class="code-quote">"[sparks.vars.a]"</span>,
<span class="code-quote">"correct_units"</span>: <span class="code-quote">"ohms"</span>
}
]
</pre>
</div></div>
<h2><a name="BreadboardActivityAuthoring-Findingfaults"></a>Finding faults</h2>
<p>Quickly finding circuit faults is possible in any script.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Method </th>
<th class='confluenceTh'>&nbsp;</th>
</tr>
<tr>
<th class='confluenceTh'> breadboard.getFault() </th>
<td class='confluenceTd'> returns the 1st faulty resistor in the circuit, or only fault is there is only one </td>
</tr>
<tr>
<th class='confluenceTh'> breadboard.getFaults() </th>
<td class='confluenceTd'> returns the array of all the faults. breadboard.getFaults()0 gives you the first (as above); breadboard.getFaults()1 gives you the second, etc.; breadboard.getFaults().length gives you the total number of faults. </td>
</tr>
</tbody></table>
<p>the resistor objects returned by the functions above are exactly the same as r1, r2 above. So you can say <tt>breadboard.getFault().UID</tt> for the id, <tt>breadboard.getFault().resistance</tt>, etc.</p>
<p>You can now check if a resistor is open or shorted quickly. <tt>r1.open</tt> and <tt>r1.shorted</tt> return true or false. Likewise, <tt>breadboard.getFault().open</tt>, or <tt>breadboard.getFaults()\[1\].shorted</tt> will tell you what type of fault the known-bad-resistors 1 and 2 are.</p>
<h2><a name="BreadboardActivityAuthoring-Loggingtotheconsole"></a>Logging to the console</h2>
<p>From within any script, you can log messages to the Javascript console (visible on Chrome through View &#45;&gt; Developer &#45;&gt; Javascript Console) using <tt>console.log(X)</tt>. Not only can you use this to log variable values (e.g. <tt>console.log("The res of R1 is " + r1.resistance)</tt>), but if you log an object alone it will display itself in the console in such a way that you can open it up:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> console.log(r1) </th>
<td class='confluenceTd'> Print (and open up) the object representing R1 </td>
</tr>
<tr>
<th class='confluenceTh'> console.log(log) </th>
<td class='confluenceTd'> Print the current log </td>
</tr>
</tbody></table>
<h1><a name="BreadboardActivityAuthoring-Defininganactivity"></a>Defining an activity</h1>
<p>Sparks activities are made up of multiple sections (levels). A given section can be used in multiple activities.</p>
<p>To define an activity, you can create a new JSON document in the Couch Database, and give it three simple properties: <b>type: activity</b>, to distinguish it from sections, a <b>title</b>, and <b>sections</b>, an array of the ids of the sections you want to use:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
<span class="code-quote">"_id"</span>: <span class="code-quote">"series-resistances"</span>,
<span class="code-quote">"type"</span>: <span class="code-quote">"activity"</span>,
<span class="code-quote">"title"</span>: <span class="code-quote">"Series Resistances"</span>,
<span class="code-quote">"sections"</span>: [
<span class="code-quote">"series-a"</span>,
<span class="code-quote">"series-b"</span>,
<span class="code-quote">"series-c"</span>,
<span class="code-quote">"series-d"</span>,
<span class="code-quote">"series-e"</span>,
<span class="code-quote">"series-f"</span>
]
}
</pre>
</div></div>
<p>Just as with levels, ff you give an activity the id X, it can be found at <a href="http://sparks.portal.concord.org/sparks-content/activities.html#X">http://sparks.portal.concord.org/sparks-content/activities.html#X</a>.</p>
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td height="12" background="http://confluence.concord.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
</tr>
<tr>
<td align="center"><font color="grey">Document generated by Confluence on Jan 28, 2014 17:31</font></td>
</tr>
</table>
</body>
</html>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment