(DEPRECATED) Developing POPUP widgets

Installation:

Getting everything setup

1. Install Materia if you haven't already!
2. Create a new project on clu in the Materia namespace for your widget (i.e. "Stroop Effect").
3. Clone the popup-template project in your-materia/static/sandbox/source
4. Change the folder name of popup-template to match the name of your project (i.e. "stroop-effect")
5. Edit the install.yaml file and change the name from "Popup Template" to your project (i.e. "Stroop Effect")
6. Clone the popup-example project in your-materia/static/sandbox/source
7. cd into the sandbox folder and build the popup-example project with grunt: grunt --widget=popup-example sandbox
8. In your browser navigate to http://localhost:8080/sandbox/popup-example/demo to view the Popup Example widget. This goes over some examples of how to create a popup widget. You can go through this widget along with its source code (again in your-materia/static/sandbox/source/popup-example) to see how it was created.

Installing the older flash widget

1. Put the older flash wigt file in your root Materia folder (the actual location is irrelevant but putting the file here will make our commands easier)
2. If you have PHP installed on your machine navigate in the command line to your root Materia folder and run this command to install the widget: php oil r widget:install -u -f the-flash-widget.wigt.
3. If you don't have PHP installed on your machine ssh into your vagrant machine with vagrant ssh, then navigate to the root Materia folder with cd /mnt/host/current, then run the install command: php oil r widget:install -u -f the-flash-widget.wigt
4. Create a new instance of this widget by running php oil r widget:create_instance -i and follow the prompts. For the user you'll want to use "~author", and when it asks you to create a stub qset you'll need to answer yes.
5. This will install the widget to your local Materia install. Navigate to 'My Widgets' to see the installed widget. You can use this widget as a reference.

Developing your widget

1. cd into the sandbox folder and watch your project with grunt: grunt --widget=your-widget watch --minify-assets=false --minify-html=false. This will watch your project source folder for changes and update the widget when you save a new file. The additional minify flags will disable minification which will help make debugging easier.
2. Edit your project source folder in your favorite text editor. HEY, LISTEN: Don't edit any files inside the sandbox/your-project folder, only edit the files in sandbox/source/your-project. The grunt task will overwrite any files in sandbox/your-project.
3. View your project at http://localhost:8080/sandbox/your-project/demo.

Storing Data

POPUP widgets utilize the storage feature of Materia, which allows arbitrary data to be stored along with the widget and the user who is taking the widget. This data, represented in the form of a "Table" (much like SQLite) can then be used in Psychology classes as a data source to analyze. Every POPUP widget uses this feature to store all kinds of data (reaction times, survey responses, etc). Here's how to get started:

• Take a look at the old Flash source code for the text storage.addTable and storage.insert. In Flash this is how the developers store data with the widget. storage.addTable creates a new table (if it doesn't exist). storage.insert adds data to that table.
• Now take a look at the widget-app.coffee file in the popup-example project. You should see MateriaService.createStorageTable and MateriaService.insertStorageRow. This is the angular way to create tables and insert data into them. The syntax is slightly different, so here's a comparison:

To create a storage table:

• Flash (old): storage.addTable('ExampleTable', 'ReactionTime', 'KeyPressed');
• Angular (new): MateriaService.createStorageTable('ExampleTable', ['ReactionTime', 'KeyPressed']);

This will create a table called ExampleTable with the fields 'ReactionTime' and 'KeyPressed'.

To insert data into a storage table:

• Flash (old): storage.insert('ExampleTable', foo, bar);
• Angular (new): MateriaService.insertStorageRow('ExampleTable', [foo, bar]);

This will add the values of foo and bar for the ReactionTime and KeyPressed fields to a new row in ExampleTable.

Workflow:

• Typically you'll want some sort of data object either in a controller you create or in the widgetCtrl to store the data you care about. Your widget will then add stuff to that data object, then use the MateriaService to create the storage table and insert your data into it. You can see an example inside widget-app.coffee of the popup-example project.
• You'll need to look inside the Flash code to determine what data to send and how to calculate that data.
• When you have inserted all the data you need to you'll want to call MateriaService.widgetCompleted() - this tells Materia that the user has finished the widget and will send all of the data to Materia.
• While developing your widget you can call MateriaService.getStorageTableValues to test the table. If you created a table called "ExampleTable" you could call console.log(MateriaService.getStorageTableValues('ExampleTable')); to test this. Of course you won't want to leave any console.log statements in your code as you finish developing your widget!

Finalizing

1. When you're near completion you'll want to install the widget to fully test the final project (and make sure the storage data works). Navigate into your sandbox folder and build your widget with grunt --widget=your-widget package, then navigate to the root Materia folder and install it with php oil r widget:install -u -f static/widget/sandbox/source/your-project/_output/your-project.wigt
2. Now you'll need to create an instance of your widget. To do this run php oil r widget:create_instance -i and follow the prompts. For the user you'll want to use "~author", and when it asks you to create a stub qset you'll need to answer yes.
3. Navigate to your Materia install in your browser and find the instance you created in the previous step. Copy the link and test your widget (don't use Preview mode - this won't save storage data). Once you've tested your widget refresh the page and select your widget again - you should see a 'Data' tab with the storage data that your widget saved. You'll want to make sure your data is what you expect and matches the Flash widget (Zach can provide you with a sample of the data for the Flash widgets).