generator-homework

A Yeoman generator for fuss-free creation of web-based homework submission files. This was created for CS 3300 Data-Driven Web Applications at Cornell University.

Table of Contents

1. Quick Start
2. Setting Up Dependencies
3. Generator Details
4. File Structure
5. index.html
6. app.js
7. styles.css
8. Optional, Fun Stuff
9. CSSComb
10. JSCS
11. JSHint and ESLint

Quick Start

Install this generator globally using NPM:

npm install -g generator-homework

If running this command causes your CLI to pop errors, it's likely that you do not have NPM installed on your system. If that's the case, follow the instructions in the next section to set up your dependencies, and come back here after that. Otherwise, create a new folder for the current homework being attempted:

mkdir homework1
cd homework1

Roll up your sleeves, pray that the professor didn't make this one too difficult, and...

yo homework

Provide your name, Net ID, and select the homework you're working on from the list that appears. The generator will populate the directory with everything you need. Remember to save your work, and submit frequently!

Setting up Dependencies

This generator is distributed via NPM, and relies on Yeoman for templating, interaction with the file system, and command line output.

If you don't already have NPM, you'll want to head over here and grab the version of Node.js (which bundles NPM in its download) that works for your system. Once you've got that installed:

sudo npm install -g npm

This uses NPM to upgrade NPM, ensuring that you have the latest version. Yes, you did not read that wrong, and there's nothing wrong with the command either. If you're using Windows, drop the sudo and run everything else from an elevated CLI.

Next, use NPM to install Yeoman globally:

npm install -g yo

On behalf of the good folks at Yeoman, we feel the need to inform you that the unfortunate choice of name was made long before the eponymous social media application came into existence. They are thoroughly unrelated.

You now have all your system dependencies in order. Follow the quick start instructions and have fun!

Generator Details

For the curious, here's what the generator actually does, and how you can make the most out of it. These explanations sacrifice brevity in the name helping novice users understand the functionality involved. Advanced users, enjoy the read?

File Structure

Running the generator in a directory creates the following file structure:

.
├── js/
│   ├── vendor/
│   │   ├── topojson.min.js
│   │   └── d3.min.js
│   └── app.js
├── css/
│   ├── vendor/
│   │   └── normalize.css
│   └── styles.css
├── index.html
├── .jshintrc
├── .jscsrc
├── .gitignore
├── .eslintrc
└── .csscomb.json

Wherever it is seen, a vendor directory contains files from third-party libraries. This nomenclature is fairly common in most well-designed projects/frameworks, and we have adopted it accordingly. A caveat: one may or may not see the files in js/vendor depending on whether the current homework being attempted requires those libraries.

Files that begin with a period are hidden in OSX, but we pinky swear they're there. They're mainly configuration files for third-party tools which you may or may not want to use. More on that down below.

index.html

The only visible file in the root directory is index.html, which contains the HTML markup for the current homework being attempted. We've adopted the conventions prescribed by HTML Boilerplate with further modifications that suit our purposes.

The generator uses your name and Net ID to populate identifier tags in the header, as well as the document title. The former allow us to identify your submission programatically if we ever go through it with an autograder. By default, we include Nick Gallagher's normalize.css to "reset" browser styling quirks. You should not need to worry about what this does, though it makes for interesting bathroom reading.

When you select a homework option from the list that is shown to you, preconfigured question numbers are used to generate corresponding <answer> tags in the document body. These allow us to go through your submission and extract answers in a systematic manner. It's important that you change neither the syntax of the <answer> element, nor the for attribute. Changing the former prevents us from knowing what plain text is an answer (versus what is code/markup), and changing the latter means that answers will be paired with wrong, or non-existent questions.

The bottom matter imports JavaScript files that are used to provide added functionality in the HTML document. If the current homework requires the use of d3.js or TopoJSON, the generator will automatically do the grunt work of including these libraries for you. There are two parts to this. The first <script src> declaration is a link to a Content Delivery Network (CDN). These servers cache updated versions of the libraries in multiple locations around the world, and are used to load files very quickly. They're a preferred method of loading libraries (as compared to loading them from your own server, which could be thousands of miles away). However, sometimes the CDNs get overloaded, which is why there's a second declaration, which tests if the library has loaded, and if it hasn't, loads it from a local source. In our case, the local source is an identical copy of the library found in js/vendor.

The only changes you should make to this file are to delete the comments in the <answer> tags and replace them with your answers to the corresponding questions.

app.js

In short, this is where any JavaScript you write should go. In casual use cases --- read: us --- there should be no (as in zero, zilch, nada) JavaScript code in your HTML file because it will block the rest of the page load. Any JS you write should be in an external file which is imported into the main HTML file. We've done that bit for you.

The novice user will wonder why there is an anonymous JS function call in app.js, and why code that is written is encapsulated in this anonymous function. Said function is called an IIFE - Immediately Invoked Function Expression. It's a function that, upon being created, is immediately called. This is used to prevent contamination of the global namespace. For example, if one were to declare var foo = 'bar' within the IIFE, foo exists only within the scope of the anonymous function, and not in the global browser namespace. This prevents things with the same name in two different files from overwriting each other. Nifty, yes?

The only changes you should make to this file are to delete the comment as instructed and replace it with your JS code. Nothing about the way you write code needs to change.

styles.css

The direct analog of app.js, this is where you should chuck all your CSS declarations. When starting out, one might be tempted to style their elements directly in the HTML markup, like so:

<p style="font-size: 314px; margin-top: 20px;">Lorem Ipsum</p>

There are cases where doing such a thing is valid (if you want to learn more, read up on CSS Specificity), but as far as we've seen in CS 3300, you will not run into those cases. Therefore doing something like this causes bunnies to die, because code becomes hard to read and maintain.

Declare your styles in this file, and reference them by assigning classes to your HTML elements.

Optional, Fun Stuff

Eye-tracking studies done in a secret underground laboratory tell us that half the readers of this document will by now have keeled over, spewed vomit over themselves, and gone off to the nearest house party in search of salvation. The other half want more, and we live to serve :)

What this means is that if all you'd like to do is finish your homework, and it's currently a couple hours before the deadline, you can stop reading here.

For ye' brave souls that remain steadfast, your dedication will be rewarded.

Build pipelines for good projects often use third-party tools to check and beautify their code. The former significantly decreases the amount of hair-pulling that occurs when debugging a large-ish code base, and the latter makes it easy to work on something after you've left left it alone for a couple of days, or if you're working in a group. Thankfully, these things are not too difficult to set up, and we've given you a boost in the form of preset configurations.

From here on, we'll assume that you know what you're doing and omit the lengthy explanations. Don't feel shy about pinging the course staff if you encounter any problems. There's always plenty of healthy respect for anyone who tries to learn new things.

CSSComb

CSSComb re-orders your CSS properties and declarations, keeping everything neat and tidy. We've provided a set of sane configurations in the form of .csscomb.json, which should work for most, if not all purposes.

To install:

npm install -g csscomb

To run:

csscomb css/styles.css

JSCS

JSCS automatically reformats your code to enforce code style. In class, we'll recommend adhering to AirBnB's JavaScript Style Guide, which can get irritating if you've never done it before. Running JSCS on your code allows you to whack it into shape without doing too much yourself - at least until you get used to it. As usual, we've provided a set of sane configurations in the form of .jscsrc that automatically enforce AirBnB's style.

To install:

npm install -g jscs

To run:

jscs js/app.js

JSHint and ESLint

The world of linters! JSHint and ESLint are two commonly use "linters" that go through your code line-by-line, picking out potential errors. For example, they could identify places where you've used == instead of ===, or places where you've modified a global variable in a loop. When used correctly, they help you write very robust code. Once again, we've provided you with configuration files for both of them (.jshintrc, and .eslintrc). Note that you should only use one or the other – JSHint is less strict, whereas ESLint is known to be more rigorous. Pick your poison!

To install:

npm install -g jshint
npm install -g eslint

To run:

jshint js/app.js
eslint js/app.js

Roadmap

• [ ] Swap out JSON configuration files for a Git hook/endpoint.
• [ ] Add support for EditorConfig

Versioning

Development will be maintained under the Semantic Versioning guidelines as much as possible in order to ensure transparency and backwards compatibility.

Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)
• New additions without breaking backward compatibility bump the minor (and resets the patch)
• Bug fixes and miscellaneous changes bump the patch

For more information on SemVer, visit http://semver.org/.

Bug Tracking and Feature Requests

Have a bug or a feature request? Please open a new issue.

Before opening any issue, please search for existing issues and read the Issue Guidelines.

Contributing

Please submit all pull requests against *-wip branches. All code should pass JSHint/ESLint validation.

License

The MIT License (MIT)

Copyright (c) 2015 Kenneth Lim

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.