Building Non-shit APIs with JavaScript

Your JS LibraryDan Webb AKA @danwrong

Tuesday, May 3, 2011


In the beginning...


In the beginning...


$("p.surprise").addClass("ohmy").show("slow");


We all know what happened next...

jQuery

The Rest


Why?


Internals were not important...


...what had John created was a great interface


"All programmers are API designers"Joshua Bloch (http://lcsd05.cs.tamu.edu/slides/keynote.pdf)


http://lcsd05.cs.tamu.edu/slides/keynote.pdf

http://lcsd05.cs.tamu.edu/slides/keynote.pdf

The API is priority #1


❖ Predictability❖ Simplicity❖ Flexibility


Predictability


RTFMTuesday, May 3, 2011

Short attention spanTuesday, May 3, 2011

Think about your audience...


...use conventions people already know


Language conventions and standard library


THIS IS JAVASCRIPT


useCamelCase, yesReally.


Be careful with polyfills


Popular JS libraries


var paper = Raphael(10, 50, 320, 200);

var c = paper.circle(50, 40, 10);

c.attr("fill", "#f00");

c.show();


The problem domain


a.internal { color: #44e534; text-decoration: none;}

$('a.external').css({ color: '#44e534', textDecoration: 'none'});


Example: creating a DOM Builder


node.innerHTML = '<form method="post" action="/action">' + '<p>' + '<label>' + 'Username: <input type="text" name="username">' + '</label>' + '<label>' + 'Password: <input type="password" name="password">' + '</label>' + '</p>' + '</form>';

var form = document.createElement('form');var p = document.createElement('p');form.setAttribute('action', '/login');form.setAttribute('method', 'post');var usernameLabel = document.createElement('label');var usernameText = document.createTextElement('Username: ');var usernameInput = document.createElement('input');usernameInput.setAttribute('type', 'text');usernameInput.setAttribute('name', 'username');form.appendChild(p);p.appendChild(usernameLabel);// ... at this point I decided to give // all this up and become a farmer


var html = { element: function(name, attributes, children) { var node = document.createElement(name); for (var attr in attributes) { node.setAttribute(attr, attributes[attr]); } for (var i=0, len=children.length; i < len; i++) { node.appendChild(children[i]); } return node; }}


var form = html.element( 'form', { action: '/login', method: 'post' } [ html.element('p', {}, [ html.element('label', {}, [ document.createTextElement('Username: '), html.element('input', { type: 'text', name: 'username' }, []), // ... you get the idea ]) ]) ]);


var form = html.form({ action: '/login', method: 'post' }, [ html.p({}, [ html.label({}, [ document.createTextElement('Username: '), html.input({ type: 'text', name: 'username' }, []), // ... you still get the idea, right? ]) ]) ]);


function elementBuilder(name) { return function(attributes, children) { return html.element(name, attributes, children); }}

function generateBuilderFunctions(elements) { for (var i=0, len=elements.length; i < len; i++) { html[elements[i]] = createElementBuilder(elements[i]); }}

generateBuilderFunctions("p|div|span|strong|em|img|table|tr|td|th|thead|tbody|tfoot|pre|code|h1|h2|h3|h4|h5|h6|ul|ol|li|form|input|textarea|legend|fieldset|select|option|blockquote|cite|br|hr|dd|dl|dt|address|a|button|abbr|acronym|script|link|style|bdo|ins|del|object|param|col|colgroup|optgroup|caption|label|dfn|kbd|samp|var".split("|"));


Simplicity



Don’t make me RTFM again...


Sensible defaults




var evt = document.createEvent("MouseEvents");

evt.initMouseEvent("click", true, true, window, 0, 0, 0, 0, 0, false, false, false, false, 0, null);


element.addEventListener('input', function() { // do some front-end magic}, false);


var evt = document.createEvent("MouseEvents");

evt.initMouseEvent("click", true, true, window, 0, 0, 0, 0, 0, false, false, false, false, 0, null);


Use options hashes for optional arguments


evt.initMouseEvent("click", { bubble: false, relatedTarget: thing});


http://blog.rebeccamurphey.com/objects-as-arguments-in-javascript-where-do-y






Function calls should read well


// replace oldNode with newNode - DOM API oldNode.parentNode.replaceChild(newNode, oldNode);

// Dojo dojo.place(newNode, oldNode, "replace");

// jQuery$(oldNode).replaceWith(newNode);


Mask complexity if possible


var con = xd.connect({ src: 'http://danwebb.net/receiver' });

con.bind('ready', function() { rpc(con).call('getData', function(result) { alert(result); });});


http://danwebb.net/receiver'


xd.connect({ src: 'http://danwebb.net/receiver' }, function(con) { rpc(con).call('getData', function(result) { alert(result); });});




var con = xd.connect({ src: 'http://danwebb.net/receiver' });

rpc(con).call('getData', function(result) { alert(result);});




Back to the DOM Builder


var form = html.form({ action: '/login', method: 'post' }, [ html.p({}, [ html.label({}, [ document.createTextElement('Username: '), html.input({ type: 'text', name: 'username' }, []), // ... you still get the idea, right? ]) ]) ]);


var form = html.form({ method: 'post', action: '/login' }, html.p( html.label( 'Username: ', html.input({ type: 'text', name: 'username' }) ), html.label( 'Password: ', html.input({ type: 'password', name: 'pass' }) ), html.input({ type: 'submit', value: 'Login'}) ));


function elementBuilder(name) { return function() { var attributes = {}, children = [], args = Array.prototype.slice.call(arguments);

// if the first arg is not a element or a string then its an attributes hash if (!args[0].nodeType && typeof args[0] != 'string') { attributes = args.unshift(); } // children can be an array or remaining args if (Array.isArray(args[0])) { args = args[0]; }

// add rest of args as children converting any strings to text nodes for (var i=0, len=args.length; i < len; i++) { if (typeof args[i] == 'string') { children.push(document.createTextNode(args[i])); } else { children.push(args[i]); } }

return html.element(name, attributes, children); }}


Flexibility





Remember: you can't please everyone


Don’t try to second guess every use case


Options hashes != flexibility


28 options!Tuesday, May 3, 2011

Add hackability


public, internal, protected


var lib = (function() { var private = function() { // you can't mess with me };

return { _internal: function() { // you probably shouldn't mess with me }, public: function() { // I'm part of the API - call me sometime } }}());


...using functions


// https://github.com/ender-js/Ender

$._select = function(selector, root) { return Sizzle(selector, root);}

$._select = function (selector, root) { return (root || document).querySelectorAll(selector);});


https://github.com/ender-js/Ender

https://github.com/ender-js/Ender

..inheritance


// github.com/danwrong/loadrunner

function Mustache(path) { this.path = path;}Mustache.prototype = new loadrunner.Dependency;Mustache.prototype.start = function() { var me = this; $.get(this.path, function(result) { var template = Mustache.parse(result); me.complete(template); });}

using(new Mustache('thing.mustache'), function(template) { template.evaluate({ a: 'yep', b: 'nope' });});


..duck typing


Meanwhile, back in DOM Builder land...


function elementBuilder(name) { return function() { // code collapsed for clarity

// add rest of args as children // converting any strings to text nodes for (var i=0, len=args.length; i < len; i++) { if (typeof args[i] == 'string') { node = document.createTextNode(args[i]); } else { if (typeof args[i].toDOM == 'function') { node = args[i].toDOM(); } else { node = args[i]; } }

children.push(node); }

return html.element(name, attributes, children); }}


function Tweet(text, author, timestamp) { this.text = text; this.author = author; this.timestamp = timestamp;}Tweet.prototype.toDOM = function() { return html.p( { 'class': 'tweet' }, html.strong(this.author.name), this.text, html.span({ 'class': 'time' }, this.timestamp) );}

var timeline = // an array of Tweet objects

document.appendChild(html.div({ id: 'timeline' }, timeline));


Create a framework for solving your problem...


...then build your library on top of that


You got yourself a plugin system


Build tools to solve the problem


❖ Design up front❖ Make use of conventions❖ Don’t make me think❖ Build in hackability


Questions?@danwrong


@jointheflocktwitter.com/[email protected]


mailto:[email protected]

mailto:[email protected]

Eye of the BeholderTuesday, May 3, 2011

ChainingTuesday, May 3, 2011

Technology

Building Non-shit APIs with JavaScript