jclic 2.2.0 → 2.3.0

package/src/project/ProjectSettings.js

@@ -1,273 +0,0 @@
-/**
- *  File    : project/ProjectSettings.js
- *  Created : 01/04/2015
- *  By      : Francesc Busquets <francesc@gmail.com>
- *
- *  JClic.js
- *  An HTML5 player of JClic activities
- *  https://projectestac.github.io/jclic.js
- *
- *  @source https://github.com/projectestac/jclic.js
- *
- *  @license EUPL-1.2
- *  @licstart
- *  (c) 2000-2020 Educational Telematic Network of Catalonia (XTEC)
- *
- *  Licensed under the EUPL, Version 1.1 or -as soon they will be approved by
- *  the European Commission- subsequent versions of the EUPL (the "Licence");
- *  You may not use this work except in compliance with the Licence.
- *
- *  You may obtain a copy of the Licence at:
- *  https://joinup.ec.europa.eu/software/page/eupl
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
- *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- *  Licence for the specific language governing permissions and limitations
- *  under the Licence.
- *  @licend
- *  @module
- */
-
-/* global window */
-
-import $ from 'jquery';
-import EventSounds from '../media/EventSounds.js';
-import { log, getXmlNodeText, parseXmlNode, reduceTextsToStrings, parseOldDate, cleanOldLanguageTag, getAttr, setAttr } from '../Utils.js';
-
-/**
- * This class contains miscellaneous settings of JClic projects.
- *
- * In addition to the members of this class, there can be other properties in JClic project files
- * that are not currently loaded:
- * - iconFileName
- * - descriptors
- * - area
- * - level
- * - locale
- * - authors
- * - organizations
- * - revisions
- */
-export class ProjectSettings {
-  /**
-   * ProjectSettings constructor
-   * @param {module:project/JClicProject.JClicProject} project - The project to which this settings belongs
-   */
-  constructor(project) {
-    this.project = project;
-    this.authors = [];
-    this.organizations = [];
-    this.revisions = [];
-    this.languages = [];
-    this.locales = [];
-    this.description = {};
-    this.tags = {};
-  }
-
-  /**
-   * Reads the ProjectSettings values from a JQuery XML element
-   * @param {external:jQuery} $xml - The XML element to parse
-   */
-  setProperties($xml) {
-    let single_description = null;
-    const multiple_descriptions = [];
-
-    $xml.children().each((_n, child) => {
-      switch (child.nodeName) {
-        case 'title':
-          this.title = child.textContent;
-          break;
-        case 'description':
-          single_description = getXmlNodeText(child);
-          break;
-        case 'descriptions':
-          $(child).children().each((_n, desc) => multiple_descriptions.push(parseXmlNode(desc)));
-          break;
-        case 'author':
-          this.authors.push(reduceTextsToStrings(parseXmlNode(child)));
-          break;
-        case 'organization':
-          this.organizations.push(reduceTextsToStrings(parseXmlNode(child)));
-          break;
-        case 'revision':
-          const revision = reduceTextsToStrings(parseXmlNode(child));
-          if (revision.date)
-            revision.date = parseOldDate(revision.date);
-          this.revisions.push(revision);
-          break;
-        case 'language':
-          this.languages.push(cleanOldLanguageTag(child.textContent));
-          break;
-        case 'eventSounds':
-          this.eventSounds = new EventSounds();
-          this.eventSounds.setProperties($(child));
-          break;
-        case 'skin':
-          this.skinFileName = $(child).attr('file');
-          break;
-        case 'descriptors':
-          this.tags = parseXmlNode(child, true);
-          if (this.tags['#text']) {
-            this.tags.other = this.tags['#text'].textContent;
-            delete this.tags['#text'];
-          }
-          break;
-        case 'license':
-          this.license = getXmlNodeText(child);
-          break;
-        case 'cover':
-        case 'thumb':
-          const img = getXmlNodeText(child);
-          if (img.file)
-            this[child.nodeName] = img.file;
-          break;
-      }
-    });
-
-    this.buildLocales();
-
-    multiple_descriptions.forEach(d => {
-      if (d.language && d.text)
-        this.description[d.language] = d.text;
-    });
-
-    if (single_description && this.languages.length > 0 && !this.description[this.languages[0]])
-      this.description[this.languages[0]] = single_description;
-
-    return this;
-  }
-
-  buildLocales() {
-    // Try to find an array of valid locales
-    // See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl
-    if (this.languages.length > 0 && window.Intl && window.Intl.getCanonicalLocales) {
-      this.locales = [];
-      this.languages.forEach(lang => {
-        // Languages usually are stored in the form: "English (en)"
-        const matches = /\(([a-z,A-Z,-]+)\)/.exec(lang);
-        if (matches && matches.length > 1) {
-          try {
-            const canonicals = window.Intl.getCanonicalLocales(matches[1]);
-            if (canonicals)
-              this.locales = this.locales.concat(canonicals);
-          } catch (_err) {
-            log('error', `Invalid language: ${lang}`);
-          }
-        }
-      });
-    }
-    return this;
-  }
-
-  /**
-   * Gets a object with the basic attributes needed to rebuild this instance excluding functions,
-   * parent references, constants and also attributes retaining the default value.
-   * The resulting object is commonly usued to serialize elements in JSON format.
-   * @returns {object} - The resulting object, with minimal attrributes
-   */
-  getAttributes() {
-    return getAttr(this, [
-      'title', 'description',
-      'tags', 'languages', 'license',
-      'authors', 'organizations',
-      'revisions',
-      'cover', 'thumb',
-      'skinFileName', 'eventSounds'
-    ]);
-  }
-
-  /**
-   * Reads the properties of this ProjectSettings from a data object
-   * @param {object} data - The data object to be parsed, or just the text content
-   * @returns {module:project/ProjectSettings.ProjectSettings}
-   */
-  setAttributes(data) {
-    setAttr(this, data, [
-      'title', 'description',
-      'tags', 'languages', 'license',
-      'authors', 'organizations',
-      'revisions',
-      'cover', 'thumb',
-      'skinFileName', 'eventSounds'
-    ]);
-
-    // Build Date objects in revisions
-    if (this.revisions)
-      this.revisions.forEach(rv => {
-        if (rv.date)
-          rv.date = new Date(rv.date);
-      });
-
-    return this.buildLocales();
-  }
-}
-
-Object.assign(ProjectSettings.prototype, {
-  /**
-   * The JClicProject to which this ProjectSettings belongs
-   * @name module:project/ProjectSettings.ProjectSettings#project
-   * @type {module:project/JClicProject.JClicProject} */
-  project: null,
-  /**
-   * The project title
-   * @name module:project/ProjectSettings.ProjectSettings#title
-   * @type {string} */
-  title: 'Untitled',
-  /**
-   * The authors of this project.
-   * Each author is represented by an object with the following attributes:
-   * `name` (mandatory), `mail`, `rol`, `organization` and `url`
-   * @name module:project/ProjectSettings.ProjectSettings#authors
-   * @type {object[]} */
-  authors: null,
-  /**
-   * Schools, companies and other institutions involved on this project.
-   * Each organization is represented by an object with the following attributes:
-   * `name` (mandatory), `mail`, `url`, `address`, `pc`, `city`, `state`, `country`, `comments`
-   * @name module:project/ProjectSettings.ProjectSettings#organizations
-   * @type {object[]} */
-  organizations: null,
-  /**
-   * The history of revisions made to this project.
-   * Revisions are represented by objects with the following attributes:
-   * `date` (mandatory), `description`, `comments` and `author`
-   * @name module:project/ProjectSettings.ProjectSettings#revisions
-   * @type {object[]} */
-  revisions: null,
-  /**
-   * Project's description, maybe in multiple languages.
-   * @name module:project/ProjectSettings.ProjectSettings#description
-   * @type {object} */
-  description: null,
-  /**
-   * JClic projects can use more than one language, so use a string array
-   * @name module:project/ProjectSettings.ProjectSettings#languages
-   * @type {string[]} */
-  languages: null,
-  tags: null,
-  cover: null,
-  thumb: null,
-  license: {
-    type: 'by-nc-sa',
-    url: 'https://creativecommons.org/licenses/by-nc-sa/4.0',
-  },
-  /**
-   * Array of canonical locales, as defined in
-   * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation|Intl}
-   * @name module:project/ProjectSettings.ProjectSettings#locales
-   * @type {string[]} */
-  locales: null,
-  /**
-   * The name of an optional 'skin' (visual aspect) can be set for the whole project, or for each {@link module:Activity.Activity Activity}
-   * @name module:project/ProjectSettings.ProjectSettings#skinFileName
-   * @type {string} */
-  skinFileName: null,
-  /**
-   * The main {@link module:media/EventSounds.EventSounds EventSounds} object of the project
-   * @name module:project/ProjectSettings.ProjectSettings#eventSounds
-   * @type {module:media/EventSounds.EventSounds} */
-  eventSounds: new EventSounds(),
-});
-
-export default ProjectSettings;

package/src/report/ActionReg.js

@@ -1,123 +0,0 @@
-/**
- *  File    : report/ActionReg.js
- *  Created : 17/05/2016
- *  By      : Francesc Busquets <francesc@gmail.com>
- *
- *  JClic.js
- *  An HTML5 player of JClic activities
- *  https://projectestac.github.io/jclic.js
- *
- *  @source https://github.com/projectestac/jclic.js
- *
- *  @license EUPL-1.2
- *  @licstart
- *  (c) 2000-2020 Educational Telematic Network of Catalonia (XTEC)
- *
- *  Licensed under the EUPL, Version 1.1 or -as soon they will be approved by
- *  the European Commission- subsequent versions of the EUPL (the "Licence");
- *  You may not use this work except in compliance with the Licence.
- *
- *  You may obtain a copy of the Licence at:
- *  https://joinup.ec.europa.eu/software/page/eupl
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
- *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- *  Licence for the specific language governing permissions and limitations
- *  under the Licence.
- *  @licend
- *  @module
- */
-
-import $ from 'jquery';
-import { attrForEach, getBoolean } from '../Utils.js';
-
-/**
- * This class stores information about one specific action done by the current user while playing
- * an activity.
- *
- */
-export class ActionReg {
-  /**
-   * ActionReg constructor
-   * @param {string} type - Type of action (`click`, `write`, `move`, `select`...)
-   * @param {string}+ source - Description of the object on which the action is done.
-   * @param {string}+ dest - Description of the object that acts as a target of the action (used in pairings)
-   * @param {boolean} ok - `true` if the action was OK, `false`, `null` or `undefined` otherwise
-   */
-  constructor(type, source, dest, ok) {
-    this.type = type;
-    this.source = source || null;
-    this.dest = dest || null;
-    this.ok = ok || false;
-    this.time = (new Date()).valueOf();
-  }
-
-  /**
-   * Provides the data associated with this action in XML format suitable for a
-   * {@link http://clic.xtec.cat/en/jclic/reports/|JClic Reports Server}.
-   * @returns {external:jQuery}
-   */
-  $getXML() {
-    const attr = { ok: this.ok, time: this.time };
-    if (this.type)
-      attr.type = this.type;
-    if (this.source)
-      attr.source = this.source;
-    if (this.dest)
-      attr.dest = this.dest;
-    return $('<action/>', attr);
-  }
-
-  /**
-   * Fills this ActionReg with data provided in XML format
-   * @param {external:jQuery} $xml - The XML element to be processed, already wrapped as jQuery object
-   */
-  setProperties($xml) {
-    attrForEach($xml.get(0).attributes, (name, value) => {
-      switch (name) {
-        case 'type':
-        case 'source':
-        case 'dest':
-          this[name] = value;
-          break;
-        case 'time':
-          this[name] = Number(value);
-          break;
-        case 'ok':
-          this[name] = getBoolean(value, false);
-          break;
-      }
-    });
-  }
-}
-
-Object.assign(ActionReg.prototype, {
-  /**
-   * The type of action (`click`, `write`, `move`, `select`...)
-   * @name module:report/ActionReg.ActionReg#type
-   * @type {string} */
-  type: 'unknown',
-  /**
-   * Description of the object on which the action was done
-   * @name module:report/ActionReg.ActionReg#source
-   * @type {string} */
-  source: null,
-  /**
-   * Description of the object that has acted as a target of the action (used in pairings)
-   * @name module:report/ActionReg.ActionReg#dest
-   * @type {string} */
-  dest: null,
-  /**
-   * Time stamp taken when the action was done
-   * @name module:report/ActionReg.ActionReg#time
-   * @type {number} */
-  time: 0,
-  /**
-   * `true` if the action was OK
-   * @name module:report/ActionReg.ActionReg#isOk
-   * @type {boolean} */
-  isOk: false,
-});
-
-export default ActionReg;

package/src/report/ActivityReg.js

@@ -1,271 +0,0 @@
-/**
- *  File    : report/ActivityReg.js
- *  Created : 17/05/2016
- *  By      : Francesc Busquets <francesc@gmail.com>
- *
- *  JClic.js
- *  An HTML5 player of JClic activities
- *  https://projectestac.github.io/jclic.js
- *
- *  @source https://github.com/projectestac/jclic.js
- *
- *  @license EUPL-1.2
- *  @licstart
- *  (c) 2000-2020 Educational Telematic Network of Catalonia (XTEC)
- *
- *  Licensed under the EUPL, Version 1.1 or -as soon they will be approved by
- *  the European Commission- subsequent versions of the EUPL (the "Licence");
- *  You may not use this work except in compliance with the Licence.
- *
- *  You may obtain a copy of the Licence at:
- *  https://joinup.ec.europa.eu/software/page/eupl
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
- *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- *  Licence for the specific language governing permissions and limitations
- *  under the Licence.
- *  @licend
- *  @module
- */
-
-import $ from 'jquery';
-import { attrForEach, getBoolean } from '../Utils.js';
-import ActionReg from './ActionReg.js';
-
-/**
- * This class stores miscellaneous data obtained by the current user playing an {@link module:Activity.Activity Activity}.
- */
-export class ActivityReg {
-  /**
-   * ActivityReg constructor
-   * @param {module:Activity.Activity} act - The {@link module:Activity.Activity Activity} referenced by this object.
-   */
-  constructor(act) {
-    this.name = act.name;
-    this.code = act.code;
-    this.actions = [];
-    this.startTime = (new Date()).valueOf();
-    this.minActions = act.getMinNumActions();
-    this.reportActions = act.reportActions;
-  }
-
-  /**
-   * Provides the data associated with the current activity in an XML format suitable for a
-   * {@link http://clic.xtec.cat/en/jclic/reports/|JClic Reports Server}.
-   * @returns {external:jQuery}
-   */
-  $getXML() {
-    const attr = {
-      start: this.startTime,
-      time: this.totalTime,
-      solved: this.solved,
-      score: this.score,
-      minActions: this.minActions,
-      actions: this.numActions
-    };
-    if (this.name)
-      attr.name = this.name;
-    if (this.code)
-      attr.code = this.code;
-    if (!this.closed)
-      attr.closed = false;
-    if (this.reportActions)
-      attr.reportActions = true;
-
-    const $result = $('<activity/>', attr);
-    this.actions.forEach(ac => {
-      $result.append(ac.$getXML());
-    });
-    return $result;
-  }
-
-  /**
-   * Builds an object with relevant data about the results obtained by the current student in this activity
-   * @returns {object} - The results of this activity
-   */
-  getData() {
-    const result = {
-      name: this.name,
-      time: Math.round(this.totalTime / 10) / 100,
-      solved: this.solved,
-      score: this.score,
-      minActions: this.minActions,
-      actions: this.numActions,
-      precision: this.getPrecision(),
-      closed: this.closed
-    };
-    if (this.code)
-      result.code = this.code;
-    return result;
-  }
-
-  /**
-   * Fills this ActivityReg with data provided in XML format
-   * @param {external:jQuery} $xml -The XML element to be processed, already wrapped as jQuery object
-   */
-  setProperties($xml) {
-    attrForEach($xml.get(0).attributes, (name, value) => {
-      switch (name) {
-        case 'name':
-        case 'code':
-          this[name] = value;
-          break;
-        case 'start':
-        case 'time':
-        case 'score':
-        case 'minActions':
-        case 'actions':
-          this[name] = Number(value);
-          break;
-        case 'solved':
-        case 'closed':
-        case 'reportActions':
-          this[name] = getBoolean(value, false);
-          break;
-      }
-    });
-    $xml.children('action').each((_n, child) => {
-      const action = new ActionReg();
-      action.setProperties($(child));
-      this.actions.push(action);
-    });
-  }
-
-  /**
-   * Reports a new action done by the user while playing the current activity
-   * @param {string} type - Type of action (`click`, `write`, `move`, `select`...)
-   * @param {string}+ source - Description of the object on which the action is done.
-   * @param {string}+ dest - Description of the object that acts as a target of the action (used in pairings)
-   * @param {boolean} ok - `true` if the action was OK, `false`, `null` or `undefined` otherwise
-   */
-  newAction(type, source, dest, ok) {
-    if (!this.closed) {
-      this.lastAction = new ActionReg(type, source, dest, ok);
-      this.actions.push(this.lastAction);
-    }
-  }
-
-  /**
-   * Retrieves a specific {@link module:report/ActionReg.ActionReg ActionReg} element from `actions`
-   * @param {number} index - The nth action to be retrieved
-   * @returns {module:report/ActionReg.ActionReg}
-   */
-  getActionReg(index) {
-    return index >= this.actions.length ? null : this.actions[index];
-  }
-
-  /**
-   * Closes the current activity, adjusting total time if needed
-   */
-  closeActivity() {
-    if (!this.closed) {
-      if (this.lastAction)
-        this.totalTime = this.lastAction.time - this.startTime;
-      else
-        this.totalTime = (new Date()).valueOf() - this.startTime;
-      this.closed = true;
-    }
-  }
-
-  /**
-   * calculates the final score obtained by the user in this activity.
-   * The algorithm used takes in account the minimal number of actions needed, the actions
-   * really done by the user, and if the activity was finally solved or not.
-   * @returns {number}
-   */
-  getPrecision() {
-    let result = 0;
-    if (this.closed && this.minActions > 0 && this.numActions > 0) {
-      if (this.solved) {
-        if (this.numActions < this.minActions)
-          result = 100;
-        else
-          result = Math.round(this.minActions * 100 / this.numActions);
-      } else
-        result = Math.round(100 * (this.score * this.score) / (this.minActions * this.numActions));
-    }
-    return result;
-  }
-
-  /**
-   * This method should be called when the current activity finishes. Data about user's final results
-   * on the activity will then be saved.
-   * @param {number} score - The final score, usually in a 0-100 scale.
-   * @param {number} numActions - The total number of actions done by the user to solve the activity
-   * @param {boolean} solved - `true` if the activity was finally solved, `false` otherwise.
-   */
-  endActivity(score, numActions, solved) {
-    if (!this.closed) {
-      this.solved = solved;
-      this.numActions = numActions;
-      this.score = score;
-      this.closeActivity();
-    }
-  }
-}
-
-Object.assign(ActivityReg.prototype, {
-  /**
-   * Name of the associated activity
-   * @name module:report/ActivityReg.ActivityReg#name
-   * @type {string} */
-  name: '',
-  /**
-   * Optional code assigned to this activity, used for later filtering
-   * @name module:report/ActivityReg.ActivityReg#code
-   * @type {string} */
-  code: '',
-  /**
-   * Timestamp when the user starts playing the activity
-   * @name module:report/ActivityReg.ActivityReg#startTime
-   * @type {number} */
-  startTime: 0,
-  /**
-   * Total time spent by the user in the activity, measured in milliseconds
-   * @name module:report/ActivityReg.ActivityReg#totalTime
-   * @type {number} */
-  totalTime: 0,
-  /**
-   * Collection of actions done by the user while playing the activity
-   * @name module:report/ActivityReg.ActivityReg#actions
-   * @type {module:report/ActionReg.ActionReg[]} */
-  actions: [],
-  /**
-   * `true` only when the user has finished and solved the activity
-   * @name module:report/ActivityReg.ActivityReg#solved
-   * @type {boolean} */
-  solved: false,
-  /**
-   * Last {@link module:report/ActionReg.ActionReg ActionReg} performed by the user in this activity
-   * @name module:report/ActivityReg.ActivityReg#lastAction
-   * @type {module:report/ActionReg.ActionReg} */
-  lastAction: null,
-  /**
-   * Final score obtained by the current user in this activity
-   * @name module:report/ActivityReg.ActivityReg#score
-   * @type {number} */
-  score: 0,
-  /**
-   * Minimum number of actions needed to solve the activity
-   * @name module:report/ActivityReg.ActivityReg#minActions
-   * @type {number} */
-  minActions: 0,
-  /**
-   * `true` when the activity has finished, `false` for the activity that is currently playing
-   * @name module:report/ActivityReg.ActivityReg#closed
-   * @type {boolean} */
-  closed: false,
-  /**
-   * `true` when this type of activity should record specific actions done by the users
-   * @name module:report/ActivityReg.ActivityReg#reportActions
-   * @type {boolean} */
-  reportActions: false,
-  /**
-   * Number of actions done by the user playing this activity
-   * @name module:report/ActivityReg.ActivityReg#numActions
-   * @type {number} */
-  numActions: 0,
-});
-
-export default ActivityReg;