Browse Source

Exported experiment mixins api, emphasized texts, fixed trees, finished creante an expe

rigwild 1 year ago
parent
commit
86ef782f2c

+ 1 - 0
DOCUMENTATION/00-home.md

@@ -8,3 +8,4 @@
 | 02 | [npm scripts](./02-npm-scripts.md) | Details the available npm scripts |
 | 03 | [npm dependencies](./03-npm-dependencies.md) | Details the npm dependencies |
 | 04 | [Create an experiment](./04-create-an-experiment.md) | Details how to fully create an experiment |
+| 05 | [Experiment mixins API](./05-experiment-mixins-api.md) | Details available data and methods in the experiments mixins |

+ 1 - 1
DOCUMENTATION/02-npm-scripts.md

@@ -2,7 +2,7 @@
 
 This wiki page details the available npm scripts. These scripts are located in the `scripts` category of [`/package.json`](../package.json).
 
-Keep in mind that this documentation uses the `yarn` command but using `npm` instead will have the same effect.
+Keep in mind that this documentation uses the `yarn` command but **using `npm` instead will have the same effect**.
 
 ## Summary
 

+ 3 - 3
DOCUMENTATION/03-npm-dependencies.md

@@ -18,7 +18,7 @@ These dependencies are mostly used by the server.
 | `body-parser` | [npm](https://www.npmjs.com/package/body-parser) | Parse HTTP request body |
 | `compression` | [npm](https://www.npmjs.com/package/compression) | Turn HTTP server's gzip compression on |
 | `core-js` | [npm](https://www.npmjs.com/package/core-js) | Dependency of Babel (in `@vue/cli-service`) |
-| `cors` | [npm](https://www.npmjs.com/package/cors) | Turn Cross-Origin Resource Sharing (CORS) HTTP header on |
+| `cors` | [npm](https://www.npmjs.com/package/cors) | Turn [Cross-Origin Resource Sharing (CORS)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) HTTP header on |
 | `cron` | [npm](https://www.npmjs.com/package/cron) | Cron integrated in Node.js, used for the extracts remover service |
 | `esm` | [npm](https://www.npmjs.com/package/esm) | Node.js JavaScript module loader. Used for the server |
 | `express` | [npm](https://www.npmjs.com/package/express) | API framework |
@@ -31,9 +31,9 @@ These dependencies are mostly used by the server.
 | `winston` | [npm](https://www.npmjs.com/package/winston) | Server logger |
 
 ## Development dependencies
-These dependencies are here for developers only. They contain the web application setup, optimized builders and API automated tests. It also contains API documentation generator and `ESLint` with its plugins.
+These dependencies are here for **developers only**. They contain the web application setup, optimized builders and API automated tests. It also contains API documentation generator and `ESLint` with its plugins.
 
-When the web application files are builded, `Vue.js` and its plugins are not necessary. In fact, the build output will contain portable HTML, CSS and JavaScript.
+When the web application files are builded, `Vue.js` and its plugins are not necessary. In fact, **the build output will contain portable HTML, CSS and JavaScript**.
 
 | Name | Link | Description |
 | --- | --- | --- |

+ 46 - 91
DOCUMENTATION/04-create-an-experiment.md

@@ -7,17 +7,11 @@ This wiki page details how to fully create an experiment.
  - [Prerequisites](#prerequisites)
  - [Experiment file tree](#experiment-file-tree)
  - [Experiment creation](#experiment-creation)
-   - [Experiment initialization](#experiment-initialization)
-   - [Experiment configuration](#experiment-configuration)
- - [Experiment mixins API](#experiment-mixins-api)
-   - [ExperimentBase](#experimentbase)
-   - [ExperimentBaseAreSameImages](#experimentbasearesameimages)
-   - [ExperimentBaseExtracts](#experimentbaseextracts)
 
 ---
 
 ## Prerequisites
-To learn how to create an experiment, you first need to know how [Vue.js](https://vuejs.org/v2/guide/) works.
+To learn how to create an experiment, **you first need to know how [Vue.js](https://vuejs.org/v2/guide/) works**.
 
 If you want to use the same style as the application, here is the [Vuetify documentation](https://vuetifyjs.com/en/getting-started/quick-start).
 
@@ -42,114 +36,75 @@ The complete `/src` directory file tree can be found here: [Application file tre
     │   └── index.js                                 || Main routing logic
     └── views                                        || Application views (pages)
         └── Experiments                              || Experiments
+            ├── _template_.vue                       || Experiment minimal template
             ├── AreSameImagesRandom.vue              || Two random quality images (versus)
-            ├── AreSameImagesReferenceOneExtract.vue || Two reference images, one has a random quality extract (versus)
             ├── AreSameImagesReference.vue           || One random quality image, one reference image (versus)
-            └── MatchExtractsWithReference.vue       || Lowest quality extracts, match them to reference image
+            ├── AreSameImagesReferenceOneExtract.vue || Two reference images, one has a random quality extract (versus)
+            ├── IsImageCorrect.vue                   || An image cut in half horizontally, tell if it looks normal
+            ├── IsImageCorrectOneExtract.vue         || An image cut in half horizontally, tell if it looks normal
+            ├── MatchExtractsWithReference.vue       || Lowest quality extracts, match them to reference image
+            └── PercentQualityRandom.vue             || Random quality image, tell how high the quality is
 ```
 
 ## Experiment creation
-
-### Experiment initialization
-When creating an experiment
+Follow the following steps to create a new experiment.
 
 ##### 1. Choose an experiment name, it must be in [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case)
+
 ##### 2. Create a new `<YourExperimentName>.vue` file in the [`/src/views/Experiments`](../src/views/Experiments) directory
 
 ##### 3. Link your experiment to the [Vue.js routing system](https://router.vuejs.org/)
+
 Create a new entry in the [`/src/router/experiments.js`](../src/router/experiments.js) file following this structure:
 
 ```js
 {
-  path: '/experiments/YourExperimentName/:sceneName',
-  name: 'YourExperimentName',
-  component: () => import('@/views/Experiments/YourExperimentName'),
+  path: '/experiments/<YourExperimentName>/:sceneName',
+  name: '<YourExperimentName>',
+  component: () => import('@/views/Experiments/<YourExperimentName>'),
   props: true,
   meta: {
-    fullName: 'The visible name of your experiment'
+    fullName: '<The visible name of your experiment>'
   }
 }
 ```
 
 ##### 4. Choose or create the experiment mixin
-`TODO: finish this part`
 
-An experiment mixin is a subset of functions or data that can be used in a type of experiment.
+An experiment mixin is a subset of data or methods that can be used in a type of experiment. The [`ExperimentBase`](./05-experiment-mixins-api.md#experimentbase) mixin is the bare minimum to include in your experiment, it is mandatory.
+
+Keep in mind that if the mixin you are using already extends [`ExperimentBase`](./05-experiment-mixins-api.md#experimentbase), you do not need to import it a second time.
+
+See [Experiment mixins API](./05-experiment-mixins-api.md) to check data and methods available to you. You need to use the `this` keyword in any Vue methods/templates to use these features.
+
+##### 5. Create the experiment configuration
+
+Create a new entry in the `experiments` object of the [`/experimentConfig.default.js`](../experimentConfig.default.js) file following this structure:
+
+```js
+YourExperimentName: {
+  mixins: [mixins.ExperimentBase], // Your used mixins
+  defaultConfig: {                 // Configuration used for all scenes
+    // Data to apply to any scenes of the experiment
+    // maxTestCount: 5
+  },
+  scenesConfig: {                  // Scene-specific configuration
+    // Data to apply to only some scenes
+    // bathroom: {
+    //   maxTestCount: 5
+    // }
+  },
+  availableScenes: {
+    whitelist: null,               // Whitelist available scenes (String[]). If null, takes all scenes
+    blacklist: null                // Remove scenes (String[])
+  }
+}
+```
+
+You can add any data in `defaultConfig` and `scenesConfig` properties, It will get merged with your experiment data (the configuration file has more priority, if you have an experiment data with the same key, it will replace it).
 
+##### 6. Actual experiment creation
 
-##### 5. Actual experiment creation
 Copy the minimal experiment template [`/src/views/Experiments/_template.vue`](../src/views/Experiments/_template.vue) content to your new experiment.
 
 You are all set! You can now develop your own experiment.
-See [Experiment mixins API](#experiment-mixins-api) to check data and methods available from your selected parent mixins using the `this` keyword in any Vue methods/templates.
-
-### Experiment configuration
-`TODO: finish this part`
-
-## Experiment mixins API
-### ExperimentBase
-File: [`/src/mixins/ExperimentBase.vue`](../src/mixins/ExperimentBase.vue)
-
-Extends: []
-
-This mixin is mandatory. If you want to create a new mixin, use this mixin in your mixin.
-
-When drawing the tree from top mixins to the experiment itself, `ExperimentBase` must be the very top parent.
-
-| Data | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| `loadingMessage` | `String` | `null` | Message to display while loading the application. `null` = not loading
-| `loadingErrorMessage` |  `String` | `null` | Message to display when the application failed to load. `null` = no loading errror
-| `qualities` | `Number[]` | `null` | List of qualities for the current scene
-
-| Method | Return type | Description |
-| ------ | ----------- | ----------- |
-| `loadProgress()` | `void` | Load progress from store into local state |
-| `saveProgress()` | `void` | Save progress from local state into store |
-| `loadConfig()` | `void` | Load a config object into the local state |
-| `finishExperiment()` | `void` | Finish an experiment, sending full data to the server . Don't forget to surcharge this function when using this mixin to add more data! |
-| `getQualitiesList()` | `Promise<void>` | Load qualities list from the API |
-| `getImage(quality: Number)` | `Promise<Object>` | Load an image from the API |
-| `sendMessage({ msgId: String, msg: Object })` | `void` | Send a message using `/experimentCollect` API route, your message will be stored in the database. Message IDs are listed in [`/config.messageId.js`](../config.messageId.js) |
-| `setExperimentFinished([done=true: Boolean])` | `void` | Set the current experiment as finished in the browser's cache |
-
-### ExperimentBaseAreSameImages
-File: [`/src/mixins/ExperimentBaseAreSameImages.vue`](../src/mixins/ExperimentBaseAreSameImages.vue)
-
-Extends: [[ExperimentBase](#experimentbase)]
-
-| Data | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| `maxTestCount` | `Number` | `null` | The total number of tests to pass for this scene |
-| `testCount` | `Number` | `1` | Passed tests count |
-| `image1` | `Object` | `null` | One of the two images |
-| `image2` | `Object` | `null` | One of the two images |
-
-| Method | Return type | Description |
-| ------ | ----------- | ----------- |
-| `scrollToChoiceButtons()` | `void` | Scroll the page to the answer buttons |
-| `getTest(leftQuality: Number, rightQuality: Number)` | `Promise<Object>` | Load a test using provided qualities |
-| `areTheSameAction(areTheSame: Boolean, getTestFn: Function, additionalData: any)` | `Promise<Object>` | Answer to the versus. `getTestFn` shoud be an async function that returns an object matching `{ image1: Object, image2: Object }`. additionalData is the experiment-specific content you want to send to the database  |
-| `finishExperiment()` | `void` | Finish an experiment |
-
-### ExperimentBaseExtracts
-File: [`/src/mixins/ExperimentBaseExtracts.vue`](../src/mixins/ExperimentBaseExtracts.vue)
-
-Extends: [[ExperimentBase](#experimentbase)]
-
-| Data | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| `extractConfig` | `Object` | `{ x=null: Number, y=null: Number }` | Used configuration to cut the image |
-| `extracts` | `Object[]` | `[]` | List of extracts of the cutted image |
-| `extractsInfos` | `Object` | `null` | Informations on the cutted image |
-| `showHoverBorder` | `Boolean` | `null` | Should the extracts be hoverable (white rectangle around the extract) |
-| `lockConfig` | `Boolean` | `null` | Should the extract configuration be editable |
-
-| Method | Return type | Description |
-| ------ | ----------- | ----------- |
-| `getExtracts([quality='min']: Number|String)` | `Promise<Object>` | Load image extracts using the provided quality and extract configuration |
-| `setExtractConfig(config: Object, [configuratorRef: Object])` | `Promise<Object>` | Change the extract configuration. It loads the new extracts. `config` is the new extracts configuration to use. If `configuratorRef` is provided, it will extract the extracts configurator |
-| `extractAction(event: MouseEvent, extractObj: Object)` | `Promise<void>` | Used when clicking on an extract. `event` is the mouse event (left/right click). `extractObj` is the object corresponding to the clicked extract (from the extracts array) |
-| `getExtractFullObject(extractsApiObj: Object)` | `Promise<Object>` | Takes the API image extracts response and apply more data to the extracts (like next/prec quality, zone, index or full link to image) |
-| `getClickDataObject(event, extractObj, action)` | `Object` | Calculate data on clicked event. Will get the click position on the responsive image, calculate the ratio to the real-sized image. It returns the full message sent when clicking on an extract |
-| `finishExperiment()` | `void` | Finish an experiment sending final experiment data |

+ 78 - 0
DOCUMENTATION/05-experiment-mixins-api.md

@@ -0,0 +1,78 @@
+# Experiment mixins API
+
+This wiki page details available data and methods in the experiments mixins.
+
+## Summary
+
+ - [ExperimentBase](#experimentbase)
+ - [ExperimentBaseAreSameImages](#experimentbasearesameimages)
+ - [ExperimentBaseExtracts](#experimentbaseextracts)
+
+---
+
+## ExperimentBase
+File: [`/src/mixins/ExperimentBase.vue`](../src/mixins/ExperimentBase.vue)
+
+Extends: None
+
+**This mixin is mandatory**. If you want to create a new mixin, **use this mixin in your mixin**.
+
+When drawing the tree from top mixins to the experiment itself, **`ExperimentBase` must be the very top parent**.
+
+| Data | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `loadingMessage` | `String` | `null` | Message to display while loading the application. `null` = not loading
+| `loadingErrorMessage` |  `String` | `null` | Message to display when the application failed to load. `null` = no loading errror
+| `qualities` | `Number[]` | `null` | List of qualities for the current scene
+
+| Method | Return type | Description |
+| ------ | ----------- | ----------- |
+| `loadProgress()` | `void` | Load progress from store into local state |
+| `saveProgress()` | `void` | Save progress from local state into store |
+| `loadConfig()` | `void` | Load a config object into the local state |
+| `finishExperiment()` | `void` | Finish an experiment, sending full data to the server . Don't forget to surcharge this function when using this mixin to add more data! |
+| `getQualitiesList()` | `Promise<void>` | Load qualities list from the API |
+| `getImage(quality: Number)` | `Promise<Object>` | Load an image from the API |
+| `sendMessage({ msgId: String, msg: Object })` | `void` | Send a message using `/experimentCollect` API route, your message will be stored in the database. Message IDs are listed in [`/config.messageId.js`](../config.messageId.js) |
+| `setExperimentFinished([done=true: Boolean])` | `void` | Set the current experiment as finished in the browser's cache |
+
+## ExperimentBaseAreSameImages
+File: [`/src/mixins/ExperimentBaseAreSameImages.vue`](../src/mixins/ExperimentBaseAreSameImages.vue)
+
+Extends: [[`ExperimentBase`](#experimentbase)]
+
+| Data | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `maxTestCount` | `Number` | `null` | The total number of tests to pass for this scene |
+| `testCount` | `Number` | `1` | Passed tests count |
+| `image1` | `Object` | `null` | One of the two images |
+| `image2` | `Object` | `null` | One of the two images |
+
+| Method | Return type | Description |
+| ------ | ----------- | ----------- |
+| `scrollToChoiceButtons()` | `void` | Scroll the page to the answer buttons |
+| `getTest(leftQuality: Number, rightQuality: Number)` | `Promise<Object>` | Load a test using provided qualities |
+| `areTheSameAction(areTheSame: Boolean, getTestFn: Function, additionalData: any)` | `Promise<Object>` | Answer to the versus. `getTestFn` shoud be an async function that returns an object matching `{ image1: Object, image2: Object }`. additionalData is the experiment-specific content you want to send to the database  |
+| `finishExperiment()` | `void` | Finish an experiment |
+
+## ExperimentBaseExtracts
+File: [`/src/mixins/ExperimentBaseExtracts.vue`](../src/mixins/ExperimentBaseExtracts.vue)
+
+Extends: [[`ExperimentBase`](#experimentbase)]
+
+| Data | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `extractConfig` | `Object` | `{ x=null: Number, y=null: Number }` | Used configuration to cut the image |
+| `extracts` | `Object[]` | `[]` | List of extracts of the cutted image |
+| `extractsInfos` | `Object` | `null` | Informations on the cutted image |
+| `showHoverBorder` | `Boolean` | `null` | Should the extracts be hoverable (white rectangle around the extract) |
+| `lockConfig` | `Boolean` | `null` | Should the extract configuration be editable |
+
+| Method | Return type | Description |
+| ------ | ----------- | ----------- |
+| `getExtracts([quality='min']: Number|String)` | `Promise<Object>` | Load image extracts using the provided quality and extract configuration |
+| `setExtractConfig(config: Object, [configuratorRef: Object])` | `Promise<Object>` | Change the extract configuration. It loads the new extracts. `config` is the new extracts configuration to use. If `configuratorRef` is provided, it will extract the extracts configurator |
+| `extractAction(event: MouseEvent, extractObj: Object)` | `Promise<void>` | Used when clicking on an extract. `event` is the mouse event (left/right click). `extractObj` is the object corresponding to the clicked extract (from the extracts array) |
+| `getExtractFullObject(extractsApiObj: Object)` | `Promise<Object>` | Takes the API image extracts response and apply more data to the extracts (like next/prec quality, zone, index or full link to image) |
+| `getClickDataObject(event, extractObj, action)` | `Object` | Calculate data on clicked event. Will get the click position on the responsive image, calculate the ratio to the real-sized image. It returns the full message sent when clicking on an extract |
+| `finishExperiment()` | `void` | Finish an experiment sending final experiment data |