search

magpie-ea / magpie-modules

the reusable front-end bits in the _magpie modules
MIT License
7 stars 1 forks source link
front-end magpie-core

readme

_magpie project

minimal architecture for the generation of portable interactive experiments

Latest version: 0.2.3

Table of contents

Create an experiment with _magpie

Install and import _magpie

Option 1: Install with npm (recommended)

  1. Get _magpie

You need to have npm installed in your machine. Install npm.

# create a folder for your experiment

mkdir my-experiment

# move to the experiment's folder

cd my-experiment

# initialise npm (create a package.json file)

npm init

# install the dependencies with npm

npm install magpie-modules --save

the npm installation process creates a folder (named node_modules) in your experiment's directory where the npm dependencies are stored. After successfully installing _magpie, the node_modules folder should contain magpie-modules and its dependencies jquery and csv-js.

  1. Add _magpie

The magpie-modules folder includes the following three files that you can add to your experiment:

Import _magpie with a script tag:

add magpie.full.js

<script src='path/to/node_modules/magpie-modules/magpie.full.js'></script>

or add magpie.js, jquery and csv.js

<script src='path/to/node_modules/jquery/dist/jquery.min.js'></script>

<script src='path/to/node_modules/csv-js/csv.js'></script>

<script src='path/to/node_modules/magpie-modules/magpie.js'></script>

  1. Update _magpie

You can get newer versions of _magpie with

npm update

Option 2: Download the magpie-modules (not reccommended)

  1. Download the .zip from this repository

  2. Unzip and move magpie.full.js, magpie.js and magpie.css in the libraries/ folder of your experiment.

    Your experiment's structure should look like this:

  1. Import _magpie in your main html file

    the full version or no-dependencies version:

    <script src="https://github.com/magpie-ea/magpie-modules/raw/master/libraries/magpie.full.js></script> or <script src="https://github.com/magpie-ea/magpie-modules/raw/master/libraries/magpie.js></script>

    and _magpie-styles:

    <link rel="stylesheet" type="text/css" href="https://github.com/magpie-ea/magpie-modules/blob/master/libraries/magpie.css">

Usage

Once you have installed and included _magpie in your files, you can start using _magpie funcitons to create your experiment. You can use:

Experiment initialisation

Use magpieInit({..}) to create a _magpie experiment.

magpieInit takes an object as a parameter with the following properties:

Sample magpieInit call:

$("document").ready(function() {
    magpieInit({
        views_seq: [
            intro,
            instructions,
            practice,
            main,
            thanks
        ],
        deploy: {
            "experimentID": "4",
            "serverAppURL": "https://magpie-demo.herokuapp.com/api/submit_experiment/",
            "deployMethod": "debug",
            "contact_email": "YOUREMAIL@wherelifeisgreat.you",
            "prolificURL": "https://app.prolific.ac/submissions/complete?cc=ABCD1234"
        },
        progress_bar: {
            in: [
                "practice",
                "main"
            ],
            style: "default",
            width: 150
        }
    });
});

Views in _magpie

_magpie views get inserted in a html element with id main, you need to have an html tag (preferrably div or main) with id="main"

Sample index.html

<!DOCTYPE html>
<html>
    <head>
        ...
        ...
        ...
    </head>

    <body>
        <-- ask the participants to enable JavaScript in their browser -->
        <noscript>This task requires JavaScript. Please enable JavaScript in your browser and reload the page. For more information on how to do that, please refer to
            <a href='https://enable-javascript.com' target='_blank'>enable-javascript.com</a>
        </noscript>

        <!-- views are inserted in here -->
        <main id='main'>
            Loading...
        </main>

    </body>
</html>

Included views

_magpie provides several ready-made views which you can access form the magpieViews object. The views use js template strings

Each _magpie view function takes an object as a parameter with obligatory and optional properties. Here you can find more information about how to use the _magpie views.

Custom views

You can also create your own views.

The views are functions that return an object with the following properties:

Add the data gathered from your custom trial type views to magpie.trial_data

Sample custom trial type view:

The templates use js template strings

magpieViews.pressTheButton = function(config) {
    const _pressTheButton = {
        name: config.name,
        title: config.title, // 
        buttonText: config.buttonText,
        render(CT, magpie) {
            let startTime = Date.now();

            const viewTemplate =
            `<div class='view'>
                <h1 class="title">${title}</h1>
                <button id="the-button">${button}</button>
            </div>`;

            $("#main").html(viewTemplate);

            $('#the-button').on('click', function(e) {
                _magpie.trial_data.push({
                    trial_type: config.trial_type,
                    trial_number: CT+1,
                    RT: Date.now() - startTime
                });
                _magpie.findNextView();
            });
        },
        CT: 0,
        trials: config.trials
    };

    return _pressTheButton;
};

const mainTrial = magpieViews.pressTheButton({
    name: 'buttonPress',
    title: 'How quickly can you press this button?',
    buttonText: 'Press me!',
    trial_type: 'main',
    trials: 1
});

$("document").ready(function() {
    magpieInit({
        ...
        views_seq: [
            ...
            mainTrial,
            ...
        ],
        ...
    });
});

Sample custom info view:

magpieViews.sayHello = function(config) {
    const _sayHello = {
        name: config.name,
        title: config.title,
        render(CT, magpie) {
            const viewTemplate =
            `<div class='view'>
                <h1 class="title">${title}</h1>
                <button id="hello-button">Hello back!</button>
            </div>`;

            $("#main").html(viewTemplate);

            $('#hello-button').on('click', function(e) {
                _magpie.findNextView();
            });
        },
        CT: 0,
        trials: config.trials
    };

    return _sayHello;
};

const hello = magpieViews.sayHello({
    name: 'buttonPress',
    title: 'Hello!?',
    trials: 1
});

$("document").ready(function() {
    magpieInit({
        ...
        views_seq: [
            ...
            hello,
            ...
        ],
        ...
    });
});
Canvas

magpie also includes a small library to create simple shapes as a picture for your experiment.

random placement example random placement example

Check the canvas api for more information.

Deploy configuration

The deploy config expects the following properties:

prolificURL is only needed if the experiment runs on Prolific.

Progress Bar

_magpie provides the option to include progress bars in the views specified in the progress_bar.in list passed to magpieInit. Use the names of the views in progress_bar.in.

You can use one of the following 3 styles (include pictues)

Use progress_bar.width to set the width (in pixels) of the progress bar or chunk

Sample progress bar

$("document").ready(function() {
    magpieInit({
        ...
        progress_bar: {
            in: [
                "practice",
                "main"
            ],                  // only the practice and the main view will have progress bars in this experiment
            style: "chunks",    // there will be two chunks - one for the practice and one for the main view
            width: 100          // each one of the two chunks will be 100 pixels long
        }
    });
});

samples

Sample experiment

Here you can find a minimal experiment created with _magpie, you can use this template as a starting point for your experiment. Showroom is an experiment which demonstrates most of _magpie's functionalities including most views, hooks and the canvas-api.

Development

To get the development version of the _magpie package, clone this repository and install the dependencies by running npm install in the terminal.

Workflow

branches:

(1) Source files

(2) Create magpie.js and magpie.full.js

Option 1: Build the _magpie package files while developing

Use npm run watch command from the magpie-modules folder to start a process which watches for changes in the files in src and builds (updates) magpie.js and magpie.full.js. This commands builds both magpie.js and magpie.full.js when a file in src is saved.

Option 2: Make changes to the files and then build the _magpie files

Run npm run concat from the magpie-modules folder. This command builds both magpie.js and magpie.full.js.

(3) Merge into master

(4) Publish to npm

Run npm publish from the magpie-modules folder to publish the new version of _magpie.

Deployment using Netlify

  1. Registration
  2. Deployment
    • Using git: Click on the New site from Git-Button, choose GitHub and authorize the netlify-app on GitHub, configure which repositories to give access to, (back on netlify) select the repository to deploy, enter the build command rm -rf dist && mkdir dist && rsync -rv * dist --exclude ./dist and the publish directory dist (this is a workaround for publishing node_modules, see here, another way of bundling the files may be appropriate), click on Deploy site
    • Manual: Go to https://app.netlify.com/ and drag and drop your finished experiment folder (including node_modules) to the drag&drop area
  3. Configuration
    • Change the domain name:
      • Click on the deployed site you want to configure, click on Domain setting, click on Edit site name and change to the name of choice.