Skip to content

v1.1.0-final
Compare
Choose a tag to compare
@benloh benloh released this 28 Jun 21:49
· 232 commits to master since this release
v1.1.0-final
b83a860

Version 1.1.0-final

Date Released: 2/11/2020

Branch: master

This is the MEME release for the February 2020 IU study.

It is 1.1 because of a change in the data format. See "Data Incompatibility Warning" below.

New Features

New features since the v1.0.0 Release:

  • The "Zoom Out" button now pan and zooms out to the extent of the model regardless of the minimum zoom value and where your model is placed. (Previously it would only zoom out to 0.5 centered, so if your model was offscreen you wouldn't see it). See !80.

  • There is now a "Zoom 1:1" button that will pan and zoom to the upper left corner of the workspace where Components are added by default. See !80.

  • The workspace now has a light-colored rectangle to indicate the main intended model area to help students orient themselves. They can still place outside the artboard. See !80.

  • The database file is now automatically backed up each time you start the app (e.g. via npm run dev, npm run app, or double clicking the meme.app. The snapshots are saved in the runtime folder. See !82.

  • Research logging for comments now will include the comment id. See !79.

  • The default resources have been updated for IU. See !78.

Bug Fixes

  • Login tokens are not converted to upper case internally so that comment authors are properly matched. This fixes a bug where logging in with a different case would cause the system to think you were a different author and therefore not allow you to edit or delete your own comment. See !79.

  • Mech comments now use the database id as a refId. This fixes two bugs: 1. If a mech is reversed, the pathId is also reversed. This results in comments becoming disconnected because the referent pathId has changed. 2. If a mech is deleted, and then a new mech is created connecting the same two props, the new mech picks up the old mech's comments. Again, this is because the pathId is the same. See !81.

  • Component positions are now properly saved and restored. This fixes a bug where positions were being saved to the wrong database object id. As a result, components did not save their positions across app restarts. https://gitlab.com/inq-seeds/boilerplate/commit/46e30746739d937509fcc6fae219790ae0dfe211

Data Incompatibility Warning

Version 1.1 database files use a new id for Mech Comments. Version 1.1 can open and read 1.0 datafiles, but Mech comments will be detached from their parent Mechs. See !81 for details.

To Install and Run

Running the system involves building and packaging the application, and starting up a game server, admin interface, and student devices. These instructions assume you're familiar with working with Git and Node and using npm in the terminal.

I. Game Server

I.A. Check Out Game Server Code

This assumes you've already installed NodeJS. If you haven't, we recommend using nvm. This will allow you to select different Node versions. As of November 2019, we are currently using Node Version 10.9.0.

  1. Check out the master branch.
  2. If you're using nvm, type nvm use to auto-load the recommended Node version (10.9.0). You may also need to type nvm install to install 10.9 if it's not already installed on your machine.
  3. npm ci -- You might need to install some packages before doing a clean.
  4. npm run clean:all -- Remove all existing database and node modules.
  5. npm ci -- Install node modules

I.B. Download Resources

The pdf and netlogo simulation resources are not currently in the repo. You will need to download them from the source (ask Joshua for them) and place them in the boilerplate/src/app-web/static/dlc folder.

I.C. Build and Run the Game Server

You should build and run the game server first just to make sure everything is working.

  1. npm run dev
  2. Point your browser at http://localhost:3000/ -- You should see the MEME login screen.

II. Building and Running the Electron App

Once you verify the game server is running, you can build and deploy a standalone Electron application for distribution to teachers, so all they have do to start a MEME server in their classroom is to double click on the MEME.app.

If you want to seed (no pun intended) a MEME Electron application with sample data, e.g. configure teachers, classrooms, and groups, example models, etc, you can just run the MEME application, make the changes, and then duplicate and the MEME.app.

The one thing that can't be easily changed via the admin interface are the resources, so generally it's best to download them first. (Technical note: By running the Electron app, you're automatically loading the db.js files in system/datasets/meme. If you want to edit the db.js files by hand for the Electron app, edit those.

To build and run the Electron app:

  1. Make sure all the resources you want to use are in the boilerplate/src/app-web/static/dlc folder.
  2. npm run package
  3. Find the app in boilerplate/dist/meme-darwin-x64/meme.app
  4. Double click the meme.app file to start it.
  5. Point your browser at http://localhost:3000/ -- You should see the MEME login screen.

You can copy and distribute the meme.app file by itself. But first, you might want to set up some template admin settings. See the "Admin Interface" section below.

NOTE: Because the meme.app Electron app is not a signed and notarized, you may have to disable some security features on your Mac to run it.

For more technical information about creating and managing the dataset, see:

Updating Resources in the MEME.app

If you've already built and distributed the MEME app and find that you need to add or change resources, you can still update resources in the MEME.app manually:

  1. Quit the MEME app.
  2. Find the "meme.app" file in your Finder.
  3. Ctrl-Click on the "meme.app" and select "Show Package Contents"
  4. Navigate to meme.app/Contents/Resources/app/web/static/dlc
  5. Copy your new resources into the dlc folder.
  6. Run the MEME app and use the admin interface to add the resources and assign them to classrooms.
  7. You can now duplicate the MEME app file and distribute it. The new resources should be included with the app.

III. Admin Interface

Use the interface to set up teachers, classrooms, groups, students, ratings definitions, criteria, sentence starters, and resources.

Each classroom can have its own ratings definition, criteria, and sentence starter, as well as a subset of the resources enabled for them. Resources are shared across all classrooms, but are only visible to the class if you enable it. This means you'll want to carefully set up each class's initial settings if you want them to be anything other than the defaults. No resources are enabled by default, so you will have to enable them for each class.

To access the Admin Interface:

  1. Start the Meme app.
  2. Point your browser at http://localhost:3000/#/admin -- You'll see the admin interface.

If you are running the server on a remote server, you can use the special ?danishpowers parameter to access the admin page.

IV. Client Machines

As of 1.0, the meme app should run on Chrome browsers on Mac laptops, Windows laptops, and Chromebooks. It should mostly work on Android tablets (though they have not been fully tested). Unfortunately there are known rendering issues with iOS Chrome.

IV.A. Install Screen Capture Extension

In order to capture screens when creating a new evidence, you will need to install the MEME Extension on each student machine.

  1. Check out https://gitlab.com/inq-seeds/screenshot
  2. Go to SETTINGS in Chrome (in "stacked dot" menu upper right)
  3. Go to EXTENSIONS (in left sidebar of settings screen)
  4. Enable Developer Mode
  5. Choose Load an Unpacked Extension
  6. Find the extension directory in screenshot repo
  7. Once the extension is installed, when students create a new evidence, a screenshot of the resource will be automatically captured.

NOTES:

  • As of November 2019, the extension has been confirmed to work with Chrome on macOS, Windows 10, and ChromeOS.
  • The screenshot only works when the Resource View is opened. If you're just viewing the Resource Library list, you can't capture the screen.
  • The app will work without the extension, but students will have to use other tools to capture the screen and manually insert them to evidence.

IV.B. Run as Student

To bring students into the app:

  1. Start the MEME app.
  2. In the admin interface, make sure you've created groups and added students to each group.
  3. Copy the student login tokens and hand them out to students.
  4. Copy the IP address from the MEME app, e.g. http://192.168.1.10:3000
  5. On the students Chrome browser, enter that URL: http://192.168.1.10:3000
  6. Enter the student login token.

NOTES:

  • Each model is owned by a group. A group can have any number of students. Any student in the group will have full author access to the model when they log in.
  • Sticky note comments are tied to individual students, but any student can edit any comment made by a member of their group.

IV.C. Teachers Viewing and Commenting on Student Work

Teachers can log in and view student work much as a student would:

  1. Start the MEME app
  2. In the admin interface, select the teacher, and write down their login token, e.g. MSBROWN-VYFZ.
  3. Point your browser to the student login URL, e.g. http://192.168.1.10:3000 (you can also use localhost if you're on the server).
  4. Login with the token.
  5. You should have read-only comment access to all student models in all of your classrooms.

Important Notes

Research Logs

  • Researcher logs can be found in meme.app/Contents/Resources/runtime/logs. Look for dated log files like meme.app/Contents/Resources/runtime/logs/2019-09102019-0910-log-102440.txt
  • Screenshots can be found in meme.app/Contents/Resources/runtime/screenshots.

NOTE: Over time research logs and screenshots can grow quite large. You'll want to keep an eye on disk space, especially if you use the same app over months.

Login Tokens

  • Student login tokens are based on group Ids. So if you delete a student from one group and add them to another, they will have a new token.
  • Teacher login tokens are based on their name, so if you update their name, they will have a new token.

Backups

We recommend daily backups. Better yet, back up after each classroom period.

  • The easiest way to backup is to just duplicate the whole MEME app.
  • If you want to save space, you can just grab the database file in meme.app/Contents/Resources/system/datasets/meme.loki (assuming you didn't rename the database or are running a different database file).

Database Snapshots
When the server starts up, MEME will now:

  • automatically copy the current LOKI database file (usually meme.loki in the classroom) to a backup file using the same date format as the log files. The database file is of the form YYYY-MMDD-meme-HHMMSS.loki.snapshot and is in the runtime directory.
  • log the file name of the database snapshot in the log

The snapshot time corresponds to the snapshot log, e.g. 2020-0209-log-124525.loki.snapshot = state of db at the start of the 2020-0209-log-124525.txt log.

Getting Ready

Assets 2
Loading