Merge pull request #1 from labinthewild/v2-dev-base

Improvements to template #2

docs/1-Installation.md

@@ -6,8 +6,8 @@ This page aims to help you to get the template running on your machine.
 
 You will need Node and NPM to build and run this bundle. See [this link](https://nodejs.org/en/) for instructions on installing Node and NPM.
 
-This bundle has been tested on Ubuntu 23.04.
-*If you used any other platform, please add it here and submit a pull request! ;)*
+This bundle has been tested on Ubuntu 22+ and macOS 12.4.
+(*If you used any other platform, please add it here and submit a pull request! ;)*
 
 
 ## Steps
@@ -20,11 +20,13 @@ Navigate to the `src` directory:
 ```
 cd LITW-study-templates/src
 ```
-Navigate to the `study-base` directory:
+COPY the `study-base` folder to one that names `my-study`. Then, navigate to `my-study` directory:
 ```
-cd study-base
+cp -r study-base my-study
+cd my-study
 ```
 Install dependencies:
+(OBS: You may want to edit the `package.json` file to change the name, version, and other metadata of your study.)
 ```
 npm install
 ```
@@ -37,11 +39,15 @@ Start the dev-server:
 ```
 npm run devserver
 ```
-You should now to be able to open access the dev-server location now: `http://localhost:8080/`.
+You should now to be able to open access the dev-server location now: `http://localhost:8080/my-study/`.
+Congrats, your study have a home!
 
 ## Study Template & Examples
 
 The loaded page served through your dev-server should show you some options of study templates and examples.
-(At this point in time - `V2-alpha` - we are only presenting the `study-base` template.)
+At this point in time we only have the `study-base` and our beloved `study-cat` packed in this template.
+You will see in the following steps of this tutorial, though, that you have many individual template slides that you can use to start your own.
 
+The next step for us now is to understand the basics of a [LITW study](2-CodeExecutionOverview.md) to allow for
+quicker and stable changes to your brand-new study.
 

docs/2-CodeExecutionOverview.md

@@ -1,54 +1,65 @@
 # Code Overview
 
-With this quick overview you'll understand the main concepts and files related to a page in the template.
+With this quick overview you'll understand the main concepts and entities that compose a LITW study using this template.
 
-![template_coding_overview](img/template-coding-overview.jpg "Template coding overview: in the center the study manager box, which manages the index HTML page to show pages based on a pre-configure timeline.")
+![template_coding_overview](img/LITW-Study-Architecture.png "Study Architecture: in the center the study manager, which manipulates the index HTML page to show interactions pre-configure in a timeline.")0
 
 In this diagram you can see the following entities:
 
-  * **study.js:** This is the workflow's manager. It is composed by a set of functions normally associated with presenting a page to the study's participants, collecting and saving necessary data, and leaving space for the next page.
-  * **templates:** Is a folder full of HTML page structures (written in [Handlebars.js](https://handlebarsjs.com/)) containing the content presented to the study participant.
-  * **index.html:** This is the page that the study participant is interacting with all the time. Its structure -- based on a list of empty DIVs -- is manipulated in runtime by the `study.js` workflow manager.
-  * **timeline:** A timeline containing all the steps/slides that compose the study. We add each slide to the timeline using timeline.push. In general each step/slide is a page that presents and/or collects data. Under the hood, we use the awesome [JsPsych framework](https://www.jspsych.org/7.3/overview/timeline/) --although an older version -- to manage that.
-  * **API:** This is a module created to support simple data management. In general, all you need to do is call a function that will save JSON objects.
+  * **study-manager.js:** This is the core of a LITW study: the workflow manager. It is responsible for loading and manipulating the web-pages and JS functions that compose the interface with participants.
+  * **page templates:** These are a set of HTML page structures (written in [Handlebars.js](https://handlebarsjs.com/) or whatever way you'd prefer) containing the content presented to the study participant.
+  * **timeline:** The manager uses a timeline to organize the study pages in a sequence. In general, in each step a page is presented and some data is collected. Under the hood, we use the awesome [JsPsych framework](https://www.jspsych.org/7.3/overview/timeline/) --although an older version -- to manage that.
+  * **index.html:** As usual, this is the main web page that the study participant is interacting with all the time. Its initial structure defines the needed resources (like CSS and JS) and some empty DIVs that will be manipulated by the Study Manager.
+  * **API:** This is a *separate system* we created to simplify data management. You'll not have to bother about it: all you need to do is to call JS functions through our JS libraries.
+  * **Study Server**: This is another *separate system* that, in its core, is simply a web-server that serves (dah!) all needed resources by the study. Our implementation has some special calls that helps you with data management.
+  * **Browser:** This is the participant's web browser, fundamentally, the client part of any web-based system.
 
 Is it clearer now?
 (*If not, please [start a Q&A](https://github.com/labinthewild/LITW-study-templates/discussions/categories/q-a) thread!*)
 
 ## The timeline
 
-Based on this code structure, one of the core code components you will want to examine first is the `configureStudy()` function inside the `study.js` file!
+Based on this architecture, one of the core code components you will want to examine is the `configureStudy()` function inside the `study-manager.js` file!
 This function exists to simply configure the timeline of the study by adding *slides* to it.
 
 Here is the basics:
 
-```
-var timeline = [] ...
+``` javascript
+var introTemplate = require("../templates/introduction.html");
+//...
+var timeline = [], 
+params = {
+    slides: {
+        INTRODUCTION: {
+            name: "introduction",
+            type: "display-slide",
+            template: introTemplate,
+            display_element: $("#intro"),
+            display_next_button: false,
+        }
+        //...
+    }
+}
 
 function configureStudy() {
-    // ******* BEGIN STUDY PROGRESSION ******** //
-    timeline.push({
-        name: "informed_consent",
-        type: "display-slide",
-        template: irbTemplate,
-        display_element: $("#irb"),
-        display_next_button: false
-    });
-    timeline.push({ ... });
-    ...
+    timeline.push(params.slides.INTRODUCTION);
+    // ...
 }
 ```
 
 As you can see, the timeline is nothing more than an Array and the `configureStudy` is a sequence of `push` calls to add slides to it.
-Every slide though, has to be a JS object that will pass specific information to the slide. At this point, we mostly will use the `display-slide` type that requires:
+Every slide though is a JS object that will configure the slide in a way our study engine understand how to present it.
+Here is the basics of a LITW slide configuration:
 
-  * a String for its `name`;
-  * a Handlebar `template` that will be shown as the HTML page;
-  * and the `DIV ID` of the specific slide you're working with that matches the `DIV ID` present in your `index.html` where you want to show this page.
+  * a String for its `name`; (used, for instance, to track when the slide was accessed.)
+  * a Type of the page: Most of the time, you will use the `display-slide` type which manages a lot of tracking and loading specifics for LTIW studies.
+  * a Handlebar `template` (i.e., an HTML DIV specifying the page content); (the first like in the code shows how to load one.)
+  * the `DIV ID` -- present in your `index.html` -- where you want to inject this page.
+  * and finally the "optional" configuration `display_next_button` which can be used to hide the next button. This is generally useful if you want to trigger the next slide command in a special way.
 
-An important thing to note is that you must have the divs for the slides added to your `index.html` page in order to use them in your timeline.
+An **important** thing to note is that you must have the DIVs for the slides added to your `index.html` page in order to use them in your timeline.
 
-Additionally, the display_next_button field has to do with the arrow that is shown on the screen allowing a participant to progress to the next slide.
+By definition, only one slide will be shown at a time. As soon as the NEXT button is "clicked" the LITW study engine will switch what is shown.
 
 ## Hands-on time!
 
@@ -58,3 +69,4 @@ We've created the following HowTo tasks to warm you up:
   * [How to change a page's text?](3-ChangePageText.md)
   * [How to create a new study page?](4-AddNewPage.md)
   * [How to create a survey?](5-CreateSurvey.md)
+  * [How to create dynamic pages?](6-LoadingComplexSlides-TheResultsPageCase.md)

docs/3-ChangePageText.md

@@ -1,32 +1,56 @@
 # How to... Change a page's text?
 
-We hope that if you are here, you already have [installed](1-Installation.md) our code template and understood its [code structure](2-CodeExecutionOverview.md).
-If that is the case, changing the content in a slide should be as easy as changing the content in an HTML page. Let us do just that in the `study-base` study template folder!
+If you already here, it should be the case that you have [installed the base code for your study](1-Installation.md) and understands the [LITW study code structure](2-CodeExecutionOverview.md).
 
-## Configure the IRB page
+Now, changing the content in a slide should be as easy as changing the content in an HTML page. Let us do just that in code for `your-study` (of if you prefer, just use the `study-base`.)
+The main lesson about implementing your own study is: **if you need to change anything from a resource offered in our template, copy the file first to your own study folder and chage that copy.** 
+NEVER change files outside your study folder as they will not be deployed to our servers!!!
 
-In our base template, you have probably seen, first thing, a simple **Informed Consent** page. Should be something like this:
+## Change the Introduction Page
 
-![Informed Consent](img/template-irb.png "The informed consent is a simple text HTML page with a title and a list of basic information about the study!")
+In our base template, you have probably seen that the first page of the study is an **Introduction Page**. Should be something like this:
 
-Now, you see that the title is kind of generic. What if we change it to something more specific, like `Get your mind blown with my LabintheWild Study!`.
-If you know enough of HTML and about the `timeline` configured in the `study-model.js` file, you should see that the first slide we show is called `irbTemplate` which is a variable created on the same JS file like this:
+![Introduction Page](img/template-intro.png "The LITW study template introduction page with some boilerplate information about it!")
+
+Now, you see that the title is kind of generic. 
+What if we change it to something more specific, like `Learn about your XYZ with this LabintheWild Study!`
+
+If you know enough of HTML you can imagine that this title is likely a `<h>` tag somewhere, right? Let us find where!
+
+If you go to the `study-magager.js` file, you can find what HTML file we should look for. 
+On the first lines of that file, you can see a sequence of lines that basically load all the used HTML templates like the one we want to change:
 
 ```javascript
-var irbTemplate = require("../templates/irb.html");
+var introTemplate = require("../templates/introduction.html");
+```
+
+Knowing that, we can go to the `introduction.html` file and change it! 
+BUT BEFORE THAT, remember: if you are changing a file from outside of your study folder, you should first COPY it inside your study folder!
+Something like:
+
+```bash
+mkdir my-study/pages
+cp templates/introduction.html my-study/pages
 ```
+(Obs.: I like to call this folder inside my study **pages** instead of **templates** but this is only a semantic preference.)
 
-Knowing that, we can go to the `irb.html` file and change it! But instead of seeing simple `H1` and `p` nodes in the page, you will find something slightly different like this:
+Now that you have your own copy of that page, you should change the reference inside the `study-manager` to point to the new file: `./pages/introduction.html` and open the file for edition!
+
+At the top of this file, you will see something like this!
 
 ```html
-<h2 class="bolded-blue" data-i18n='litw-irb-header'></h2>
-<p data-i18n='litw-irb-subheader-1'></p>
-<p><em data-i18n='litw-irb-subheader-2'></em></p>
+ <div class="row">
+     <div class="col d-flex justify-content-center">
+         <h2 class="bolded-blue" data-i18n="litw-study-title"></h2>
+     </div>
+ </div>
 ```
+Well! That may be a bit of a surprise that the **H2** tag does not directly have the text, but a reference to it in the `data-i18n` parameter. 
+Why do we use this `data-i18n` instead of inserting text directly on the HTML page? That is because we are VERY pro internalization, and even if you do not intend to translate your study right now, we believe everything should be built to make that very easy!
 
-Why do we use this `data-i18n` instead of inserting text directly on the HTML page? That is because we are VERY pro-internalization, and even if you do not intend to translate your study right now, we believe everything should be built to make that very easy!
 We use the [Wikipedia's i18n library](https://github.com/wikimedia/jquery.i18n) to make translations almost transparent to you and the study participants.
-All you need to do is to open the language file (in this case `en.json`) inside the `i18n` folder of your study. Here is a snippet of it:
+All you need to do is to open the language file and change the entry related to the `litw-study-title` key use by the header HTML tag. 
+In this case, your study English language file is `i18n/en.json`, and should look like this: 
 
 ```json
 {
@@ -39,27 +63,28 @@ All you need to do is to open the language file (in this case `en.json`) inside
   },
   "litw-template-title": "This is your Project",
   "litw-template-loading": "Loading...",
-  "litw-irb-header": "Welcome to my LabintheWild Study!",
-  ...
+  "litw-study-title": "This is a very interesting study",
+  "...": "..."
 }
 ```
 All it is, is a `key:value` JSON file with all the strings you need to use in the HTML of your study.
-All you have to do to change the text displayed on the page is to change the value of your desired key:value pair to be whatever you want it to be!
-Now, considering we want to change the text above that has the `litw-irb-header` key, go ahead and change it in the JSON file.
+As you can imagine, you just to need to change the title to whatever string you want and same it! 
 
-## Check the changes
+## Check this worked!
 
 To see the changes -- any changes from now on -- we recommend to:
-1. stop the `dev-server` if it is running (Ctrl+C on terminal)
+1. stop the `devserver` if it is running (Ctrl+C on terminal)
 2. build your study (as described [here](1-Installation.md#steps))
-3. run the `dev-server`
-4. access the study folder on a browser windows... something like `http://localhost:8080/study-base/index.html`!
+3. run the `devserver` and reload your study on the browser (as shown in the same installation instructions)
 
 You should now see the new title of your study.
 
 ## What now?
 
-We're so excited you got here! Now that you know the basics of a study slide, maybe you want to [add a whole new page](4-AddNewPage.md) to your study?
+Now that you know that every study page is just an HTML template that you can copy and change, you can make a bunch of improvements to your study. 
+
+What if you need to add a completely new page? 
+Check this [next tutorial page](4-AddNewPage.md)!
 
 ## What if this did not work?
 

docs/6-LoadingComplexSlides-TheResultsPageCase.md

@@ -0,0 +1,16 @@
+# Loading Complex Pages - The Results Page Case
+
+As discussed in the [Code Architecture](2-CodeExecutionOverview.md) part of this tutorial, implementing a LITW study is basically implementing a set of HTML templates and adding them to a timeline.
+Up to this point, though, we have only worked with static templates, meaning, HTML pages that are fully defined at "coding time".
+There are though, some complex pages, that you may want to change depending on some specific data that was produced on "participantion time."
+For example, you may want to think that, if a participant said they are from a specific country, you want to show a flag of that nation in a page.
+
+In this tutorial, we will see how to implement such dynamic pages.
+
+## Dynamic pages
+
+**TODO**
+
+## The Results Page
+
+**TODO**

src/css/litw-styles.css

@@ -253,7 +253,7 @@ textarea.comments-box, textarea.comments_box {
 }
 
 .litw-study-link-img {
-	width: 200px;
+	width: 100%;
 }
 .litw-study-link-description {
 }