search

InteractiveMechanics / nmai-nk360-interactives

0 stars 0 forks source link

readme

NMAI NK360 Interactives

TODO

Getting started

Working with this repo

There will be at least three people actively working in this repository. Keep it clean and organized for everyone's sake. If you make a change that impacts other people, please notify them via Slack and submit the change as a Pull Request with reviewers assigned so we can approve it. Pull anything that can benefit the team into the shared/lib/im directory where possible to save time.

Project structure

Each project folder (see 5-news-article-creator for a sample) should follow the same structure:

Shared assets

In the root project directory is a shared folder containing assets we can use for multiple interactives. This may include Sass files, images/assets, written content, or JavaScript files. Check the shared/lib/im/code directory for all shared code with sample markup.

Third-party libraries

We're using a number of outside libraries for different features, including:

Grunt

Each interactive has a Gruntfile that will run a local webserver with watch command grunt dev. If you want to run JSHint to lint all of your custom JavaScript files, you can run grunt jshint.

For distribution, you can run grunt dist with several variables: --json=m#a#, --dir=name-of-directory, --theme=theme-acronym. For example, if you want to generate/build Module 1's (Pacific Northwest) Activity 1, and the directory provided by NMAI is "pnw-fishwars-markup", you can should run grunt dist --json=m1a1 --dir=pnw-fishwars-markup --theme=pnw. This will build a folder with the built files for that activity processed for deployment in the root of the repo. To see the full list of directory names from NMAI, go here: https://docs.google.com/document/d/1tCZ--qR89ZD-peq41w0BEt1foUu9S7ratKCiMky3HQo/edit

Here are all of the grunt dist commands you will need to run (by activity):

Back to Lesson Paths

After running grunt dist, update the "Back to Lesson" paths to (not timeline):

Commenting

As you go, be sure to comment your code to make sure it's clear. Write a short description of all functions (even if they seem obvious) and define each Sass file at the top of the file with a short description of what you might find in that folder. Use the following comment format where possible (include a short description of the function/file, and where appropriate, define the arguments and returned values):

/**
 * A short description of what this function/file does
 * @param {string|int|array} [argument] Description
 * @return {string|int|array} Description
Refactoring

This project will be delivered to the web development team at NMAI for integration, so refactor often to clean out code cruft and improve code. Add comments in, clean up file structure. There should be no JavaScript or CSS in HTML files!

Google Analytics

We're using Google Analytics for this project for analytics tracking. We'll use our local GA account for development for easier testing. Here is the tracking code:

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-28789452-3', 'auto');
  ga('send', 'pageview');
</script>
Common tracking functions

There is a shared function file that can be used to call a simple sendAnalyticsEvent function and sendAnalyticsTiming function. See this file for detailed use.

What do I track?

We'll create specific events for most interactives, but track events for the following situations as a default:

Track timing functions once when necessary. This could be for seeing how long a user spends on a specific section that isn't automagically tracked by the page.

Unit testing

We'll be setting up unit tests using QUnit to confirm functionality continues to work as the interactives are built and changes are made. For an introduction to unit testing, please read QUnit's Intro to Unit Testing and the QUnit Cookbook.

Setting up tests

In each interactive's project folder, there is a test directory. For each function/method, there should be a test HTML file that runs through each aspect of that function to ensure that any data or DOM manipulation still runs successfully. As you build project features, be sure to write your tests as you go.

Deployment

We will use Grunt to generate the deployment/installation versions of the interactives. Each interactive will have a specific deploy script (coming soon) that will package that interactive up with its appropriate assets and data—relevant for the interactives that are built to be used as templates.

What to send to NMAI for final delivery