Noble Pug Mullet


    0.2.3 • Public • Published

    _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:

    • magpie.full.js - includes _magpie functions and its dependencies (jquery nad csv-js), no need to install and import jquery and csv-js.
    • magpie.js - includes only _magpie functions (jquery nad csv-js), jquery and csv-js have to be included separately.
    • magpie.css - includes magpie styles.

    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:

    • experiment/
      • libraries/
        • magpie.full.js
        • magpie.css
        • magpie.js

    magpie.full.js includes the dependencies that _magpie uses (jQuery, and csv-js). There is no need to install and import jQuery, and csv-js.

    magpie.js includes only the _magpie package, the dependencies should be installed separately for _magpie to work.

    magpie.css includes styles for _magpie experiments.

    1. Import _magpie in your main html file

    the full version or no-dependencies version:

    <script src="libraries/magpie.full.js></script> or <script src="libraries/magpie.js></script>

    and _magpie-styles:

    <link rel="stylesheet" type="text/css" href="libraries/magpie.css">


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

    • magpieInit({..}) - to initialize the experiment
    • magpieViews.view({..}) - to create an instance of a _magpie view

    Experiment initialisation

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

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

    • views_seq - an array of view objects in the sequence you want them to appear in your experiment. more info
    • deploy - an object with information about the deploy methods of your experiment. more info
    • progress_bar - an object with information about the progress bars in the views of your experiment. more info

    Sample magpieInit call:

    $("document").ready(function() {
            views_seq: [
            deploy: {
                "experimentID": "4",
                "serverAppURL": "",
                "deployMethod": "debug",
                "contact_email": "",
                "prolificURL": ""
            progress_bar: {
                in: [
                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>
            <-- 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='' target='_blank'></a>
            <!-- views are inserted in here -->
            <main id='main'>

    Included views

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

    • Trial Type Views (TTV):

      • magpieViews.forcedChoice - binary forced-choice task
      • magpieViews.sliderRating - slider rating task
      • magpieViews.textboxInput - textbox input task
      • magpieViews.dropdownMenu - dropdown menu task
      • magpieViews.ratingScale - Likert-scale rating task
      • magpieViews.sentenceChoice - text selection task
      • magpieViews.imageSelection - click-on-a-picture task
      • magpieViews.keyPress- press a button task
      • magpieViews.selfPacedReading
      • magpieViews.selfPacedReading_ratingScale
    • Other Type Views (OTV):

      • magpieViews.intro - introduction view
      • magpieViews.instructions- instructions view
      • magpieViews.begin - begin experiment view; can be used between the practice and the main view
      • magpieViews.postTest - post-experiment questionnaire
      • magpieViews.thanks - the last view that handles the submission of the results of creates a table with the results in 'Debug Mode'

    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:

    • name: string - the name of the view (the progress bar uses the name)
    • trials: number - the number of trials this view appears
    • CT: 0 - current trial, always starts from 0
    • render: function - a function that renders the view
      • pass CT and magpie as parameters to render()

    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 = {
            title: config.title, // 
            buttonText: config.buttonText,
            render(CT, magpie) {
                let startTime =;
                const viewTemplate =
                `<div class='view'>
                    <h1 class="title">${title}</h1>
                    <button id="the-button">${button}</button>
                $('#the-button').on('click', function(e) {
                        trial_type: config.trial_type,
                        trial_number: CT+1,
                        RT: - startTime
            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() {
            views_seq: [

    Sample custom info view:

    magpieViews.sayHello = function(config) {
        const _sayHello = {
            title: config.title,
            render(CT, magpie) {
                const viewTemplate =
                `<div class='view'>
                    <h1 class="title">${title}</h1>
                    <button id="hello-button">Hello back!</button>
                $('#hello-button').on('click', function(e) {
            CT: 0,
            trials: config.trials
        return _sayHello;
    const hello = magpieViews.sayHello({
        name: 'buttonPress',
        title: 'Hello!?',
        trials: 1
    $("document").ready(function() {
            views_seq: [

    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:

    • experimentID: string - the experimentID is needed to recover data from the magpie server app. You receive the experimentID when you create the experiment using the magpie server app
    • serverAppURL: string - if you use the _magpie server app, specify its URL here
    • deployMethod: string - use one of 'debug', 'localServer', 'MTurk', 'MTurkSandbox', 'Prolific', 'directLink'
    • contact_email: string - who to contact in case of trouble
    • prolificURL: string - the prolific completion URL if the deploy method is "Prolific"

    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 list passed to magpieInit. Use the names of the views in

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

    • separate - have separate progress bars in each type of views declared in
    • default - have one progress bar throughout the whole experiment
    • chunks - have a separate progress chunk for each type of view in

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

    Sample progress bar

    $("document").ready(function() {
            progress_bar: {
                in: [
                ],                  // 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


    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.


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



    • master - Current stable version.
    • development - Development version. This is where new featues or bug fixes are pushed. When the version is stable, the branch is merged into master.

    (1) Source files

    • src/

      • magpie-canvas.js
      • magpie-errors.js
      • magpie-init.js
      • magpie-progress-bar.js
      • magpie-submit.js
      • magpie-utils.js
      • magpie-views.js
    • magpie.css

    (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 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.




    npm i magpie-modules

    DownloadsWeekly Downloads






    Unpacked Size

    536 kB

    Total Files


    Last publish


    • marcelklehr
    • xji
    • michael-franke
    • jannisbush