Shorthand.js

A lightweight, natural language syntax for describing interactive behaviors for the web.

Shorthand is intended for quickly prototyping behaviors in HTML mockups. The idea is to quickly test out user interactions without investing tons of time in custom JavaScript programming. Shorthand should get you 80% of the way to a functional 'web thang', without the headaches of jQuery spaghetti code.

Shorthand statements all follow a simple basic syntax:

(selector) should (do an action) on (user interaction)

Setup

Setup is easy - just include the base Shorthand.js file anywhere in your page, and then add custom <SCRIPT> blocks for your Shorthand statements

Shorthand requires a jQuery-compatable DOM manipulation to be loaded in the page for it to work. You can include your preferred library (Zepto.js!) and Shorthand will use whatever's available. If none is available, Shorthand will attempt to load the latest version jQuery (from cdnjs) for itself.

<!-- Step 0: Include a specific DOM library, or not. -->
<script src="//cdnjs.cloudflare.com/ajax/libs/zepto/1.0/zepto.min.js" type="text/javascript"></script>

<!-- Step 1: Include Shorthand.js -->
<script src="Shorthand.js" type="text/javascript"></script>

<!-- Step 2: Add <script type='text/Shorthand'> blocks -->
<script type="text/shorthand"> 
	
	Step 3: write Shorthand!
	
	Note that anything that doesn't match the syntax is ignored, so if you want to write out some comments like these you can.

	Here's an example of a valid Shorthand statement that will show an element with id='dialog' when the element with id='button' is clicked:

	#button should show #dialog on click

	And here's a statement that will hide that dialog when the element with class='closebox' inside that dialog.

	#dialog>.closebox should hide #dialog on click

    Or how about leveraging the awesome [animate.css](http://daneden.github.io/animate.css/)?

    #header1 should animate 'bounceInDown' #section1 on click 

    What about using [interact.js](http://interactjs.io/) to support drag and drop and resizing?

    #container1 should be draggable and resizeable

</script>

Selectors

You can use any kind of CSS or jQuery-compatible selectors to specify which elements in your mockup should receive the intended behaviors - ID, class, tag name, whatever you like.

The only limitation on selectors is that they should not contain whitespace. So if you want to use a hierarchical selector like 'section > h1' simply write it as 'section>h1' and Shorthand will apply the behaviors to the correct elements as intended.

Actions

This is the good stuff.

The first word after 'should' in your statement should be one of the valid actions. (There will be more, and it's easy to extend Shorthand's actions to add custom ones, if you're interested.)

Supported Actions:

• toggle (target selector)
• hide (target selector)
• show (target selector)
• toggleclass 'classname' (target selector)
• addclass 'classname' (target selector)
• removeclass 'classname' (target selector)
• goto 'url'
• load 'ajax url' (target selector)
• animate 'animate.css class name' (target selector) -- new!
• be draggable -- new!
• be resizeable -- new!

The word after the action is usually another selector to describe the target for the action. Sometimes it's a valid URL, as in the 'goto' or 'load' actions.

Target Selectors

Target selectors describe the intended target for the action. They can be vanilla CSS selectors like the main selector, or one of the special ones.

• self/itself -- targets the main source selector of the statement.
• next (selector) -- targets the element(s) next to the source element, optionally filtered by a provided selector.
• previous (selector) -- targets the element(s) previous to the source element, again filtered by an optional selector.

Chaining with 'and'

Here's the really good stuff: you can chain multiple actions on a single main selector by simply using the 'and' keyword in your Shorthand statement.

#button should toggle #dialog and toggleclass 'active' self and load 'dialog.html' #dialog>.content on click

See what I did there?

Events

The last part of a Shorthand statement is the event that triggers the Action.

Events follow the 'on eventname' syntax, and eventname can be any valid DOM event, such as 'click', 'mouseover', 'mouseleave', 'touchstart', etc.

Page Load Events

You can also specify that events happen on page load, by simply adding 'on load'. This is great for handling initial setup of complex states, like hiding elements that will later be revealed.

#dialog should hide itself on load

Animation and Interactions

New: ShortHand.js will load additional modules for animation and interaction effects.

Notably, animate.css and interact.js open source libraries are now supported. Simply use 'animate' as the directive such as:

#element should animate 'animationName' #targetElement on (event)

For interact.js, where dragging and resizing are the primary interactions, a new 'should be' syntax is supported:

#dialog1 should be draggable

#dialog2 should be resizable

#dialog3 should be draggable and resizable

Still to come is 'droppable' although that may prove more complex.

License

MIT.

Extending Shorthand

There's a simple way to use JavaScript to add custom actions to Shorthand's default library of actions.

In your own javascript:

window.Shorthand.Actions.enlarge = function(origin, target) {
	target = this.findTarget(target, arguments); // this is required for the magic target selectors to work, like 'self', 'next', and 'previous'
	// After that line, you can do whatever you like here with the target DOM element.
	target.css("font-size", "10em");
}

If you develop useful Actions, please consider sending a pull request, and I'd be happy to include them in the defaults!

Roadmap

I'd like to add a few things, and am open to contributions.

Server-side generation of JavaScript from Shorthand statements.

Ideally Shorthand could be run (via node.js) as part of a build script, and instead of evaluating statements and adding event handlers in-browser, the same statements could be used to generate an application skeleton of some kind.