Created with the grunt-init gui template.
- Install grunt and its dependencies
This applies whether you are initialising the project, or you've cloned the repo from GitHub (as development dependencies are excluded from the repo by .gitignore):
$ npm install
This section obviously only applies if you are initialising the project.
- Create local repo
$ git init
$ git add .
$ git commit -m 'first commit woo!'
- Create remote repo
For clarity, it is recommended that you give the repo the same name as this project (guess-the-sound):
http://github.com/organizations/GuardianInteractive/repositories/new
- Link the two
Assuming you called the remote repo guess-the-sound, you would do
$ git remote add origin https://github.com/GuardianInteractive/guess-the-sound.git
$ git push -u origin master
- Start grunting
$ grunt
To watch the styles and data folders for changes:
$ grunt watch
To launch a server - http://local.static.guim.co.uk:9876 (you can change the port in Gruntfile.js):
$ grunt server
It is recommended that you edit your hosts file so that
local.static.guim.co.uk
redirects tolocalhost
. This avoids cross-domain nonsense, e.g. with fonts. But if you haven't done that you can still access the site at http://localhost:9876).
- Create your app
Project anatomy:
-
boot
your boot files, which are responsible for doing any feature detection or picking a code path (if multiple code paths exist, e.g. mobile vs desktop), then loading the interactive. These files have access to<%= projectUrl %>
and<%= versionDir %>
variables, which are set as appropriate on deployment -
data
files in here will be bundled together as data.json (see grunt-dir2json for more info) -
gubbins
for project-specific stuff that shouldn't end up in the finished product, e.g. artwork, shell scripts, Excel files, whatever -
js
your scripts. The project template currently assumes you are using AMD -
preview
files to enable previewing the project at different screen sizes etc. (This folder also containsdefault.html
, which is used to render the finalindex.html
) -
files
any additional files you want to include in the project, besides your index.html, min.css and data.json files (which are auto-generated). E.g. images -
styles
.scss files, from whichmin.css
is generated -
codeobject.html
the markup that the user is presented with at launch, whether it is squirted onto a Guardian page, or part of a dedicatedindex.html
file
(The above is correct at the time of writing... if it looks out of date, please correct!)
- Build
$ grunt build
You can check that the built version behaves as expected by doing
$ grunt sanitycheck
and visiting http://local.static.guim.co.uk:9876.
- Deploy
You will need to have AWS credentials, either in your environment or in a JSON file somewhere. To add credentials to your environment on OS X, open ~/.bash_profile
and add the following lines (with your details, natch):
export AWS_ACCESS_KEY_ID='yourKeyIdHere'
export AWS_SECRET_ACCESS_KEY='yourSecretAccessKeyHere'
Alternatively add the credentials to a JSON file, and specify its path as the credentials
option to the deploy
task:
{
"accessKeyId": "yourKeyIdHere",
"secretAccessKey": "yourSecretAccessKeyHere"
}
It is possible to specify credentials directly within the task config. Do not do this. You may accidentally push your credentials to GitHub.
To deploy, simply do
$ grunt deploy
This will upload the contents of the dist
folder to our S3 account (the gdn-cdn
bucket). It will then be accessible from http://interactive.guim.co.uk/2013/jul/guess-the-sound/v/1/index.html (the version number will increment with each deploy).