You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Nov 22, 2022. It is now read-only.
**Thank you so much for checking out lab.js!** It's a great pleasure to have you
5
-
here, and we hope you will enjoy building experiments using this little library
6
-
as much as we have enjoyed creating it.
7
-
8
-
The purpose of this initial tutorial is to get you up to speed as quickly as
9
-
possible. We'll have you building a very simple experiment in the next half hour
10
-
or so, and we'll examine more details in the following parts of the tutorial.
11
-
12
-
You'll need a browser, and a basic understanding of how web pages are built
13
-
using ``HTML``. In addition, a good text editor with syntax highlighting can be
14
-
an enormous support: It helps us distinguish the different parts of our code
15
-
visually. If you're using a text editor already in your daily work, we'd
16
-
recommend to stick to that for the moment. If you haven't used a text editor
17
-
before, we would encourage you to try out `Atom <https://atom.io/>`_, which
18
-
works great out of the box.
19
-
20
-
If you run into difficulties in the tutorial, that's our fault: Please let us
21
-
know how we can support you! We are also constantly trying to make the tutorial
22
-
clearer and more helpful -- if you have comments or suggestions, we would love
23
-
to hear them!
4
+
**So how do you build a ``lab.js`` study in pure code?** This is what we'd like to show you in the following, by building a very simple experiment. We'll cover more details in the subsequent parts of the tutorial.
5
+
6
+
First, **let's get you set up**: You'll need a browser, and a basic understanding of how web pages are built using ``HTML``. In addition, a good text editor with syntax highlighting can be an enormous support: It helps us distinguish the different parts of our code visually. If you're using a text editor already in your daily work, we'd recommend to stick to that for the moment. If you haven't used a text editor before, we would encourage you to try out `Visual Studio Code <https://code.visualstudio.com/>`_, which works great out of the box.
7
+
8
+
If you run into difficulties in the tutorial, that's our fault: **Please let us know how we can assist you!** The ``lab.js`` community convenes in the `community support channel <lab.js.org/resources/support/>`_, where you'll find kind folks to help answer questions and discuss how things work. You're very warmly invited to join, and after going through this tutorial, you'll be able to help others, too! Finally, we are also constantly trying to make the tutorial clearer and more helpful -- if you have comments or suggestions, we would genuinely love to hear them.
24
9
25
10
.. contents:: Contents
26
11
:local:
@@ -40,90 +25,55 @@ to hear them!
40
25
Downloading the starter kit
41
26
---------------------------
42
27
43
-
To get up and running, the first thing you'll need to do is download the starter
44
-
kit attached to `the latest release <https://github.com/FelixHenninger/lab.js/releases>`_
45
-
of ``lab.js``.
28
+
To get up and running, the first thing you'll need to do is **download the starter kit** attached to `the latest release <https://github.com/felixhenninger/lab.js/releases>`_ of ``lab.js``. The starter kit is a zip archive containing all necessary files for building a simple experiment. Please extract it in a convenient location on your computer, and navigate to the folder containing the extracted files. That's it!
46
29
47
-
The starter kit is a zip archive containing all necessary files for building a
48
-
simple experiment. Please extract it in a convenient location on your computer,
49
-
and navigate to the folder containing the extracted files. That's it!
50
-
51
-
Whenever you are building a new experiment in the future, you can start from a
52
-
clean slate by downloading and building upon the latest starter kit. As you
53
-
gather more experience, you might build your own starter kit using the code that
54
-
helps you get to speed quickest -- you are by no means limited to the template
55
-
provided.
30
+
Whenever you are building a new experiment in the future, you can start from a clean slate by downloading and building upon the latest starter kit. As you gather more experience, you might build your own starter kit using the code that helps you get to speed quickest -- you are by no means limited to the template provided. However, **you'll always need the files in the ``lib`` folder of the starter kit**, because that's where the ``lab.js`` library files live.
56
31
57
32
A web page about to be turned into an experiment
58
33
------------------------------------------------
59
34
60
-
Among the extracted files, you'll find a file named ``index.html`` [#f1]_ . This
61
-
is the web page that contains the initial experiment. Please open this file in a
62
-
browser, by double-clicking the file or dragging it onto your browser window.
35
+
Among the extracted files, you'll find a file named ``index.html`` [#f1]_ . This is the web page that contains the initial experiment. Please open this file in a browser, by double-clicking the file or dragging it onto your browser window.
63
36
64
37
.. image:: getting_started/starterkit.png
65
38
:alt:Screenshot of default starterkit page
66
39
:width:60%
67
40
:align:right
68
41
69
-
The page should look very similar to the example on the right, but please don't
70
-
anxiously wait for something to happen: it won't. That's because right now,
71
-
there is no experiment to run -- the file we opened just contains the loading
72
-
screen. The experiment we build will replace this content, as we will see in the
73
-
next step.
42
+
The page should look very similar to the example on the right, but please don't anxiously wait for something to happen: it won't. That's because right now, there is no experiment to run -- the file we opened just contains the loading screen, and because we haven't provided a study for it to run, it will wait indefinitely at this point. The experiment we are about to build will replace this content, as we will see in the next step.
74
43
75
-
Before we move on, you might want to have a brief look at the code of the file
76
-
you just opened. If you view it in your editor instead of the browser, you'll
77
-
see the underlying source code. If you like, take a closer look -- here are some
78
-
things you might notice:
44
+
Before we move on, you might want to have a brief look at the code of the file you just opened. If you view it in your editor instead of the browser, you'll see the underlying source code. If you like, take a closer look -- here are some things you might notice:
79
45
80
46
* In the ``head`` tag, there are quite a few references to outside files. In
81
-
particular, we're loading some external Javascript and ``CSS``. These are
82
-
provided with ``lab.js`` and contain the library code and default styles. You
83
-
might have also spotted a reference to ``experiment.js`` -- that's where we'll
84
-
define the actual study.
47
+
particular, we're loading some external Javascript and ``CSS``. These are provided with ``lab.js`` and contain the library code and default styles. You might have also spotted a reference to ``study.js`` -- that's where we'll define the actual study.
85
48
* The ``body`` tag contains the page content. A closer look will reveal that
86
-
everything is contained within a ``div`` tag of the ``container`` class.
87
-
This is what provides the rectangular frame you saw on the page.
49
+
everything is contained within a ``div`` tag of the ``container fullscreen`` class. This is what provides the rectangular frame you may have spotted on the page.
88
50
* Within the container div, the content is subdivided into ``header``, ``main``,
89
-
and ``footer`` elements. These correspond to the three areas on the page. Feel
90
-
free to adjust the content as you see fit!
91
-
* Finally, inside the ``main`` element, there's a ``div`` with an attribute
92
-
``data-labjs-section`` with the value ``main``. That's where the actual
93
-
experimental content will go.
51
+
and ``footer`` elements. These correspond to the three areas on the page. Feel free to adjust the content as you see fit!
52
+
* Finally, you might have spotted that the ``main`` element has an attribute
53
+
``data-labjs-section`` with the value ``main``. That because the experiment content will go inside that element, and the surrounding parts of the page will remain unchanged. You can move this attribute, for example, to the surrounding ``div``, which will allow you to replace the entire container content with every new screen.
94
54
95
-
With that, let's go get this experiment to work!
55
+
So that's the page structure we're going to work within. Next, let's go get an experiment to work!
96
56
97
57
.. seealso::
98
58
99
-
If you're not quite sure exactly how the design works, please don't worry --
100
-
we'll come back to the specifics of layout when we think about :ref:`styling
101
-
your study <tutorial/style>`
59
+
If you would like to find out more about how the design works, we discuss specifics of page layouts in the section :ref:`styling your study <tutorial/style>`.
60
+
61
+
----
102
62
103
63
How an experiment is built
104
64
--------------------------
105
65
106
-
The experiment runs on top of the basic ``HTML`` file you've just seen, by
107
-
exchanging content when appropriate, and collecting and reacting to
108
-
participants' responses. This interaction requires Javascript.
66
+
The experiment runs on top of the basic ``HTML`` file you've just seen, by exchanging content when appropriate, and collecting and reacting to participants' responses. This interaction requires JavaScript.
109
67
110
-
Let's take a closer look at the ``experiment.js`` file included in the starter
111
-
kit -- that's where the actual structure of the experiment is set up. In
112
-
particular, let us draw your attention to a specific part of the code::
68
+
Let's take a closer look at the ``study.js`` file included in the starter kit -- that's where the actual structure of the experiment is set up. In particular, we would like to draw your attention to a specific part of the code::
113
69
114
-
var experiment = new lab.flow.Sequence({
70
+
var study = new lab.flow.Sequence({
115
71
content: [
116
72
/* ... */
117
73
]
118
74
})
119
75
120
-
As you may have guessed, this snippet defines the experiment as a **sequence**
121
-
of things. To be exact, the sequence component is retrieved from the ``flow``
122
-
control part of the ``lab`` library. Then, a new sequence is created and saved
123
-
in the ``experiment`` variable. Some additional options are provided in the
124
-
brackets, notably some ``content`` (omitted here). You might have noticed that
125
-
the content is included in brackets, which indicate a list of things (or, to use
126
-
the common technical term, an array).
76
+
As you may have guessed, this snippet defines the experiment as a **sequence** of things. To be exact, the sequence component is retrieved from the ``flow`` control part of the ``lab`` library. Then, a new sequence is created and saved in the ``experiment`` variable. Some additional options are provided in the brackets, notably some ``content`` (omitted here). You might have noticed that the content is included in square brackets, which indicate that the content is a list of things (or, to use the common technical term, an array).
127
77
128
78
So what goes into the sequence content? Again, there's an example in the starter
129
79
kit::
@@ -132,45 +82,26 @@ kit::
132
82
content: 'Hello world!'
133
83
})
134
84
135
-
We hope that the similarities to the previous example become apparent: We're
136
-
building a new screen which is provided by the ``HTML`` part of the library.
137
-
Again, there's some content, this time a text string, which is more appropriate
138
-
as content for a single screen than the list of things used in the sequence
139
-
above.
85
+
We hope that the similarities to the previous example become apparent: We're building a new screen which is provided by the ``HTML`` part of the library. Again, there's some content, this time a text string, which is more appropriate as content for a single screen than the list of things used in the sequence above.
86
+
87
+
This basic structure is worth taking another look at, because we're going to come across it over and over again: We're going to build components, specify some content (and possibly a few more options), and nest them within one another to build even complex experiments.
140
88
141
-
This basic structure is worth taking another look at, because we're going to
142
-
come across it over and over again: We're going to build components, specify
143
-
some content (and possibly a few more options), and nest them within one another
144
-
to build even complex experiments.
89
+
----
145
90
146
91
So why isn't this working yet?
147
92
------------------------------
148
93
149
94
We apologize for keeping you in suspense for this long! If you take another look
150
-
at the remainder of the code in the file, two more things happen: A :ref:`data
151
-
store <reference/data>` is set up to collect the information gathered in the
152
-
experiment, and then the experiment is run ... or rather it isn't, because us
153
-
spoilsports have commented out the final line of code.
154
-
155
-
By uncommenting the final line and reloading the ``HTML`` page in the browser,
156
-
you should see the code in action: Instead of the loading screen you saw before,
157
-
the page should now contain the content you specified above.
158
-
159
-
Feel free to change the content to see that your changes to the code are
160
-
reflected in the display. You might also try adding a second screen to the
161
-
sequence -- make sure that you don't forget a comma to separate the two as you
162
-
list them in the sequence content. Also, you might need to add an additional
163
-
option like ``timeout: 1000`` to the first screen to make sure that the
164
-
experiment progresses beyond it!
95
+
at the remainder of the code in the file, there's one more thing that happens: The study is started ... or rather it isn't yet, because us spoilsports have commented out the final line of code.
96
+
By uncommenting the final line and reloading the ``HTML`` page in the browser, you should see the code in action: Instead of the loading screen you saw before, the page should now contain the content you specified above.
97
+
98
+
Feel free to change the content to see that your changes to the code are reflected in the display. You might also try adding a second screen to the sequence -- make sure that you don't forget a comma to separate the two as you list them in the sequence content. Also, you might need to add an additional option like ``timeout: 1000`` to the first screen to make sure that the experiment progresses beyond it!
165
99
166
100
.. tip::
167
101
168
-
Please don't worry about breaking the code: It can't harm your computer.
169
-
If something goes wrong, you can find the original version `in the repository
**Please don't worry about breaking the code as you experiment**: It can't harm your computer. If something goes wrong, you can find the original version `in the repository <https://github.com/FelixHenninger/lab.js/blob/master/src/starterkit/experiment.js>`_.
171
103
172
-
If you have questions at this point, please don't hesitate to reach out; we'd
173
-
be thrilled to hear from you and happy to help as best we can.
104
+
As before, **we'd love to support you** if you have questions at this point. Please don't hesitate to `reach out <https://lab.js.org/resources/support/>`_; we'd be thrilled to hear from you and happy to help as best we can.
Copy file name to clipboardExpand all lines: docs/learn/code/index.rst
+6-31Lines changed: 6 additions & 31 deletions
Original file line number
Diff line number
Diff line change
@@ -3,40 +3,15 @@
3
3
Code a study from scratch
4
4
=========================
5
5
6
-
**Welcome to the lab.js tutorial, and thank you for checking out our library!**
7
-
We hope you like it, and are excited to see how you are going to use it in your
8
-
research.
6
+
**Welcome to the lab.js tutorial, and thank you for checking out our library!** We hope you like it, and are excited to see how you are going to use it in your research.
9
7
10
8
----
11
9
12
-
On the following pages, we're going to provide an introduction to building
13
-
experiments using ``lab.js``, and show you how the library works. In our
14
-
experience, it will take between 30 minutes and an hour to get a feel for how to
15
-
work with the library, and probably an afternoon to build your first experiment.
16
-
After that, our experience is that things get progressively easier, and students
17
-
can often build a complete experiment in an hour or two.
18
-
19
-
The experiments will be built as web pages, so the tutorial presupposes some
20
-
familiarity with HTML and CSS, and some (minimal) experience in programming
21
-
(not necessarily in Javascript -- R users, in our experience, quickly feel at
22
-
home).
23
-
24
-
If you are not familiar with HTML and CSS, it is well worth it to spend some
25
-
time learning these skills, which are handy regardless of how you will build
26
-
your experiments, and useful far beyond the domain of online experiments. These
27
-
topics warrant their own tutorials; thankfully, `Codecademy
28
-
<https://www.codecademy.com/>`_ offers an excellent course on `HTML and CSS
29
-
<https://www.codecademy.com/learn/web>`_ that will teach you everything you need
30
-
to know for building experiments online and more. If you are just getting
31
-
started with making web pages, we warmly recommend this course. Similarly, there
32
-
is a very good `introductory Javascript course
33
-
<https://www.codecademy.com/learn/javascript>`_ offered on Codecademy and
However, having detailed Javascript knowledge is not necessary for following the
37
-
tutorial: If you have a little experience in programming (especially with R), or
38
-
if you are willing to experiment and mess with the code, please be invited to
39
-
jump right in and consult further resources as required.
10
+
On the following pages, we're going to provide an introduction to programming experiments in JavaScript using ``lab.js``, and show you how the library works. In our experience, it will take between 30 minutes and an hour to get a feel for how to work with the library, and probably an afternoon to build your first experiment. After that, our experience is that things get progressively easier, and students can often build a complete experiment in an hour or two.
11
+
12
+
The experiments will be built as web pages, so the tutorial presupposes some familiarity with HTML and CSS, and some (minimal) experience in programming (not necessarily in Javascript -- R users, in our experience, quickly feel at home).
13
+
14
+
If you are not familiar with HTML and CSS, it is well worth it to spend some time learning these skills, which are handy regardless of how you will build your experiments, and useful far beyond the domain of online experiments. These topics warrant their own tutorials; thankfully, `Codecademy <https://www.codecademy.com/>`_ offers an excellent course on `HTML and CSS <https://www.codecademy.com/learn/web>`_ that will teach you everything you need to know for building experiments online and more. If you are just getting started with making web pages, we warmly recommend this course. Similarly, there is a very good `introductory Javascript course <https://www.codecademy.com/learn/javascript>`_ offered on Codecademy and another on `Khan Academy <https://www.khanacademy.org/computing/computer-programming/programming>`_. However, having detailed Javascript knowledge is not necessary for following the tutorial: If you have a little experience in programming (especially with R), or if you are willing to experiment and mess with the code, please be invited to jump right in and consult further resources as required.
0 commit comments