From 395f54581a44746cf91e5388b89c11f6ae9982ba Mon Sep 17 00:00:00 2001
From: Robert Zorko <robertz@gurucue.com>
Date: Fri, 18 Sep 2015 10:32:58 +0200
Subject: added some comments and improved the selection of the divs which are
 beeing changed when transitioning

---
 index.html         |  8 ++++----
 js/codeq/prolog.js | 41 ++++++++++++++++++++++++++++++++++-------
 js/codeq/python.js | 40 ++++++++++++++++++++++++++++++++--------
 3 files changed, 70 insertions(+), 19 deletions(-)

diff --git a/index.html b/index.html
index 5ca650a..6b2c31e 100644
--- a/index.html
+++ b/index.html
@@ -82,11 +82,11 @@
 
         <div class="container-fluid" id="screen_prolog" style="display: none;">
             <div class="row">
-                <div class="col-lg-3 col-md-6 col-sm-12 block">
+                <div class="col-lg-3 col-md-6 col-sm-12 block" id="description_outer_div">
                     <div id="description"></div>
                     <div class="block-label">Instructions</div>
                 </div>
-                <div class="col-lg-3 col-md-6 col-sm-12 block">
+                <div class="col-lg-3 col-md-6 col-sm-12 block" id="code_editor_outer_div">
                     <nav class="navbar navbar-default" id="block-toolbar">
                         <div class="container-fluid">
                             <button type="button" class="btn btn-default navbar-btn" id="btn_code_hint">Hint</button>
@@ -96,11 +96,11 @@
                     <div id="code_editor"></div>
                     <div class="block-label">Code</div>
                 </div>
-                <div class="col-lg-3 col-md-6 col-sm-12 block">
+                <div class="col-lg-3 col-md-6 col-sm-12 block" id="console_outer_div">
                     <div id="console"></div>
                     <div class="block-label">Console</div>
                 </div>
-                <div class="col-lg-3 col-md-6 col-sm-12 block">
+                <div class="col-lg-3 col-md-6 col-sm-12 block" id="info_outer_div">
                     <div id="info"></div>
                     <div class="block-label">Hints</div>
                 </div>
diff --git a/js/codeq/prolog.js b/js/codeq/prolog.js
index 682b81e..a663e06 100644
--- a/js/codeq/prolog.js
+++ b/js/codeq/prolog.js
@@ -6,41 +6,69 @@
     var problems,//this will the actual (sub)state machine
         stateNameTag = 'stateName';
 
+    //get the divs which are the main elements being change on transitions between states in the sub-state machine
     var divs = {};
-    divs['description'] = $('div.col-lg-3.col-md-6.col-sm-12:has(#description)');//lets actually find the needed divs for later use
-    divs['code'] = $('div.col-lg-3.col-md-6.col-sm-12:has(#code_editor)');
-    divs['console'] = $('div.col-lg-3.col-md-6.col-sm-12:has(#console)');//named 'consoleDiv', because 'console' is already in use
-    divs['info'] = $('div.col-lg-3.col-md-6.col-sm-12:has(#info)');
+    divs['description'] = $('#description_outer_div');//$('div.col-lg-3.col-md-6.col-sm-12:has(#description)');
+    divs['code'] = $('#code_editor_outer_div');//$('div.col-lg-3.col-md-6.col-sm-12:has(#code_editor)');
+    divs['console'] = $('#console_outer_div');//$('div.col-lg-3.col-md-6.col-sm-12:has(#console)');
+    divs['info'] = $('#info_outer_div');//$('div.col-lg-3.col-md-6.col-sm-12:has(#info)');
 
+    //these tags connect the div to their respective state in the sub-state machine
     divs['description'].data(stateNameTag, 'description');
     divs['code'].data(stateNameTag, 'code');
     divs['console'].data(stateNameTag, 'console');
     divs['info'].data(stateNameTag, 'info');
 
     var eventName = 'mousedown',//event name of the event which will trigger the transition between these substates
+        /**
+         * the general function which should be called on the mousedown event to trigger the transition between states
+         */
         mouseDownEventFunction = function () {
             problems.transition($(this).data(stateNameTag));
         },
+        /**
+         * removes the above function from the divs
+         */
         removeListenersFromDivs = function () {
             $.each(divs, function (i, value) {
                 value.off(eventName, mouseDownEventFunction);
             });
         },
+        /**
+         * removes the 'block' class from all divs we need to change when we change the current state
+         */
         removeBlockClassesFromDivs = function () {
             $.each(divs, function (i, value) {
                 value.removeClass('block');
             });
         },
+        /**
+         * removes all those special classes from the divs, which are set when a new state is entered and it also adds the 'block' class back
+         */
         removeChangedClassesFromDivs = function () {
             $.each(divs, function (i, value) {
                 value.removeClass('block-focus block-less-width block-less-height block-less-everything').addClass('block');//these class names were chosen for the view where the screen is partitioned in 4 quarters (2 by 2)
             });
         },
+        /**
+         *
+         * @param current the key of the state ('description','code','hint','console'), which is currently active, because it must not have a transition set
+         */
         setTransitionsBetweenDivs = function (current) {
             $.each(divs, function (key, value) {
                 if (current !== key) value.on(eventName, mouseDownEventFunction);
             });
         },
+        /**
+         *
+         * @param divsWithClasses a object where we have the keys of the divs object paired with the class name we want to assign to them e.g. :
+         *          {
+                        'description': 'block-focus',
+                        'code': 'block-less-width',
+                        'console': 'block-less-height',
+                        'info': 'block-less-everything'
+                    }
+         */
         addClassesToDivs = function (divsWithClasses) {
             $.each(divsWithClasses, function (divName, className) {
                 divs[divName].addClass(className);
@@ -112,7 +140,7 @@
                 }
             }
         };
-    var prologHandler;
+    var prologHandler;//created when we enter the prolog state and destroyed once we leave it
     codeq.globalStateMachine.register('prolog', {
         'enter': function (data) {
             $('#disabled').css('display', '');
@@ -121,7 +149,7 @@
             problems = codeq.makeStateMachine(substates);
             problems.transition(divs['description'].data(stateNameTag));
             Q.delay(100).then(function(){
-                $('div.col-lg-3.col-md-6.col-sm-12').addClass('transition');
+                $('div.col-lg-3.col-md-6.col-sm-12').addClass('transition');//for smooth animations - need to be delayed, because otherwise we get some weird "animations" while the page is loading
             }).done();
 
             $('#disabled').css('display', 'none');
@@ -137,7 +165,6 @@
     // a constant
     var firstCharacterPos = {'line': 0, 'ch': 0};
 
-    //codeq.makePrologTerminalHandler = function (jqConsole, editor, problem_id, activityHandler) {
     var makePrologTerminalHandler = function (jqConsole, editor, problem_id, activityHandler) {
         var promptMode = true, // default: query composition; alternative: query result browsing
             terminal = codeq.makeConsole(jqConsole, {
diff --git a/js/codeq/python.js b/js/codeq/python.js
index 3121f1e..3445db5 100644
--- a/js/codeq/python.js
+++ b/js/codeq/python.js
@@ -2,49 +2,73 @@
  * Created by robert on 9/17/15.
  */
 
-/**
- * Created by robert on 9/17/15.
- */
-
 (function() {
     var problems,//this will the actual (sub)state machine
         stateNameTag = 'stateName';
 
+    //get the divs which are the main elements being change on transitions between states in the sub-state machine
     var divs = {};
-    divs['description'] = $('div.col-lg-3.col-md-6.col-sm-12:has(#description)');//lets actually find the needed divs for later use
-    divs['code'] = $('div.col-lg-3.col-md-6.col-sm-12:has(#code_editor)');
-    divs['console'] = $('div.col-lg-3.col-md-6.col-sm-12:has(#console)');//named 'consoleDiv', because 'console' is already in use
-    divs['info'] = $('div.col-lg-3.col-md-6.col-sm-12:has(#info)');
+    divs['description'] = $('#description_outer_div');//$('div.col-lg-3.col-md-6.col-sm-12:has(#description)');
+    divs['code'] = $('#code_editor_outer_div');//$('div.col-lg-3.col-md-6.col-sm-12:has(#code_editor)');
+    divs['console'] = $('#console_outer_div');//$('div.col-lg-3.col-md-6.col-sm-12:has(#console)');
+    divs['info'] = $('#info_outer_div');//$('div.col-lg-3.col-md-6.col-sm-12:has(#info)');
 
+    //these tags connect the div to their respective state in the sub-state machine
     divs['description'].data(stateNameTag, 'description');
     divs['code'].data(stateNameTag, 'code');
     divs['console'].data(stateNameTag, 'console');
     divs['info'].data(stateNameTag, 'info');
 
     var eventName = 'mousedown',//event name of the event which will trigger the transition between these substates
+        /**
+         * the general function which should be called on the mousedown event to trigger the transition between states
+         */
         mouseDownEventFunction = function () {
             problems.transition($(this).data(stateNameTag));
         },
+        /**
+         * removes the above function from the divs
+         */
         removeListenersFromDivs = function () {
             $.each(divs, function (i, value) {
                 value.off(eventName, mouseDownEventFunction);
             });
         },
+        /**
+         * removes the 'block' class from all divs we need to change when we change the current state
+         */
         removeBlockClassesFromDivs = function () {
             $.each(divs, function (i, value) {
                 value.removeClass('block');
             });
         },
+        /**
+         * removes all those special classes from the divs, which are set when a new state is entered and it also adds the 'block' class back
+         */
         removeChangedClassesFromDivs = function () {
             $.each(divs, function (i, value) {
                 value.removeClass('block-focus block-less-width block-less-height block-less-everything').addClass('block');//these class names were chosen for the view where the screen is partitioned in 4 quarters (2 by 2)
             });
         },
+        /**
+         *
+         * @param current the key of the state ('description','code','hint','console'), which is currently active, because it must not have a transition set
+         */
         setTransitionsBetweenDivs = function (current) {
             $.each(divs, function (key, value) {
                 if (current !== key) value.on(eventName, mouseDownEventFunction);
             });
         },
+        /**
+         *
+         * @param divsWithClasses a object where we have the keys of the divs object paired with the class name we want to assign to them e.g. :
+         *          {
+                        'description': 'block-focus',
+                        'code': 'block-less-width',
+                        'console': 'block-less-height',
+                        'info': 'block-less-everything'
+                    }
+         */
         addClassesToDivs = function (divsWithClasses) {
             $.each(divsWithClasses, function (divName, className) {
                 divs[divName].addClass(className);
-- 
cgit v1.2.1