Skip to content

Commit

Permalink
Update the README to reflect the changes for 2.0.
Browse files Browse the repository at this point in the history
  • Loading branch information
@bartkamphorst
bartkamphorst committed Oct 12, 2022
1 parent 5a00ba8 commit a2de644
Showing 1 changed file with 56 additions and 25 deletions.
81 changes: 56 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# FSC-C
A continuous measure of future-self continuity, developed for the web.

For a live demo, click [here](http://jsfiddle.net/xgdVM/113/embedded/result/).
For a live demo, click [here](https://jsfiddle.net/90Lvym4g/).

If you use this software for academic purposes, please cite the following [article](https://journals.sagepub.com/doi/pdf/10.1177/0894439316653513):

Expand All @@ -12,33 +12,46 @@ If you use this software for academic purposes, please cite the following [artic

To add the FSC-C measure to a webpage, follow these steps.

* Copy the contents of the file _fsc-c.css_ to the CSS of your HTML webpage, for example by placing them in \<style\>\<\\style\> tags within the \<head\> of the page;
* Add the following include headers.
* Add the following include headers to include JQuery, JQuery-UI, and FSC-C (javascript and css stylesheet).
```html
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.11.2/jquery-ui.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.1/jquery.min.js" ></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/bartkamphorst/fsc-c@5e76fc9/fsc-c.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/bartkamphorst/fsc-c@5e76fc9/fsc-c.css">
```

* Copy the contents of the file _fsc-c.js_ to your HTML webpage, placing it within \<script type="text/javascript"\>\<\\script\> tags.
* Add the following lines to the body of your HTML:

```html
<div class="circle-container">
<div class="circles" id="circle-drag-1"><span>future self</span>
</div>
<div class="circles"><span>present self</span>
</div>
<div class="fsc-c-circle-container">
<div class="fsc-c-circles fsc-c-draggable" id="fsc-c-1"><span>future self</span></div>
<div class="fsc-c-circles"><span>present self</span></div>
</div>
<div id="fsc-c-1-distance">0</div>
<div id="fsc-c-1-overlap">0%</div>
```
Notice that the id includes a number (1). This is not strictly necessary, but it allows for multiple instances of the measure to be included on one page. Just make sure that each id is unique.

(Also, ensure that the div elements have the `circles` class so that they are styled properly. If the elements do not show up as circles, check that you have included the CSS / that the CSS is loaded properly.)
(Also, ensure that the div elements have the `fsc-c-circles` class so that they are styled properly. The first circle additionally requires the `fsc-c-draggable` class. If the elements do not show up as circles, check that you have included the CSS / that the CSS is loaded properly.)

* Profit!

# Storing the measure's values

Typically, you'll want to store the measure's values. How to do so will depend on how you use the measure. For example, if you use the measure inside a HTML form, you can store the values in form fields that are then sent to a server on submission of the form. If, on the other hand, the measure is used in something like Qualtrics, there are often certain Javascript methods available that can be called to store the data (this will have to be added to the Javascript). We'll see an example of this in the Qualtrics instructions below.
Typically, you'll want to store the measure's values. How to do so will depend on how you use the measure. For example, if you use the measure inside a HTML form, you can store the values in form fields that are then sent to a server on submission of the form. If, on the other hand, the measure is used in something like Qualtrics, there are often certain Javascript methods available that can be called to store the data (this will have to be added to the Javascript). We'll see an example of this in the Qualtrics instructions below. The basic format however is to implement an "event handler" for a `fsc-c:data` event:
```html
<script>
jQuery(function($) {
$( ".fsc-c-draggable" ).on( "fsc-c:data", function(event, data) {
// process the data
Object.entries(data).forEach(([id, values]) => {
console.log(id + '-distance', values['distance']);
console.log(id + '-overlap', values['overlap']);
})
})
});
</script>
```


# Detailed instructions for adding the FSC-C measure to Qualtrics
Expand All @@ -54,23 +67,41 @@ Typically, you'll want to store the measure's values. How to do so will depend o
* Copy the contents of the file _fsc-c.css_ to this text editor, and hit 'Save'.
* Hit 'Save' again to return to your survey.

Alternatively, you can rely on a CDN to load the CSS. For this method, go to the 'Header' field (still under 'Look \& Feel' \> 'Advanced') and add the following line:
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/bartkamphorst/fsc-c@5e76fc9/fsc-c.css">
```

### Step two: Adding headers and the Javascript.

* Click on the 'Look \& Feel' button of your survey (located below the 'My Surveys' tab).
* Choose the 'Advanced' option.
* In the 'Header' field, add the following lines:

```html
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.11.2/jquery-ui.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.1/jquery.min.js" ></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/bartkamphorst/fsc-c@5e76fc9/fsc-c.js"></script>

<script></script>
```
* Then, in the same 'Header' field, position your cursor in between the last pair of script tags, and paste the contents of the file _fsc-c.js_ there.
* Then, in the same 'Header' field, position your cursor in between the last pair of script tags, and implement your event handler there. An example can be found in `fsc-c_example.html`, which is reproduced here:
```javascript
jQuery(function($) {
$( ".fsc-c-draggable" ).on( "fsc-c:data", function(event, data) {
// process the data
Object.entries(data).forEach(([id, values]) => {
// Qualtrics only: use Qualtrics.SurveyEngine.setEmbeddedData(key, value) to store the values as Qualtrics embeddedData.
// Notice that these embedded data has to be added explicitly in the survey flow in order for them to show up in your data exports.
Qualtrics.SurveyEngine.setEmbeddedData(id + '-distance', values['distance']);
Qualtrics.SurveyEngine.setEmbeddedData(id + '-overlap', values['overlap']);
})
})
});
```

**Notice that it is possible to use Qualtrics' text editor for editing the 'Header' field by clicking the 'edit' link, but make sure to use the 'Source' option if you decide to do so.**

* Uncomment the two lines that call Qualtrics' Qualtrics.SurveyEngine.setEmbeddedData(key, value) method. This is needed to store the FSC-C's values.

* Click 'Save' to return to your survey.

### Step three: Adding custom HTML to a question to enable the FSC-C measure.
Expand All @@ -84,19 +115,19 @@ Typically, you'll want to store the measure's values. How to do so will depend o
* Add the following lines to the body of your HTML:

```html
<div class="circle-container">
<div class="circles" id="circle-drag-1"><span>future self</span>
</div>
<div class="circles"><span>present self</span>
</div>
<div class="fsc-c-circle-container">
<div class="fsc-c-circles fsc-c-draggable" id="fsc-c-1"><span>future self</span></div>
<div class="fsc-c-circles"><span>present self</span></div>
</div>
<div id="fsc-c-1-distance">0</div>
<div id="fsc-c-1-overlap">0%</div>
```

### Step four: Adding embeddedData fields for storing values

* Go to 'Survey Flow'
* Add a new Embedded Data Field Name that corresponds to the _id_ of the moving circle, with the string '-overlap' appended. With the example code from the previous step, the field name would thus become 'circle-drag-1-overlap'.
* Repeat the previous step, only with the suffix '-distance'. With the example code from the previous step, the field name would thus become 'circle-drag-1-distance'.
* Add a new Embedded Data Field Name that corresponds to the _id_ of the moving circle, with the string '-distance' appended. With the example code from the previous step, the field name would thus become 'fsc-c-1-distance'.
* Repeat the previous step, only with the suffix '-overlap'. With the example code from the previous step, the field name would thus become 'fsc-c-1-overlap'.


### Step five: Check if your setup is working
Expand Down

0 comments on commit a2de644

Please sign in to comment.