Small.JS

Debug

Toby Ho — 2014-04-30T00:00:00.000Z

Debug is a small library for logging debug messages. Since it is just a wrapper around console.log, it works in both Node and the Browser. It allows you to filter logging output without changing your source and it also outputs time differences which lets you easily tell how much time has elapsed between log messages.

Log The Things

To log messages using debug, first create a logger:

var Debug = require('debug'); var debug = Debug('main');

require('debug') gets you the debug module - which is a function, I will call that capitalized Debug. Calling Debug with a name gives you a logger - which is also a function - we will call that lowercase debug. Now you can use it to log messages:

debug('Hello, world!'); setTimeout( debug('Hello again!');

Seeing The Logs

If you save the above example as run.js and run it with Node:

$ node run.js

Nothing happens. Don't panic! It's just that debug hides messages by default. You need to configure the logger to output messages from the logger(s) you want to see. For now we'll set visibility to everything by setting the DEBUG environment variable to *.

Sweet! Notice that the output contains the logger name, the message, and the time difference between the current and previous log messages. Oh, and nice colored text output too.

In the browser, configuration is done via the Debug.enable() method, like so:

Debug.enable('*');

The configuration setting is persisted across browser refreshes via localStorage, which is convinient for debugging.

<side-note> Okay, this may be one of the very few times where something looks better in the terminal than it does it the browser. What?!! Though I was told that on some browsers at least, you can now style console.log output - pull request anyone? </side-note>

Now lets look at different ways you can filter the log messages.

Filtering The Logs

The wildcard * is what to do if you want to see all the log messages going through debug, but debug is more useful when you want to filter down debug messages to specific modules you are having trouble with. So let's say you have a calculator module that looks like this (calculator.js):

module.exports = { add: function(one, other){ return one + other; } }

With the debug module, we can instrument it with debug statements like this:

var debug = require('debug')('calculator'); module.exports = { add: function(one, other){ debug('Adding numbers:', one, other); var result = one + other; debug('Result:', result); return result; } }

Then you have a main.js script that uses calculator.js:

var debug = require('debug')('main'); var calc = require('./calculator'); var num1 = prompt('First number'); var num2 = prompt('Second number'); var result = calc.add(num1, num2) debug('result:', result); alert('Result is ' + result);

We have a bug somewhere. Let say that we suspect the problem to be in calculator.js, we can just turn on debug logging for it in the JS console:

> Debug.enable('calculator')

Now rerun the code and you shall see the log messages for calculator.js.

To see output for more than just one module, i.e. both main.js and calculator.js, use a comma to separate them:

> Debug.enable('calculator,main')

Debugging this code is left as an exercise for the reader ;)

Wildcards

You can use the wildcard * to pattern match module names - this is useful for modules that have submodules. For example, maybe your calculator module got complicated and you split the code into calculator/add.js and calculator/multiply.js. As a simple convention, both files can use the same prefix for their logger names:

// in calculator/add.js var debug = require('debug')('calculator:add'); // in calculator/multiply.js var debug = require('debug')('calculator:multiply');

Now, if you want to see only messages for add.js, you can specify the specific logger as

> Debug.enable('calculator:add')

But, if you want to see the messages for either submodule, you can simply configure it using a wildcard

> Debug.enable('calculator:*')

Bye!

To learn more about debug, check out the readme, or just read the source, cause seriously it's tiny.

Page

Toby Ho — 2014-04-17T00:00:00.000Z

Page is a small client-side routing library for use with building single page applications (SPAs). It has a simple API which is inspired by Express. It utilizes the HTML5 history API under the hood, which is what allows you to build smooth user interfaces while still having linkable URLs for different pages of the app.

Routing

Page supplies you a page function which has a few different roles:

var page = require('page');

The first of those roles is specifying routes. If you've use Ruby on Rails or Express or a similar framework, this should look familiar:

page('/', function(){ // Do something to set up the index page }); page('/about', function(){ // Set up the about page });

Your routes can contain parameters, which you can assess through the context parameter to your route handler

page('/user/:id', function(context){ var userId = context.params.id; console.log('Loading details for user', userId); });

You can use wildcards as parameters too, in which case you will need to use array indexing to access the parameters:

page('/files/*', function(context){ var filePath = context.params[0]; console.log('Loading file', filePath); });

A key difference between using a wildcard vs a named parameter is that a wildcard can match the character "/", while a named parameter cannot. In our file path example, using a wildcard allows filePath to contain arbitrarily nested subdirectories.

Another useful thing you can do with a wildcard is to define a fallback route:

page('*', function(){ console.error('Page not found :('); });

Starting The Router

Once you have all your routes defined, you need to start the router, which is done with another call to page, but this time with no parameters:

page();

If you are weirded out by this, and prefer to be more explicit, you can instead write the equivalent:

page.start();

Both of these can take an optional options object, containing the properties:

click - whether to automatically bind to click events on the page and intercept link clicks and handle them using page's router - defaults to true.
popstate - whether to bind to and utilize the popstate event - defaults to true.
dispatch - whether to perform initial route dispatch based on the current url - defaults to true.

As mentioned above, page will by default automatically intercept clicks on links on the page and try to handle it using the routes you've setup. Only if it can't match the url with any of the define routes will it default back to the browser's default behavior. Sometimes though, you may want to change the URL based on other events. Maybe the element clicked happens to be something other than a link. Or, if you are building a search page, you may want to allow users to share the URL to their search results. You can do this by just calling page function with the page you want to navigate to:

$(form).on('submit', function(e){ e.preventDefault(); page('/search?' + form.serialize()); });

If you prefer to be more explicit, you can use page.show(path) instead.

Route Handler Chaining

A cool feature of page is that it allows for route handler chaining, which is similar to Express's middlewares. A route definition can take more than one handler:

page('user/:id', loadUser, showUser);

Here, when the path user/1 is navigated, page will first call the loadUser handler. When the user is done loading, it will call the showUser handler to display it. How does it know when the user is done loading? A callback is provided to the handlers as the second parameter - here is what loadUser might look like:

function loadUser(ctx, next){ var id = ctx.params.id; $.getJSON('/user/' + id + '.json', function(user){ ctx.user = user; next(); }); }

Then, in showUser you can get at the user through ctx.user. Now this is nice because you can reuse the loadUser function for, say, the user/:id/edit route.

States

The History API supports saving states along with each history entry. This allows you to cache information along with previously navigated URLs, so that if the user navigates back to them via the back button, you don't have to to re-fetch the information, making the UI much smoother. Page exposes this via the state property of the context object. To make the above loadUser function utilize this cache, you would write this:

Putting It All Together

Now that you know what you need to know about page, let's build an example application. The app will render a list of the earliest Github users. You can click on an individual user and get more details about him or her. The back button should work seamlessly and should use caching. This will use the modules page, superagent, and mustache.

var page = require('page'); var request = require('superagent'); var mustache = require('mustache');

These are route definitions:

page('/', loadUsers, showUsers); page('/user/:id', loadUser, showUser);

The implementation of loadUsers and loadUser look like this, much like the previous state-caching example:

For rendering the pages, this will use mustache, and I've made the following templates:

var listTemplate = '<h1>Early Github Users</h1>\ <ul>\ {{#.}}\ <li>\ <a href="/user/{{id}}">{{login}}</a>\ </li>\ {{/.}}\ </ul>'; var showTemplate = '<h1>User {{login}}</h1>\ <p>{{name}} is user number {{id}}. \ He has {{followers}} followers, \ {{public_repos}} public repos and writes a blog at\ <a href="{{blog}}">{{blog}}</a>.\ <a href="/">Back to list</a>.</p>\ ';

There are ways to lift the markup into .html files, but I'll save that for another day. To render these templates is job of showUser and showUsers:

function showUsers(ctx){ var users = ctx.state.users; content.innerHTML = mustache.render(listTemplate, users); } function showUser(ctx){ var user = ctx.state.user; content.innerHTML = mustache.render(showTemplate, user); };

And finally, we need to start the router:

page.start();

And there you have it! A multi-page single page application. If you want to poke around with this code, take a look at the full source code, which has been modularized into small files.

JSDiff

Toby Ho — 2014-04-10T00:00:00.000Z

JSDiff is an implementing of text comparison in Javascript, it is used in Mocha to implement colored diffs, and it's fairly easy to use.

Let's say you have two strings: oldString and newString

var oldString = 'beep boop'; var newString = 'beep boob blah';

To compare them you may use the diffChars method

var diff = JsDiff.diffChars(oldString, newString);

This gives you diff which is an array of change objects. A change object represents a section of text which is has either been added, removed, or neither. It has the following properties

value: text content
added: whether the value was inserted into the new string
remove: whether the value was removed from the old string

In the above example, if you'd log the diff object, you'd see

[ { value: 'beep boo', added: undefined, removed: undefined }, { value: 'b blah', added: true, removed: undefined }, { value: 'p', added: undefined, removed: true } ]

To render this information visually, we can color code these text chunks. In Node, there's a module colors which makes outputing colors to the terminal easy.

diff.forEach(function(part){ // green for additions, red for deletions // grey for common parts var color = part.added ? 'green' : part.removed ? 'red' : 'grey'; process.stderr.write(part.value[color]); });

If you run this program (see full source code) you should see

You can also use JSDiff on a web page by using browserify or just via <script> tag. To render the same diff using DOM elements - using the raw DOM API would look like

var display = document.createElement('pre'); diff.forEach(function(part){ // green for additions, red for deletions // grey for common parts var color = part.added ? 'green' : part.removed ? 'red' : 'grey'; var span = document.createElement('span'); span.style.color = color; span.appendChild(document .createTextNode(part.value)); display.appendChild(span); }); document.body.appendChild(display);

The result of that code (full source, or on requirebin) would look like

But wait, there's more. Take a look at JsDiff's API, it can also

compare by word.
compare by line.
compare CSS.
create patch files for use with the patch) program.

This article was originally posted at http://tobyho.com/2013/11/05/jsdiff-for-comparing-text/.

Browserify

Toby Ho — 2014-04-02T00:00:00.000Z

Browserify is a build tool that lets you use Node's CommonJS module system for frontend JavaScript development. It integrates seamlessly with npm, and you can use the same smooth npm workflow for installing and publish modules. For this reason, we've seen the rise of frontend JavaScript modules being published to npm. Browserify also opens up the possibility of code reuse between the server and the client - if you have a Node backend.

To learn more about using npm itself and using it to write server-side Node programs, check out the npm article.

The Gist

Pretend you are writing a Node program. You are probably doing these things:

Install some modules: npm install a_module.
Write some code: vi myprogram.js (or substitute your favorite editor in place of vi).
Test some code: node myprogram.js.

With Browserify, you still have these same steps, but you also add a build step, and testing your code involves opening up a browser:

Install some modules: npm install a_module.
Write some code: vi myprogram.js.
Build the bundle: browserify myprogram.js -o bundle.js
Test some code: <script src="bundle.js"></script>.

And that's Browserify in a nutshell.

The Walkthrough

Now, a walkthrough for those who like to get their hands dirty. I will go quick because I will assume familiarity with npm.

Installing

First, you'll need to install Browserify, obviously:

npm install browserify -g

This should install the browserify executable. On some platforms, you may need to use sudo i.e. sudo npm install browserify -g if you are getting permission error issues.

Create A Project

Create a new project directory and create a package.json file

mkdir browserify_hello cd browserify_hello npm init

Grab Some Modules

npm install lodash --save npm install superagent --save npm install spin --save npm install dom-events --save

Write Some Code

The following code will implement a Github repository search engine. First, make a index.html that contains a basic search UI:

<!doctype html> <html> <head> <title>Browserify Hello</title> </head> <body> <label for="search">Search Github</label> <input id="search" name="search" type="search"> <button id="button">Search</button> <div id="results"></div> <script src="bundle.js"></script> </body> </html>

Next make an index.js:

Bundle It

browserify index.js -o bundle.js

Run It

Open index.html in you browser, and test it out. You should now have a functioning Github repository search engine, and it even has a spinner while the results are loading!

Shimmed Node.js Environment

The above example used lodash, dom-events, superagent, and spin. But you might be wondering: can I use just any module off of npm? The answer is: not exactly. Although, Browserify does make a valiant effort.

Browserify makes some modifications to the browser environment to make it look like the Node environment. You have access to things like:

You can use Node core modules like:

See the docs for the full list. For a given module, these shims make it much more likely for it to work in the browser, but it's not a guarantee. In practice this is not a big problem, because frontend code and backend code generally do very different things anyway, so it's actually a good idea to keep them separate where it makes sense. But this does present a challenge: how does one find frontend modules on npm? Searching on npm, the only way to know for sure whether a module can work with browserify or not is by installing it and then running Browserify on it. Unfortunately, there's no home-run solution to this yet, but people are working on it and this should get easier soon.

Source Maps

Since Browserify transforms your source code and dependencies all into one single bundle, debugging can become difficult when you are stepping through the debugger and line numbers that don't correspond to your actual source. Luckily, there's source maps! To turn on source maps just use the --debug option. However, last I checked in Chrome, line numbers in error stack traces still do not get remapped.

Transforms

Browserify also supports performing source transforms as part of the build process. Using source transforms, you can support preprocessor languages like CoffeeScript, EcmaScript 6 syntax, even markup templating languages like Jade and CSS preprocessor languages like Sass and Less.

For example, to use CoffeeScript, just install the coffeeify module and pass it in via the -t option:

npm install coffeeify browserify -t coffeeify index.coffee -o bundle.js

Take a look at the List of Transforms to see what else is possible with transforms.

Automation

Having to do a manual compilation step every time you change a file gets old really fast. As you might have guessed, there are tools for that:

Grunt-Browserify: there's a Grunt plugin for that!
vinyl-source-stream appears to be the prefered solution for Gulp + Browserify.
watchify - if you just want a standalone watcher.
beefy - spin up a development server that automatically Browserifies your entry point .js file on the fly.
bff - like beefy, but doesn't require you to specify an entry point .js.

If you prefer to build your own tooling, Browserify can be used as a Node module:

var browserify = require('browserify'); var fs = require('fs'); browserify(['./index.js']) .bundle(function(err, code){ if (err) return console.error(err.message); fs.writeFile('bundle.js', code); });

RequireBin: Browserify Playground

Okay, if you are too lazy to even use the automation tools, give requirebin.com a try. It is like a jsbin that integrates with Browserify and npm modules easily. Go there and you can start requiring npm modules right away, and run it. You don't even have to npm install.

jQuery And MV* Frameworks

Although the premise of Small.js is to forego large frameworks in favor of building things from scratch using small modules, I recognize that you can get a lot of benefit from building in small modules atop a larger foundation as well. Plus, this seems to be a common issue people run into, so, I'll cover how Browserify works/interacts with some of the popular frameworks.

jQuery - jquery became a proper npm package starting version 2.0, which means you can npm install jquery and var $ = require('jquery'), glorious!
Backbone - backbone has long been available on npm, in fact it has proved useful for server-side applications.
AngularJS, Ember, Marionette and other frameworks not directly available on npm as client packages - I recommend downloading the framework separately either as a direct download or by using bower (to be covered in a separate episode). Include the scripts separately via script tags or via your build process. You can then manage the rest of your dependencies using npm and Browserify by adding another script tag for the browserify bundle.

Homework

Yes, homework! I can tell you were hoping that I would forget about homework, but I didn't, ha!

You homework is to find and discover a new module on npm - one that you did not already know about - install it, and use it with Browserify by building a simple toy application. Have fun!

array

Toby Ho — 2014-03-26T00:00:00.000Z

If you are like me, you had a background in another programming language before getting familiar with JavaScript. Also, if you are like me, the thought "WTF" might have come up once or twice as you were learning JavaScript's array API. Gradually though, you've familiarized yourself with the array, and it has become second nature to you. The array API is actually not that bad, especially after the functional style methods were introduced in Ecmascript 5. But still, it could be better - which is the aim of the module I am covering - simply called array. array provides events that allow observers to be notified of changes in the array and adds convinient shorthands for functional style methods.

The Constructor

First things first: as a convention, we will aliase array's constructor to array:

var array = require('array');

To make a new array, call the constructor:

var arr = array();

Alternatively you can pass an existing native array as its argument and it will initialize to the contents of that array:

var numbers = array([1, 2, 3]); // => array instance representing [1, 2, 3]

Unlike the native array constructor, you can't pass a variable list of parameters to it or initialize it with a "size" argument:

var arrayOfNames = array("Bob", "Jen", "Ben"); // things will go horribly wrong var arrayOf5Things = array(5); // things will also go horribly wrong

Array Methods

array implements most of the native array methods you know and love. In most cases (with some caveat) it can be a drop-in replacement for the native array, but there are also some differences. Later in this article I will list its differences to native arrays.

Events

Events allow observers to be notified of changes to the contents of the array, which can be useful for building user interfaces. array is an event emitter, so you can register for change events using the on() method

arr.on('change', function(){ console.log('Array has changed!'); });

The following events are emitted:

add (item, index) - when items are added to the array (push, unshift, splice).
remove (item, index) - when items are removed from the array (pop, shift, splice).
sort - when array is sorted.
reverse - when array is reversed.
change - whenever array is modified - emitted at most once for every mutating operation.

Functional Shorthands

Like the native array, array has the functional programming style helper methods like map() and filter(), etc (filter is also aliased to select()). array adds a twist to them by allowing you to specify the criteria in shorter and more expressive ways than anonymous functions. So instead of writing

var firstNames = users.map(function(user){ return user.name.first; });

You can write

var firstNames = users.map('name.first');

You can use shorthands for filtering an array as well. Here's the before:

users.select(function(user){ return user.age > 20; })

And here's the after:

users.select('age > 20')

Another syntax is:

users.select({age: 14}) // this finds users whose age === 14

It does this using the to-function behind the scenes - so take a look at to-function to find out all the different ways you can write matchers. Some other methods that support shorthands are:

unique(fn|str) - return a new array whose items are unique wrt to the criteria.
reject(fn|str) - return a new array with all items which match the criteria removed.
none(fn|str) - returns true iff none of the items satisfy the criteria.
any(fn|str) - returns true iff at least one of the items satisfy the criteria.
find([fn|str]) - returns the first item that satisfies the criteria or undefined.
findLast([fn|str]) - returns the last item that satisfies the criteria or undefined.

For refenence to all methods, take a look at the docs.

`sort()`

The sort method adds some extra shorthand for easily sorting by a criteria. For example, with a native array, if you wanted to sort by the calories property of the contained items, you would write a compare function:

function compareCalories(user1, user2){ if (user1.calories > user2.calories){ return 1; }else if (user1.calories < user2.calories){ return -1; }else{ return 0; } } users.sort(compareCalories);

With array, you can simply do this:

users.sort('calories');

If you want to sort in descending order instead, you can do:

users.sort('calories', 'descending');

Differences To Native Array

Although array's interface mimics the native array for the most part, there are some differences. These are the differences I've found:

the length property doesn't auto-magically update when you set a index of the array beyond it's current size. This shouldn't be a problem because normally, the best practice is to avoid using this feature and use push or splice to add items.
doesn't skip holes properly - i.e. [1, ,3].

For more information about array, visit the project page.

Introduction to npm

Toby Ho — 2014-03-19T00:00:00.000Z

This time on small.js: npm - the granddaddy of JavaScript package managers. npm is the beloved package manager for Node. It hosts over 64 thousand modules and counting. Based on data at modulecounts.com - npm is by far the fastest growing package manager, that's is compared to Ruby Gems, CPAN, PyPI, Maven plus a few others. I believe this tremendous rate of growth has everything to do with the ease with which you can write and publish an npm module - we will get to that.

npm isn't limited only to Node modules, however. Client-side JavaScript modules have also found a home on npm. In an upcoming article I will cover how to use client-side modules on npm with Browserify, but I am getting ahead of myself. First, let's start from the beginning.

Getting npm

npm comes preinstalled with Node. If you have node, you already have npm! If not, install Node - it's as easy as downloading and then running an installer.

Installing Modules

npm wants to keep dependencies of different projects separate and isolated - this is a good thing. So first, make a project:

mkdir npm_hello cd npm_hello

Now you are ready to install modules! Try this

npm install cheerio

That installs cheerio. Cheerio is a fun module - it gives you a jQuery API for parsing and manipulating a HTML document in Node - without a real browser. For example, the following script (save it as run.js) extracts the text within each <li> in a HTML snippet:

var cheerio = require('cheerio'); var $ = cheerio.load( '<ul>\ <li>Bob</li>\ <li>Benny</li>\ </ul>'); $('li').each(function(){ console.log($(this).text()); });

If you run it, you should get this result:

$ node run.js Bob Benny

Note the thing that you require - the string "cheerio" - is the same as the thing you install on the command line. This is always the case with npm, and it is nice because it removes ambiguity - it's one less thing you have to think about. It also means that if you are reading someone else's script and see require('abc'), they almost certainly got it from npm install abc.

We are off to a great start. Why not install another one? Let's install superagent - which I covered previously.

npm install superagent

This following script fetchs and prints the titles of latest posts on Hackernews:

var cheerio = require('cheerio'); var request = require('superagent'); request.get('https://news.ycombinator.com/') .end(function(reply){ var $ = cheerio.load(reply.text); $('td.title a').each(function(){ console.log($(this).text()); }); });

Run that and I got (actual result may vary)

[Full-disclosure] Administrivia: The End Tired of doing coding interviews on Skype? We've built this The sierpinski triangle page to end most sierpinski triangle pages Nodemailer: Easy as cake e-mail sending from your Node.js applications What Happens to Older Developers? Needy robotic toaster sells itself if neglected Cleaning up from an IMAP server failure ... goes on for about 30 more lines ...

Look, you just made a web scrapper! Easy right? Such is the power of modules - you can connect them together like legos to make something new and brilliant!

A Closer Look: Nested Dependencies

If you've been following along, you probably noticed that npm has created a node_modules directory inside the project directory. This is where the installed modules reside. A look inside the directory shouldn't surprise you:

$ ls node_modules cheerio superagent

But, you might be wondering, do these modules have any dependencies? If so, where are they? You may remember from the first Component tutorial that Component installs the dependencies of the requested module in the same directory as the requested module. npm does things differently - it installs the dependencies in yet another node_modules directory within that module's subdirectory, and this "module nesting" can keep going indefinitely. In our scenario, we have this directory structure:

npm_hello ├run.js └node_modules ├cheerio │ └node_modules │ ├CSSselect │ │ └node_modules │ │ ├CSSwhat │ │ └domutils │ │ └node_modules │ │ └domelementtype │ ├entities │ ├htmlparser2 │ │ └node_modules │ │ ├domelementtype │ │ ├domhandler │ │ ├domutils │ │ └readable-stream │ │ └node_modules │ │ ├core-util-is │ │ ├debuglog │ │ └string_decoder │ └underscore └superagent └node_modules ├cookiejar ├debug ├emitter-component ├extend ├formidable ├methods ├mime ├qs └reduce-component

That's a lot of modules! You can also visualize the module dependency hierarchy using npm list:

$ npm list .../npm_hello ├─┬ cheerio@0.13.1 │ ├─┬ CSSselect@0.4.1 │ │ ├── CSSwhat@0.4.5 │ │ └─┬ domutils@1.4.0 │ │ └── domelementtype@1.1.1 │ ├── entities@0.5.0 │ ├─┬ htmlparser2@3.4.0 │ │ ├── domelementtype@1.1.1 │ │ ├── domhandler@2.2.0 │ │ ├── domutils@1.3.0 │ │ └─┬ readable-stream@1.1.11 │ │ ├── core-util-is@1.0.1 │ │ ├── debuglog@0.0.2 │ │ └── string_decoder@0.10.25-1 │ └── underscore@1.5.2 └─┬ superagent@0.17.0 ├── cookiejar@1.3.0 ├── debug@0.7.4 ├── emitter-component@1.0.0 ├── extend@1.2.1 ├── formidable@1.0.14 ├── methods@0.0.1 ├── mime@1.2.5 ├── qs@0.6.5 └── reduce-component@1.0.1

Note that we can see the version number of each module too. One thing that's interesting to note is that two of the modules installed - domutils and domelementtype - are duplicates: there are two copies of each of them. That seems redundant and inefficient. Why does npm do that? There's actually a good reason - this makes it possible for two or more parent modules to depend on different versions of the same child module. In our scenario, both cheerio and htmlparser2 depend on domutils, but cheerio uses version 1.4.0 while htmlparser2 uses version 1.3.0. In general, this ability to load different versions of the same module in different contexts but still within the same app avoids a whole class of problems that have to do with version conflicts - sometimes referred to as DLL Hell. In the land of Node, there is no DLL Hell, and we all all happier for it. Is it a little less efficient in terms of disk usage? Yes, but disk is cheap, frustration is more expensive - I think this is a worthwhile tradeoff.

Making It Your Own

Now that you've gotten your feet wet, the next step is to write and publish your own module.

Setting Up A Module

The one file every module needs is package.json. Typing this file out by hand is a little tedious. Fortunately, npm init semi-automates this by asking you a series of questions on the prompt. If you are following along, use <your internet handle>-scrape as the module name. All fields except for name are optional, and you can just hit ENTER to skip them. This is how I answered the prompts

name: (npm_hello) airportyh-scrape version: (0.0.0) description: A simple web scraper. entry point: (index.js) test command: git repository: keywords: webscrapping author: Toby Ho license: (ISC) MIT

At the end it displays the resulting package.json, and you can go ahead with creating the file or abort. My file looked like this

{ "name": "airportyh-scrape", "version": "0.0.0", "description": "A simple webscrapper.", "main": "index.js", "dependencies": { "superagent": "~0.17.0", "cheerio": "~0.13.1" }, "devDependencies": {}, "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [ "webscrapping" ], "author": "Toby Ho", "license": "MIT" }

Note that npm automatically added superagent and cheerio as my module's dependencies because it found them in node_modules. Gee, that's swell, thanks npm! If you install a module after this point, and would like to add it as a dependency, simply use the --save option, as in npm install <a module> --save. If you deleted your node_modules directory for some reason, you can get all your dependencies back with the command npm install.

Writing The Module

npm also defined main - the entry point of the module - to be index.js. This is the file Node runs when someone requires the module. Using index.js to mean "top-level entry point" is a common convention, but you can use a different name if you wish. Before creating this file, consider what the API of the module would look like:

var scrape = require('airportyh-scrape'); var url = 'https://news.ycombinator.com/'; scrape(url, 'td.title a', function(err, data){ // check for err and/or deal with data });

The API should take 3 parameters:

url - the web URL to scrape
selector - the CSS selector to use to find elements of interest on the page
callback(err, data) - a function to be called when the results are ready. It should adhere to Node's callback convention of using the first parameter for errors. The second parameter in the callback is data found and should be an array of strings.

So, here's the index.js that implements this:

To test that this worked, modify run.js to use it:

var scrape = require('./index'); var url = 'https://news.ycombinator.com/'; var selector = 'td.title a'; scrape(url, selector, function(err, data){ if (err) console.error(err.message); return } console.log(data.join('\n')); });

Run to verify. Note that this time require is given a relative path: ./index - with Node/npm, this is how you require intra-project modules.

Go Forth And Publish!

Now you are ready to publish the module! If you've never published a Node module before, you'll need to register for an account on the npm registry, but that's easy:

npm adduser

This command will ask you for a username, password and your email address. You'd also use this command to login to your existing account in the case that you are on a machine that does not have your npm user information yet.

Next,

npm publish

Wait... Congratulations! You published your first npm module! If you check the npm website, you should see yours at or near the top of the "recently updated" list of modules. How does that feel?

Now, as an exercise for the reader: make a new test project; install your newly published module from npm, and then write or modify the existing run.js to test it.

Homework

What's that look? You knew you had homework, right? Your assignment is to add a command line utility as part of the module. If a user installs your module globally

npm install <your module> -g

They should be able to run this command from the shell

scrape https://news.ycombinator.com/ "td.title a"

and see the results. You'll need to create a cli.js in the module, and tell package.json about it via the bin property. For more information run npm help json and look for the "bin" section. You'll also need to inspect the process.argv array to get the command line arguments.

More Info

There's actually a lot more to npm that I haven't covered. Here are some good resources on npm:

Reactive

Toby Ho — 2014-03-11T00:00:00.000Z

Knockout and AngularJS have popularized the concept of declarative data binding in UI views. Reactive is a library that gives you this convinience in à la carte fashion.

Note: reactive does 1-way data binding: from the model to the view - it does not support 2-way binding. It can be made to approach 2-way binding behavior by declaring custom bindings.

Basic Example

Supposed you have the following "view" in your HTML page, which displays information about a person. It uses string interpolation to substitute in the name and age properties of said person:

You have a person object:

var bob = { name: 'Bob', age: 38 };

To wire up the view to the object:

var elm = document.getElementById('person-view'); reactive(elm, bob);

Bam! Now the view is populated with the values from the object.

Alternatively, the first argument can also be a string containing the template markup.

reactive('<div id="person-view">...</div>', bob);

But, since bob is a plain object, there is no way to tell the view that its value has updated. What we need is something that fires events - we can use an event emitter for this.

Event Emitter

An Person object that emits events can be written as:

function Person(name, age){ this.name = name; this.age = age; } Person.prototype = new EventEmitter; // or substitute your preferred // method of inheritance here.

bob can be instantiated as

var bob = new Person('Bob', 38);

And now, it can emit events to tell the view when its properties has changed:

bob.age = 39; bob.emit('change age');

At this point the age value in the view's display will update. Note that the name of the event reactive looks for by default is change <name of property>.

Backbone Model

If you use Backbone, I know what you are saying: why trigger the event manually? Backbone models will do that for you! Valid point. Reactive can do that! Reactive is pluggable and can be made to work with a variety of model implementations, including Backbone models. To do this, we need an adapter for backbone models. A model adapter is a constructor that takes a model object and implements the following methods:

subscribe
unsubscribe
unsubscribeAll
set
get

See the adapters documentation for more details on how to implement your own adapter. I've made it easy for you, here's the code for the Backbone adapter:

Note: I've put the Backbone adapter on github as a separate project.

Now, to test it out, first make a backbone model instance:

var bob = new Backbone.Model({name: 'Bob', age: 35});

Bind the backbone model to the view using reactive, supplying the backbone adapter

reactive(elm, bob, {adapter: BackboneAdapter});

And voila! Now the view will automatically update when the model's attributes are set - such as bob.set('name', 'Robert').

Everyone loves Backbone, right? If Backbone is not your thing though, that's okay too! For alternative model implementations, have a look at Bamboo and Modella.

String Interpolation

Now you are ready to take a closer look at Reactive's the string interpolation feature. Take this example:

Reactive interpolates expressions between { and }. The syntax can be simple properties, but can also be more complex JavaScript expressions, such as method calls:

{ name.toUpperCase() }

and string concatenation:

{ firstName + ' ' + lastName }

The properties used in these expressions will be bound automatically so that if they change, the view updates correctly.

Declarative Bindings

In addition to string interpolation, Reactive also provides declarative bindings - which are written as attributes of DOM elements. I'll walk through the most useful ones.

Event Bindings

You can use an event binding to delegate event handling to your code. To specify a handler for a click event on an element, you'd use the on-click binding:

The value specified - in this case: save - maps to a method in the delegate object, which you'll need to specify as an option to reactive. For example:

var delegate = { save: function(e, view){ var model = view.model; request.post('/api/person/', model.serialize()); } } reactive(elm, bob, { delegate: delegate });

All the common DOM events are supported, via on-<event name>.

`each` Binding

each gives you the ability to iterate an array of objects. It binds a model property - the value of which should be an array - and renders the original contents of the element once for each item in the array. Example:

<ul each="children"> <li>{last}, {first}</li> </ul>

Note: in order to be notified of changes in the array, the each binding duck punches the instance of array that's in use.

If you use Backbone, you might be wondering whether this can iterate a Backbone.Collection. Currently the answer is no.

`data-<attr>` Binding

data-<attr> binds a model property to an attribute of the element.

<a data-href="download_url">Download</a>

`data-visible` and `data-hidden` Bindings

data-visible binds a boolean model property. If the value is true, it adds the class visible to the element, otherwise, it addes the class hidden to the element. This allows for conviniently showing or hiding it - note that you'll need to write CSS rules to instruct the browser how you want to show or hide the element based on these classes (you could use CSS animations or simply display: none). data-hidden does the opposite of data-visible.

<p data-hidden="hasItems">no items</p> <ul data-visible="hasItems"> <li each="items">{name}</li> </ul>

`data-checked` Binding

data-checked binds a model property to the checked property of a checkbox.

`data-append` Binding

data-append appends a new DOM element.

The histogram property of the model is expected to contain a DOM element containing the desired widget.

More On Bindings

Read the docs for refenences on all the bindings. It is also possible to write your own custom bindings that do amazing things! I'll leave that as an exercise for the reader.

A View Pattern

There is a view pattern that works well for applications that use Reactive. It looks like this

function UserView(user){ this.user = user; this.view = reactive(html, user, { delegate: this // event delegate is set to the instance itself }); } // Event handlers via event binding can simply be written as methods UserView.prototype.edit = function(evt){ ... }

Event Emitter

Toby Ho — 2014-02-18T00:00:00.000Z

Module Summary

Node.js:: events
Component:: component/emitter
Bower:: eventEmitter
Dependencies:: None
LOC:: 302/112/308
File size minified:: 4.2k/1.3k/2.8k

Today I am going to cover the event emitter. What is an event emitter? Well, it's a simple library for attaching events to JavaScript objects.

A Little History

Event emitter first appeared as a core library in Node where it has proven to be a useful pattern. Since the library itself is not specific to Node at all, it has found uses in the browser as well. There are now many implementations of event emitter - partly due to how easy it is to implement its API. Here, I am going to cover the event emitter API that is common to most implementations.

Registering

Let's say there is job object which happens to be an event emitter. To register an event handler for the event done, you'd use the on method like so:

job.on('done', function(){ console.log('The job is done!'); });

Emitting

Now if you are writing the code responsible for actually performing the job, you'll need to notify all the handlers that the job was done at the end. How do you do that?

job.emit('done');

You can also pass arguments to the event, for example the time when the job was done.

var timeDone = new Date(); job.emit('done', timeDone);

The arguments will passed in the same order to all the handlers.

job.on('done', function(timeDone){ console.log('Job was pronounced done at', timeDone); });

Removing Handlers

To remove an active event handler from an event emitter, you'd use the removeListener method

function onDone(timeDone){ console.log('Job was pronounced done at', timeDone); } job.on('done', onDone); ... job.removeListener('done', onDone);

Or you could use the removeAllListeners method to remove all handlers associated with an event:

job.removeAllListeners();

Fire Just Once

The event emitter API also has a convinient shorthand for registering a handler to be called once, and once only, it's called once().

job.once('done', function(){ // This callback will only be called the // first time `done` is fired. });

Make Your Own Event Emitter

So, that's great, but how do you make an event emitter of your own? You inherit EventEmitter.

function Job(){ EventEmitter.call(this); // custom initialization here } Job.prototype = new EventEmitter;

I find that this is the simplest way to inherit EventEmitter without using any utilities. To make it even simpler, the line EventEmitter.call(this) is not strictly necessary since EventEmitter`s constructor doesn't do anything - but people have been told to add this in just in case it ever does in the future.

There are other flavors of inheriting EventEmitter. I will list them here in case you encounter them and get confused. So, in place of Job.prototype = new EventEmitter, you could also:

Use an inheritance function like Node's util.inherits or component/inherit: inherit(Job, EventEmitter)
Use __proto__ but this is is not supported in IE 10 and older (I am partial to this one if I am doing Node-only stuff): Job.prototype.__proto__ = EventEmitter.prototype
Mixin instead of inherit, i.e. copy over the methods, with an extend function like xtend or _.extend or just write your own: extend(Job.prototype, EventEmitter.prototype)
Built-in mixin capability as implemented by component/inherit EventEmitter(Job.prototype)

Regardless of which of the above you use, you can create a job with the new operator

var job = new Job

and it is indeed an event emitter!

Where To Get It?

Node/Browserify - it's built in. var EventEmitter = require('events').EventEmitter
Component - use component/emitter.
Bower or standalone - use Wolfy87/EventEmitter.

Some implementations have more extra features, but they will all support the basic features covered above.

Component Part 2: Making Your Own

Toby Ho — 2014-02-10T00:00:00.000Z

This is our second Component tutorial - a follow up to the first. This article will walk through how to make a component. There is a screencast for this post as well for those who prefer watching over reading.

Why Make A Component?

Why would one want to make a component? There are mainly two reasons:

Code organization - breaking up your application into small logical pieces allows other team members and future you navigate the code base more easily.
Code sharing - if you find that an existing component in your application is applicable in another application you are building, it reduces the build cost of the new application. Furthermore, open sourcing the component opens up the possibility of code reuse with anyone in the world.

With that, let's make a local component - for the purpose of code organization; and then we'll make the component public - to share it with the world.

Setting Up

To set up the project, create a new directory and within it create a component.json file with these contents

{ "name": "My App", "local": [], "paths": ["mycomponents"] }

The paths property tells Component where to search for local components. We've defined mycomponents as the subdirectory where they will be located. Let's create this directory:

mkdir mycomponents

The local property is an explicit list of the local components which will be included in the build when we rebuild the components via component build. It's empty now because we don't have any yet, so let's make one.

Making A Local Component

In the last article, we created a "hello world button" - which when clicked, opens up a dialog box that says "Hello, world!". To refresh your memory, we ended up with this code

<!doctype html> <html> <head> <title>Hello Dialog</title> <link href="build/build.css" rel="stylesheet"> <script src="build/build.js"></script> </head> <body> <h1>Hello Dialog</h1> <button id="button">Open</button> <script> var Dialog = require('dialog'); var dom = require('dom'); dom('#button').on('click', openDialog); function openDialog(){ var dialog = new Dialog('Hello World', 'Welcome human!') .closable() .modal(); dialog.show(); } </script> </body> </html>

The goal is to extract the button into a library so that we can require it, initialize it and attach it to the DOM, like this:

var HelloButton = require('hello_button'); var aButton = HelloButton(); aButton.appendTo(document.body);

We will create a skeleton for the component, use the component create command with the -l flag - for local.

component create mycomponents/hello_button -l

This will prompt you for a name, description and a whether it contains JS, CSS, and HTML - we'll say yes to all three.

$ component create mycomponents/hello_button -l name: hello_button description: A hello world button. does this component have js? ye does this component have css? y does this component have html? y create : mycomponents/hello_button create : mycomponents/hello_button/index.js create : mycomponents/hello_button/template.html create : mycomponents/hello_button/hello_button.css create : mycomponents/hello_button/component.json

Note that some files have been created for you, including a JS file, a CSS file and an HTML file. It also created mycomponents/hello_button/component.json. Open it up and we see this

{ "name": "hello_button", "description": "A hello world button.", "dependencies": {}, "development": {}, "main": "index.js", "scripts": [ "index.js" ], "templates": [ "template.html" ], "styles": [ "hello_button.css" ] }

The scripts, templates and styles properties contain the paths to each file of interest - this is important. A component must explicitly list each Javascript file, template file, and stylesheet file that it needs.

We will put the button's markup in template.html.

<button class="hello_button">Click me!</button>

In index.js we will "require" this template file:

var markup = require('./template.html');

What? You can require an HTML file? Why yes. Yes you can. During the build step, Component converts HTML files listed as templates to Javascript modules which returns a string containing the markup in the file. The idea is that you can use any templating engine you want to - simply an a build step to compile the template, but component has built-in support for the simplest templating engine of all: plain HTML. Also note that we are using a relative path to require the template - this is necessary when requiring another file within the same component.

To create the button, we use the dom component:

var dom = require('dom'); ... var button = dom(markup);

We now implement the component by extracting code from the previous example into index.js, and exporting a function which creates and returns the button - in the CommonJS module system, this is done by assigning a value to module.exports.

var template = require('./template.html'); var Dialog = require('dialog'); var dom = require('dom'); module.exports = function(){ var button = dom(template) .on('click', openDialog); return button; } function openDialog(){ var dialog = new Dialog('Hello World', 'Welcome human!') .closable() .modal(); dialog.show(); }

Create a new test page

<!doctype html> <html> <head> <title>Hello Dialog</title> <link href="build/build.css" rel="stylesheet"> <script src="build/build.js"></script> </head> <body> <h1>Hello Dialog</h1> <script> var HelloButton = require('hello_button'); var aButton = HelloButton(); aButton.appendTo(document.body); </script> </body> </html>

If you rebuild and load the page now, you'll get errors. There are two issue. First we need to specify the parent project's dependency on "hello_button". Also since it no longer directly require component/dom and component/dialog - those can be removed. Add "hello_button" to the main project's "local" property, like so:

{ "name": "hello_component", "paths": ["mycomponents"], "local": ["hello_button"], "dependencies": {} }

Next, establish hello_button's dependency on component/dom and component/dialog: in mycomponents/hello_button/component.json make sure you have:

... "dependencies": { "component/dom": "*", "component/dialog": "*" }, ...

Re-install and then rebuild everything in the parent project directory

component install component build

Reload the page and thing should work just like before.

We have yet to make use of the CSS file in the hello_button component, so let's do that. Let's make this button fancy! In mycomponents/hello_button/styles.css put

button.hello_button{ color: red; font-family: Impact; font-size: 2em; background-color: green; border: 5px solid red; }

Rebuild

component build

Aaaand BAM! Colors.

Auto-Rebuilding

During the course of building this component, you might have had to type component build quite a few times. This gets tedious, doesn't it? Tj recommends using a C program called watch, which simply reruns a supplied command every second. To install it

git clone git@github.com:visionmedia/watch.git cd watch make install

This installs the watch command, and you can now do watch component build from the project directory in a separate terminal, and not have to manually rebuild.

Making It Public

If you had wanted to make a public component in the beginning, you would have used the component create command without the -l flag - which will scaffold out some extra things for you in the project. But since we already have a working local component, we'll just convert it to a public component.

The main things you need for a public component which are not already present in a local component are

"repo" property in component.json - the Github repo path of the component.
"version" property in component.json - a version number becomes important when code becomes public and others depend on it.
"license" property in component.json - the open source license the component is under.
A README.md file.
All dependencies of the component must also be public components.

We'll move the component outside of the parent project:

mv mycomponents/hello_button ../hello_button cd ../hello_button

Edit the component.json to add some fields to it (replace <github user> with your own Github username):

... "repo": "<github user>/hello_button", "version": "0.0.1", "license": "MIT", ...

Next add a README.md (follow this or use your imagination):

Hello Button ============ A hello world button. ## Install component install <github user>/hello_button ## Usage ``` js var HelloButton = require('hello_button'); var button = HelloButton(); button.appendTo(document.body); ```

All dependencies of the button component are already public (component/dialog and component/dom), so we are good there. Now we are ready to publish! Create a new repo on Github and call it hello_button. Then back in the terminal:

git init git add . git commit -m "First commit" git remote add origin git@github.com:<github user>/hello_button.git git push -u origin master

Voila! You've created your first component. But let's make sure it works okay by installing within the parent project. Go back to the parent project, and remove "hello_button" from the "local" property of component.json. If you component build and reload the page, it should fail. Now, install your new public component

component install <github user>/hello_button component build

Reload the page now, and it should work as before!

Adding It To The Registry

If this component were any useful, the next step would be to add it to the Components Registry so that other people can find it. The registry is nothing but a wiki, so to add an entry amounts to clicking "Edit Page", adding a link to your component's project repo, and writing a brief description.

Screencast

Here's this post in screencast form - get your popcorn!

Component Part 2 from Toby Ho on Vimeo.

SuperAgent

Toby Ho — 2014-02-03T00:00:00.000Z

SuperAgent is a light-weight, flexible and expressive Ajax library.

Note: SuperAgent has been loaded on this page! You can open up the dev console to try out the examples. The Github APIs support CORS and so you can make Ajax requests to them directly from here.

The Basics

All of the examples in SuperAgent's documentation alias SuperAgent to request, so I will follow suit. If you are using npm or component

var request = require('superagent');

If you are using it standalone

var request = window.superagent;

Now, to make a simple GET request

var url = 'https://api.github.com/repos/visionmedia/superagent'; request.get(url, function(response){ console.log('Response ok:', response.ok); console.log('Response text:', response.text); });

The response object is what you get back from the callback.

Response Object

The response object contains everything you'd need to know about what came back, including:

status - HTTP status, plus meaningful boolean attributes based on it:
- ok
- clientError
- serverError
- accepted
- noContent
- badRequest
- unauthorized
- notAcceptable
- notFound
- forbidden
- statusType
text - unparsed response body string
body - parsed body, only present if response Content-Type is "application/json" or "application/x-www-form-urlencoded"
header or headers - a map of response headers, note that header names are lowercased
error - an error object if not ok, with details
charset - character set of the response
req - the request object that originated this
xhr - the raw XMLHttpRequest object

Having visited the response object, now let's get into the meat of the library - the request object.

Request Object

Let's step back and look at the request object. A request object is returned by any call to the request function or one of its convinience methods - consisting of "get", "post", and other HTTP verbs.

var req = request.get(url);

If you don't supply a callback function, the request will not be sent out until you called the end() method later

req.end(function(resp){ console.log('Got response', resp.text); });

There are a number of convinience methods too, let's start with query parameters.

Query Parameters

The query() method sets query parameters on the URL of the request.

req.query({id: 8});

or set it in string format

req.query('id=8');

You can call it multiple times and it will combine all of the parameters. This makes easy to set parameters conditionally - which is harder to do in jQuery:

if (search.category){ req.query({category: search.category}); } if (search.searchTerm){ req.query({searchTerm: search.searchTerm}); }

Method Chaining

In the tradition of jQuery, all methods on the request object are chainable (they return back the request object) to allow for a sort of "fluent syntax".

request .get('/post') .query({id: 8}) .end(function(resp){ console.log('Got post', resp.body) });

Sending Parameters

Setting parameters on POST or PUT requests works similarly to query parameters, except you use the send() method to do it:

request .post('/submit') .send({name: 'tj', pet: 'tobi'}) .end(function(resp){ // ... });

By default, SuperAgent encodes the request body in JSON, which means in this case, you would see a request like

POST /submit HTTP/1.1 Host: somesite.com Connection: keep-alive Content-Length: 26 ... Content-Type: application/json {"name":"tj","pet":"tobi"}

You can alternatively use form encoding to mimic submitting an HTML form

request .post('/submit') .type('form') .send({name: 'tj', pet: 'tobi'}) .end(function(resp){ // ... });

then the request would be like

POST /submit HTTP/1.1 Host: somesite.com Connection: keep-alive Content-Length: 16 ... Content-Type: application/x-www-form-urlencoded name=tj&pet=tobi

Setting Headers

Setting a header is done with the set() method

req.set('Content-Type', 'application/json');

but if you are setting the Content-Type, there's shorthand for that

req.type('application/json')

there's also a shorthand for setting the Accept header

req.accept('application/json')

Aborting and Timeouts

You can abort an in-flight request with the abort() method. Or more conveniently, the timeout(ms) method will abort a request after the specified number of milliseconds has passed without getting a response back.

Server-Side Capabilities

SuperAgent also works on the server-side. In addition, it has some server-side specific features such as

Handling redirects
Piping to streams
Multipart requests
Handling attachments
Compression
CORS

Learning More

To learn more about SuperAgent, the best way is to check out the docs.

Introduction to Component

Toby Ho — 2014-01-24T00:00:00.000Z

Hello, and welcome to the first post of Small.js! This post will cover the basics of Component. Component is a frontend Javascript package manager developed by the prolific Tj Holowaychuk. It embodies the philosophy of small modules and is designed to manage assets as well as Javascript. Currently, there exists over 1600 "components". Although there are more popular JS package managers than Component, I chose to cover it first because I love an underdog.

Update: There is a screencast for this post as well for those who prefer watching over reading.

Installing

Before getting started, you'll need to install Node - which is a prerequisite of Component. Installing Node is as simple as clicking on "Download" on the Node website, and then running the installer. To verify you have successfully installed Node, run node from the command line and see that the executable exists.

Next, install Component using npm (sudo is required on some platforms)

npm install component -g

Component is installed! If you type component you should see its usage info

Usage: component [options]

Options:

-h, --help output usage information -V, --version output the version number

Commands:

install [name ...] install one or more components create [dir] create a component skeleton search [query] search with the given query convert <file ...> convert html files to js modules info <name> [prop] output json component information changes <name> output changelog contents wiki open the components list wiki page build build the component ls list installed components

Component has several commands. For this tutorial we'll cover only install, and build.

Create a Project

To create an application which uses components, all that's required is that the root directory of the project contains a valid component.json file. So let's set these up

mkdir hello_component cd hello_component

Next, create a file component.json with the following content

{ "name": "hello_component" }

Congratulations! Now, we can start installing components.

Installing a Component

For demostration purposes, we'll install the dialog component:

component install component/dialog

component/dialog is simply an alias to the Github url: https://github.com/component/dialog. All components are identified by their Github URL. Once you've installed dialog, you'll notice that a components directory was created, and that it contains a component-dialog subdirectory plus a bunch of others

$ ls components component-classes component-indexof component-css component-matches-selector component-delegate component-overlay component-dialog component-query component-dom component-sort component-domify component-type component-emitter component-value component-event

All the other components that were installed were installed because they are either a direct dependency or a transitive dependency of component/dialog.

Also note that your component.json has been doctored - a "dependencies" field has been added containing component/dialog

"dependencies": { "component/dialog": "*" }

keeping the dependencies in component.json allows you to easily get back all the components you need even if you've deleted the components directory, via the command: component install.

Next, to test out the dialog, we need to build it.

Build It

In order to consume any components, you will need build them - which combines all of the components you've currently installed into a .js file and a .css file. Why CSS? Because components can contain CSS - dialog does.

component build

Now you should see a build directory which contains a build.js as well as a build.css.

Test It

The only other thing we need to do now is to create a test page that links these files

<!doctype html> <html> <head> <title>Hello Dialog</title> <link href="build/build.css" rel="stylesheet"> <script src="build/build.js"></script> </head> <body> <h1>Hello Dialog</h1> </body> </html>

Sweet! Open it up in your browser, but nothing happens. Oops, we still need to write some Javascript. First let's bring in the dialog component using the require function

var Dialog = require('dialog');

Then make an openDialog function which calls the dialog component API

function openDialog(){ var dialog = new Dialog('Hello World', 'Welcome human!') .closable() // this adds an `x` button on the top right .modal() // makes it a modal dialog dialog.show() }

To activate this function, put a button on a page, and just for now, use an onclick attribute

Refresh the page, click the button you should see a modal dialog!

Full Source

Do Some DOM

Using the onclick attribute is ok for a quick toy example, but would be unsanitary for a real app, so let's rewrite that in a cleaner way. jQuery time, right? Not so fast! In the land of Component, instead of jQuery, we can use the much more light-weight dom component

component install component/dom

Check your component.json and make sure it contains "component/dom" as a dependency. There's currently a bug in Component that causes a dependency not to get added if it already exists in the components directory. If it's not there, just add it manually - so we should have

"dependencies": { "component/dialog": "*", "component/dom": "*" }

rebuild the components

component build

Now, we can do this

var dom = require('dom'); ... dom('#button').on('click', openDialog);

Same result, but cleaner code! Very jQuery-like, no?

Full Source

Finding Components

How to know what components exist? You can peruse the components wiki page - which in fact is the official registry for components. Alternatively you can also use the component search command, for example

component search dom

to search for all dom-related components.

Homework

What's that? Ohhhh yes! Of course there's homework! Don't look so surprised. What? Yes, you have to do it. If you don't, everything you've learned thus far will be lost.

Your homework is to browse the registry and pick one that looks interesting to you. Then, you are going to install it and incorporate it into your code. Good luck!

Screencast

Component Part 1 from Toby Ho on Vimeo.

Small.JS

Debug

Log The Things

Seeing The Logs

Filtering The Logs

Wildcards

Bye!

Page

Routing

Starting The Router

Programmatic Navigation

Route Handler Chaining

States

Putting It All Together

JSDiff

Browserify

The Gist

The Walkthrough

Installing

Create A Project

Grab Some Modules

Write Some Code

Bundle It

Run It

Shimmed Node.js Environment

Source Maps

Transforms

Automation

RequireBin: Browserify Playground

jQuery And MV* Frameworks

Homework

array

The Constructor

Array Methods

Events

Functional Shorthands

sort()

Differences To Native Array

More

Introduction to npm

Getting npm

Installing Modules

A Closer Look: Nested Dependencies

Making It Your Own

Setting Up A Module

Writing The Module

Go Forth And Publish!

Homework

More Info

Reactive

Basic Example

Event Emitter

Backbone Model

String Interpolation

Declarative Bindings

Event Bindings

each Binding

data-<attr> Binding

data-visible and data-hidden Bindings

data-checked Binding

data-append Binding

More On Bindings

A View Pattern

Event Emitter

Module Summary

A Little History

Registering

Emitting

Removing Handlers

Fire Just Once

Make Your Own Event Emitter

Where To Get It?

Component Part 2: Making Your Own

Why Make A Component?

Setting Up

Making A Local Component

Auto-Rebuilding

Making It Public

Adding It To The Registry

Screencast

`sort()`

`each` Binding

`data-<attr>` Binding

`data-visible` and `data-hidden` Bindings

`data-checked` Binding

`data-append` Binding