mumuki-laboratory 7.6.2 → 7.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fecc1d7f623d854c2554619adfc59748ca2b048de16a11397189c951c6243212
-  data.tar.gz: d65801b409606fb0fdf446246ba28c0af7a264ab42377f4632300890a9ae66e6
+  metadata.gz: cf3186d3e4ad3367ccf34396dfde31138bb255456b8cf5e5593a76e908545434
+  data.tar.gz: 7e3aa354499be05940fe21355f7e4a45ae933dab0a989cd8db99b48e564c8f12
 SHA512:
-  metadata.gz: 1f77c9e8dcf0c095871c903460ff37cfe6c3603a5855c31f1d02cafe97015a6e6bd5f884b51363e58bc8324cbc56e9b6aed654610275e141a444b01813d609e5
-  data.tar.gz: ecf2f4a616198b6cf6565a73d039c3bb88a421e25a644947ac2a3170f24c190901930ab354b2812eac01a843200dec6b6ebb9064469abe64677983e8f9e02e31
+  metadata.gz: e91791ad61d5843960950276383f74330b0eec046f475400c21fdb89af80f044fa3902a7a86e82d1dc3e130f30716c62e23d79f5ea87c8416c9140e550414819
+  data.tar.gz: 528f209da31776d4c01be41b92c2218bcbb6dc98175809a05062c3b077e1dc0ca8951b034e44a9a0f3cca93bbba371fd0f14da18bb56e15fac9ddb3b2e211455

data/README.md

@@ -135,6 +135,21 @@ rails s
 bundle exec rspec
 ```
 
+## Running JS tests
+
+> You need first to download [geckodriver](https://github.com/mozilla/geckodriver/releases/download/v0.27.0/geckodriver-v0.27.0-linux64.tar.gz), uncrompress
+> it and add it to your path
+
+```bash
+MOZ_HEADLESS=1 bundle exec rake teaspoon
+```
+
+## Running `eslint`
+
+```bash
+yarn run lint
+```
+
 ## JavaScript API Docs
 
 In order to be customized by runners, Laboratory exposes the following selectors and methods
@@ -158,7 +173,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 +187,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 +194,8 @@ which are granted to be safe and stable.
 
 * `mumuki.bridge.Laboratory`
   * `.runTests`
+* `mumuki.CustomEditor`
+  * `addSource`
 * `mumuki.editor`
   * `formatContent`
   * `reset`
@@ -191,10 +209,15 @@ which are granted to be safe and stable.
   * `scaleBlocksArea`
   * `scaleState`
   * `showResult`
+  * `showContext`
 * `mumuki.renderers`
   * `SpeechBubbleRenderer`
   * `renderSpeechBubbleResultItem`
 * `mumuki.locale`
+* `mumuki.exercise`
+   * `id`: the `id` of the currently loaded exercise, if any
+   * `layout`: the `layout` of the currently loaded exercise, if any
+* `mumuki.incognitoUser`: whether the current user is an incognito user
 * `mumuki.MultipleScenarios`
   * `scenarios`
   * `currentScenarioIndex`
@@ -205,6 +228,9 @@ which are granted to be safe and stable.
   * `setUpDeleteFiles`
   * `setUpDeleteFile`
   * `updateButtonsVisibility`
+* `mumuki.submission`
+  * `processSolution`
+  * `registerContentSyncer`
 * `mumuki.version`
 
 ### Bridge Response Format
@@ -213,7 +239,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 +268,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.editors.registerContentSyncer(() => {
+  // ... write here your custom component content...
+  $('#mu-custom-editor-value').val(/* ... */);
+});
+
+// alternate method
+// you can register many sources
+mumuki.editors.addCustomSource({
+  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/Rakefile

@@ -27,6 +27,15 @@ require 'rspec/core/rake_task'
 desc "Run all specs in spec directory (excluding plugin specs)"
 RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
 
+desc "Force development environment, required by javascript specs"
+task :development do
+  ENV['RACK_ENV'] = 'development'
+  ENV['RAILS_ENV'] = 'development'
+end
+
+desc "Run the javascript specs"
+task teaspoon: [:development, "app:teaspoon"]
+
 task default: :spec
 
 

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/alias-modes.js

@@ -1,4 +1,4 @@
-mumuki.load(function () {
+mumuki.load(() => {
 
   function CodeMirrorAlias(alias, current) {
     CodeMirror.defineMIME(alias, CodeMirror.mimeModes[current]);

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

@@ -1,4 +1,4 @@
-const assetsLoader = {
+var assetsLoader = {
   layout: {
     onLoadingStarted: function () {
 

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

@@ -1,68 +1,103 @@
-var mumuki = mumuki || {};
+/**
+ * @typedef {"errored"|"failed"|"passed_with_warnings"|"passed"|"pending"|"aborted"} SubmissionStatus
+ */
 
-(function (mumuki) {
-  var lastSubmission = {};
+/**
+ * @typedef {{
+ *  status: SubmissionStatus,
+ *  test_results: [{status: SubmissionStatus, title: string}]
+ * }} SubmissionClientResult
+ */
 
-  function Laboratory(exerciseId){
-    this.exerciseId = exerciseId;
-  }
+/**
+ * @typedef {{
+  *  status: SubmissionStatus,
+  *  class_for_progress_list_item?: string,
+  *  guide_finished_by_solution?: boolean
+  * }} SubmissionResult
+  */
 
-  function asString(json){
-    return JSON.stringify(json);
-  }
+/**
+ * @typedef {object} Solution
+ */
 
-  function sameAsLastSolution(newSolution){
-    return asString(lastSubmission.content) === asString(newSolution);
-  }
+/**
+ * @typedef {{
+ *  "solution[content]"?:string,
+ *  solution?: Solution,
+ *  client_result?: SubmissionClientResult
+ * }} Submission
+ */
 
-  function lastSubmissionFinishedSuccessfully(){
-    return lastSubmission.result && lastSubmission.result.status !== 'aborted';
-  }
-
-  function sendNewSolution(solution){
-    var token = new mumuki.CsrfToken();
-    var request = token.newRequest({
-      type: 'POST',
-      url: window.location.origin + window.location.pathname + '/solutions' + window.location.search,
-      data: solution
-    });
-
-    return $.ajax(request).done(function (result) {
-      lastSubmission = { content: solution, result: result };
-    });
-  }
+/**
+ * @typedef {{submission?: Submission, result?: SubmissionResult}} SubmissionAndResult
+ */
 
-  mumuki.load(function () {
-    lastSubmission = {};
-  });
-
-  Laboratory.prototype = {
+mumuki.bridge = (() => {
 
+  class Laboratory {
     // ==========
     // Public API
     // ==========
 
-    // Runs tests for the current exercise using the given submission
-    // content.
-    runTests: function(content) {
+    /**
+     * Runs tests for the current exercise using the given submission
+     * content.
+     *
+     * @param {object} content the content object
+     * */
+    runTests(content) {
       return this._submitSolution({ solution: content });
-    },
+    }
 
     // ===========
     // Private API
     // ===========
 
-    _submitSolution: function (solution) {
-      if(lastSubmissionFinishedSuccessfully() && sameAsLastSolution(solution)){
-        return $.Deferred().resolve(lastSubmission.result);
+    /**
+     * Sends a solution object
+     *
+     * @param {Submission} submission the submission object
+     * @returns {JQuery.Promise<SubmissionResult>}
+     */
+    _submitSolution(submission) {
+      const lastSubmission = mumuki.SubmissionsStore.getSubmissionResultFor(mumuki.exercise.id, submission);
+      if (lastSubmission) {
+        return $.Deferred().resolve(lastSubmission);
       } else {
-        return sendNewSolution(solution);
+        return this._sendNewSolution(submission).done((result) => {
+          mumuki.SubmissionsStore.setSubmissionResultFor(mumuki.exercise.id, {submission, result});
+        });
       }
-    },
-  };
+    }
 
-  mumuki.bridge = {
-    Laboratory: Laboratory
-  };
+    /**
+     * @param {Submission} submission the submission object
+     * @returns {JQuery.Promise<SubmissionResult>}
+     */
+    _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: submission
+      });
+      return $.ajax(request).then((result) => this._preRenderResult(result));
+    }
 
-}(mumuki));
+    /**
+     * Pre-renders some html parts of submission UI, adding them to the given result
+     *
+     * @param {SubmissionResult} result
+     * @returns {SubmissionResult}
+     */
+    _preRenderResult(result) {
+      result.class_for_progress_list_item = mumuki.renderers.progressListItemClassForStatus(result.status, true)
+      return result;
+    }
+  }
+
+  return {
+    Laboratory
+  };
+})();