HSC2011/Building your own EduBuzzer: Unterschied zwischen den Versionen

← Zum vorherigen Versionsunterschied Zum nächsten Versionsunterschied →

VisuellWikitext

@@ Zeile 62: / Zeile 62: @@
 Align the holes in the board with the matching parts of the lower part and just screw it in somehow.
+=== software development ===
+==== architectural overview ====
+Each Edubuzzer app, e.g. '''Raise Your Hands''', is chiefly implemented in a
+single responsible JavaScript file, e.g. <tt>raise-your-hands.js</tt>. Each one can
+define a single callback, <tt>Edubuzzer.run_application</tt> which is called when
+the application is started.
+Inside <tt>Edubuzzer.run_application</tt> it may register other callbacks like
+<tt>Edubuzzer.updated_known_logins</tt> which is called whenever a client is added
+or removed, or <tt>Edubuzzer.display</tt> which is called in regular intervals.
+<tt>global.js</tt> runs a poor man's event loop and schedules all pollings to the
+server which result in callbacks of the active app registered being called.  An
+app is activated by changing the URI <tt>#hash</tt>. The skeleton switches to an app
+by simply overwriting the <tt>display</tt> function.
+==== querying buzzers ====
+<tt>/ygor</tt> is the base URI for the middleware endpoint. Send <tt>GET</tt> requests to
+certain named queries, e.g. <tt>?name=ls_accepted_login.sql</tt>. For the full list,
+see directory <tt>Ygor/sql/</tt> in the [https://github.com/Metalab/hsc2011/tree/master/software software repository]. It returns a JSON array of objects/hashes whose
+keys are described in the SQL file, e.g. for above:
+<code>
+    [{"rowid":42,"src":"BUZZER-DEVICE-ID","dest":"MASTER-DEVICE-ID",
+        "seqnum":23,"ibutton":"SOMETHING","since":"TIMESTAMP",
+        "accepted":true,"ack":false}, … ]
+</code>
+Refer to the table schemas in <tt>Ygor/schema/</tt> for explicit key/row names. Rely
+on <tt>src</tt> for uniquely identifying a buzzer.
+The most important query is <tt>ls_events.sql</tt> because it deals with the device
+buttons. The first line in the file hints at the additional query parameters,
+in this case <tt>loginid</tt>, i.e. the full query string is
+<tt>?name=ls_events&loginid=ROWID</tt> where <tt>ROWID</tt> is a number received in earlier
+different queries. Extract the button status from the <tt>eventmask</tt> field. See
+<tt>docs/serialprotocol</tt> for the semantics.
+For debugging purposes the middleware exposes an echo interface at base URI
+<tt>/echo</tt>. The query string is ignored except for the parameter name
+<tt>Response-Body</tt>. Its value is a percent encoded JSON string which
+unsurprisingly is returned as response body.
+For example, you want to mock:
+<code>
+    $.getJSON(
+        Edubuzzer.middleware_endpoint+'?name=…',
+        function (foo) {
+            …
+        }
+    )
+</code>
+Add a [http://api.jquery.com/jQuery.getJSON/ second parameter to the <tt>getJSON</tt> call], thus:
+<code>
+    $.getJSON(
+        Edubuzzer.middleware_mock_endpoint+'?name=…',
+        'Response-Body'+encodeURIComponent('[{"rowid":123}]')
+        function (foo) {
+            …
+        }
+    )
+</code>
+==== instruction list ====
+* decide on an app name (e.g. <tt>exampleapp</tt>)
+* create a new JavaScript file with the name
+* implement the <tt>run_application</tt> function and the hooks you need
+** present the app UI in element <tt>#buzzers</tt>
+** keep internal data under the <tt>Edubuzzer.exampleapp</tt> namespace
+* add the app name/link in <tt>index.xhtml</tt>
+* register the app in <tt>global.js</tt>
+* add styles in <tt>edubuzzer.css</tt>
 === Done ===