mumuki-laboratory 7.5.1 → 7.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29f66dce581024a0293143b796f0eb335d70e95caa9ea46c502722795cbba45b
-  data.tar.gz: b469e0fcd7e4641b5f20f2efe445317d80427da353e1410c9f4a05a98b71c4de
+  metadata.gz: d60f8e4e5e65ba9fbec1d6faa38f76553495da9143ddd468b5d03f9e44a82c13
+  data.tar.gz: 59691b467d9f217fd42c114965e7c8111f8ffc636931b20b08275df30a533410
 SHA512:
-  metadata.gz: 283c6fda05975f588f00256b7e3f064e0dfb91f22e2b6268141c2c71f23ca0a61096f7f881e2669807c4f6adcfa2d78ebe30e1f690df8bd2227cb17d91eece72
-  data.tar.gz: ab0b73b864f01d3ca18249ecbf7dabd2fa2fb8d14b4caeb1d2f868e2ee3588d0893d27fb501b7c62dccbbab0409603b26c7060840e6bcc51aff1238e232400ae
+  metadata.gz: 2728b431baba6b407f648d6adf0315288e4644f0672c6f9144b9c67bb02d9f3d4213aaa5e70016a0b0803e2bbf6d6abff5cab16b9924c3d8da2d18e4599736a8
+  data.tar.gz: 2b94fcdab8698adfecc7dd579d24aa99941e49f4ff92f061cd549ceedf5d040962a83b7cfc9efceffa94251416222473586a5580887a0e7ef9e0f841781853d3

data/README.md

@@ -158,7 +158,9 @@ which are granted to be safe and stable.
 * `.mu-kids-submit-button`
 * `.mu-multiple-scenarios`
 * `.mu-scenarios`
+* `.mu-submit-button`
 * `#mu-actual-state-text`
+* `#mu-${languageName}-custom-editor`
 * `#mu-custom-editor-default-value`
 * `#mu-custom-editor-extra`
 * `#mu-custom-editor-test`
@@ -170,7 +172,6 @@ which are granted to be safe and stable.
 * `.mu-kids-gbs-board-initial`: Use `.mu-initial-state` instead
 * `.mu-state-final`: Use `.mu-final-state` instead
 * `.mu-state-initial`: Use `.mu-initial-state` instead
-* `#kids-context`: Use `.mu-kids-context` instead
 * `#kids-results-aborted`: Use `.mu-kids-results-aborted` instead
 * `#kids-results`: Use `.mu-kids-results` instead
 
@@ -178,6 +179,8 @@ which are granted to be safe and stable.
 
 * `mumuki.bridge.Laboratory`
   * `.runTests`
+* `mumuki.CustomEditor`
+  * `addSource`
 * `mumuki.editor`
   * `formatContent`
   * `reset`
@@ -191,6 +194,7 @@ which are granted to be safe and stable.
   * `scaleBlocksArea`
   * `scaleState`
   * `showResult`
+  * `showContext`
 * `mumuki.renderers`
   * `SpeechBubbleRenderer`
   * `renderSpeechBubbleResultItem`
@@ -205,6 +209,9 @@ which are granted to be safe and stable.
   * `setUpDeleteFiles`
   * `setUpDeleteFile`
   * `updateButtonsVisibility`
+* `mumuki.submission`
+  * `processSolution`
+  * `registerContentSyncer`
 * `mumuki.version`
 
 ### Bridge Response Format
@@ -213,7 +220,6 @@ which are granted to be safe and stable.
 {
   "status": "passed|passed_with_warnings|failed",
   "guide_finished_by_solution": "boolean",
-  "class_for_progress_list_item": "string",
   "html": "string",
   "remaining_attempts_html": "string" ,
   "title_html": "string",                         // kids-only
@@ -243,6 +249,182 @@ which are granted to be safe and stable.
 2. Laboratory Kids Layout Initialization
 3. Runner Editor HTML
 
+## Custom editors
+
+Mumuki provides several editor types: code editors, multiple choice, file upload, and so on.
+However, some runners will require custom editors in order to provide better ways of entering
+solutions.
+
+The process to do so is not difficult, but tricky, since there are a few hooks you need to implement. Let's look at them:
+
+### 1. Before state: adding layout assets
+
+If you need to provide a custom editor, chances are that you also need to provide assets to augment the layout, e.g. providing ways
+to render some custom components on descriptions or corollaries. That code will be included first.
+
+In order to do that, add to your runner the layout html, css and js code. Layout code has no further requirements. It can customize any public selector previously.
+
+Although it is not required, it is recommended that your layout code works with any of the mumuki layouts:
+
+* `input_right`
+* `input_bottom`
+* `input_primary`
+* `input_kindergarten`
+
+:warning: Not all the selectors will be available to all layouts.
+
+Then expose code in the `MetadataHook`:
+
+```ruby
+class ... < Mumukit::Hook
+  def metadata
+    {
+      layout_assets_urls: {
+        js: [
+          'assets/....'
+        ],
+        css: [
+          'assets/....'
+        ],
+        html: [
+          'assets/....'
+        ]
+      }
+    }
+  end
+end
+```
+
+Finally, it is _recommended_ that you layout code calls `mumuki.assetsLoadedFor('layout')` when fully loaded.
+
+That's it!
+
+### 2. Adding custom editor assets
+
+The process for registering custom editors is more involving.
+
+#### 2.1 Add your assets and expose them
+
+Add your js, css and html assets to your runner, and expose them in `MetadataHook`:
+
+```ruby
+class ... < Mumukit::Hook
+  def metadata
+    {
+      editor_assets_urls: {
+        js: [
+          'assets/....'
+        ],
+        css: [
+          'assets/....'
+        ],
+        html: [
+          'assets/....'
+        ]
+      }
+    }
+  end
+end
+```
+
+These assets will only be loaded when the editor `custom` is used.
+
+#### 2.2 Add your components to the custom editor
+
+Using JavaScript, append your components the custom-editor root, which can be found using the following selectors:
+
+* `mu-${languageName}-custom-editor`
+* `#mu-${languageName}-custom-editor`
+* `.mu-${languageName}-custom-editor`
+
+```javascript
+$('#mu-mylang-custom-editor').append(/* ... */)
+```
+
+#### 2.3 Extract the test
+
+If necessary, read the test definition from `#mu-custom-editor-test`, and plump into your custom components
+
+```javascript
+const test = $('#mu-custom-editor-test').val()
+//...use test...
+```
+
+#### 2.4 Exposing your content
+
+Before sending a submission, mumuki needs to be able to your read you editor components
+contents. There are two different approaches:
+
+* Register a syncer that writes `#mu-custom-editor-value` or any other custom editor selectors
+* Add one or more content sources
+
+```javascript
+// simplest method - you can register just one
+mumuki.submission.registerContentSyncer(() => {
+  // ... write here your custom component content...
+  $('#mu-custom-editor-value').val(/* ... */);
+});
+
+// alternate method
+// you can register many sources
+mumuki.CustomEditor.addSource({
+  getContent() {
+    return { name: "solution[content]", value: /* ... */ } ;
+  }
+});
+```
+
+#### 2.5 Optional: Sending your solution to the server programmatically
+
+Your solution will be automatically sent to the client when the submit button is pressed. However,
+if you need to trigger submission process programmatically, call `mumuki.submission.processSolution`:
+
+```javascript
+mumuki.submission.processSolution({solution: {content: /* ... */}});
+```
+
+#### 2.6 Optional: customizing your submit button
+
+You can alternatively override the default submit button UI and behaviour, by replacing it with a custom component. In order to
+do that, override the `.mu-submit-button` or the kids-specific `.mu-kids-submit-button`:
+
+```javascript
+ $(".mu-submit-button").html(/* ... */);
+```
+
+However, doing this is tricky, since you will need to manually update the UI and connecting to the server. See:
+
+* `mumuki.kids.showResult`
+* `mumuki.bridge.Laboratory.runTests`
+* `mumuki.updateProgressBarAndShowModal`
+
+#### 2.7 Register kids scalers
+
+Kids layouts have some special areas:
+
+ * _state area_: its display initial and/or final states of the exercise
+ * _blocks area_: a workspace that contains the building blocks of the solution - which are not necessary programming or blockly blocks, actually
+
+If you want to support kids layouts, you **need** to register scalers that will be called when device is resized. Skip this step otherwise.
+
+```javascript
+mumuki.kids.registerStateScaler(($state, fullMargin, preferredWidth, preferredHeight) => {
+  // ... resize your components ...
+});
+
+mumuki.kids.registerBlocksAreaScaler(($blocks) => {
+  // ... resize your components ...
+});
+```
+
+#### 2.8 Notify when your assets have been loaded
+
+In order to remove loading spinners, you will need to call `mumuki.assetsLoadedFor` when your code is ready.
+
+```javascript
+mumuki.assetsLoadedFor('editor');
+```
+
 ## Transparent Navigation API Docs
 
 In order to be able to link content, laboratory exposes slug-based routes that will redirect to the actual

data/app/assets/javascripts/mumuki_laboratory/application.js

@@ -27,7 +27,6 @@
 //= require codemirror-autorefresh
 //= require codemirror-modes
 //= require analytics
-//= require hotjar
 //= require muvment
 
 //= require_tree ./application

data/app/assets/javascripts/mumuki_laboratory/application/bridge.js

@@ -1,3 +1,11 @@
+/**
+ * @typedef {{status: string, test_results: [{status: string, title: string}]}} ClientResult
+ */
+
+/**
+ * @typedef {{solution: object, client_result?: ClientResult}} Submission
+ */
+
 var mumuki = mumuki || {};
 
 (function (mumuki) {
@@ -19,19 +27,28 @@ var mumuki = mumuki || {};
     return lastSubmission.result && lastSubmission.result.status !== 'aborted';
   }
 
-  function sendNewSolution(solution){
+  function sendNewSolution(submission){
     var token = new mumuki.CsrfToken();
     var request = token.newRequest({
       type: 'POST',
       url: window.location.origin + window.location.pathname + '/solutions' + window.location.search,
-      data: solution
+      data: submission
     });
 
-    return $.ajax(request).done(function (result) {
-      lastSubmission = { content: solution, result: result };
+    return $.ajax(request).then(preRenderResult).done(function (result) {
+      lastSubmission = { content: {solution: submission.solution}, result: result };
     });
   }
 
+
+  /**
+   * Pre-renders some html parts of submission UI
+   * */
+  function preRenderResult(result) {
+    result.class_for_progress_list_item = mumuki.renderers.progressListItemClassForStatus(result.status, true)
+    return result;
+  }
+
   mumuki.load(function () {
     lastSubmission = {};
   });
@@ -42,8 +59,12 @@ var mumuki = mumuki || {};
     // Public API
     // ==========
 
-    // Runs tests for the current exercise using the given submission
-    // content.
+    /**
+     * Runs tests for the current exercise using the given submission
+     * content.
+     *
+     * @param {object} content the content object
+     * */
     runTests: function(content) {
       return this._submitSolution({ solution: content });
     },
@@ -52,13 +73,18 @@ var mumuki = mumuki || {};
     // Private API
     // ===========
 
-    _submitSolution: function (solution) {
-      if(lastSubmissionFinishedSuccessfully() && sameAsLastSolution(solution)){
+    /**
+     * Sends a solution object
+     *
+     * @param {Submission} submission the submission object
+     */
+    _submitSolution: function (submission) {
+      if(lastSubmissionFinishedSuccessfully() && sameAsLastSolution(submission)){
         return $.Deferred().resolve(lastSubmission.result);
       } else {
-        return sendNewSolution(solution);
+        return sendNewSolution(submission);
       }
-    },
+    }
   };
 
   mumuki.bridge = {

data/app/assets/javascripts/mumuki_laboratory/application/button.js

@@ -1,3 +1,20 @@
+/**
+ * A generic button component.
+ *
+ * It exposes three APIs: low level, common and high level.
+ *
+ * The low level allows you to control all aspects of the button, but it is legacy
+ * and should not be used in new code.
+ *
+ * The common API offers the start function, which can be used under both the low
+ * and high level APIs to configure the initial on-click button handler.
+ *
+ * The high level allows to implement a simple state-like button handling
+ * that goes as follow:
+ *
+ * 1. simple flow: {init} -start-> {enabled} -wait-> {waiting} -continue-> {enabled}
+ * 2. extended flow: {init} -start-> {enabled} -wait-> {waiting} -ready-> {ready-to-continue} -continue-> {enabled}
+ */
 mumuki.Button = class {
 
   constructor($button, $container) {
@@ -6,10 +23,78 @@ mumuki.Button = class {
     this.originalContent = $button.html();
   }
 
+  // ==========
+  // Common API
+  // ==========
+
+  /**
+   * Initializes the button, configuring the action that will be called
+   * before wating, moving it into the {enabled} state.
+   */
+  start(main) {
+    this.main = (e) => {
+      e.preventDefault();
+      main();
+    };
+    this.$button.on('click', this.main)
+  }
+
+  // ==============
+  // High level API
+  // ==============
+
+  /**
+   * Moves this button into the {waiting} state,
+   * disabling its usage and updating its legend
+   */
+  wait() {
+    this.$button.off('click');
+
+    this.setWaiting();
+  }
+
+  /**
+   * Moves this button into {ready-to-continue} state,
+   * and sets the given callback to be called before continue.
+   *
+   * Going through this state is optional.
+   */
+  ready(secondary) {
+    this.$button.off('click');
+
+    this.undisable();
+    this.setRetryText();
+
+    this.$button.on('click', (e) => {
+      e.preventDefault();
+      secondary();
+    });
+  }
+
+  /**
+   * Puts this button back in the {enabled} state,
+   * making it ready-to-use.
+   */
+  continue() {
+    this.$button.off('click');
+
+    this.enable();
+
+    this.$button.on('click', this.main)
+  }
+
+  // =============
+  // Low level API
+  // =============
+
   disable () {
     this.$container.attr('disabled', 'disabled');
   }
 
+  undisable() {
+    this.$container.removeAttr('disabled');
+  }
+
   setWaiting () {
     this.preventClick();
     this.setWaitingText();
@@ -17,13 +102,17 @@ mumuki.Button = class {
 
   enable () {
     this.setOriginalContent();
-    this.$container.removeAttr('disabled');
+    this.undisable();
   }
 
   setWaitingText () {
     this.$button.html('<i class="fa fa-refresh fa-spin"></i> ' + this.$button.attr('data-waiting'));
   }
 
+  setRetryText() {
+    this.$button.html('<i class="fa fa-undo"></i>');
+  }
+
   setOriginalContent () {
     this.$button.html(this.originalContent);
   }