Minified.js Beta 3: Features and Changes

Beta 3's main feature is the new Util module which provides you with collection and string helpers, formatting and parsing, date arithmetic and a template system. The Web module has also been extended with some new features. The new main distribution of Minified is now the complete version containing both modules, as well as some additional features that require both modules to be present.

Here's an overview over Minified's distributions:

FilenameContainsIE6-8 Support?Old nameTarget Size
minified.jsEverythingno-<8kB
minified-legacyie.jsEverythingyes-
minified-web.jsWeb Modulenominified-web.noie.js<4kB
minified-legacyie-web.jsWeb Moduleyesminified-web.js-
minified-util.jsUtil Moduleyes-

Backward-incompatible Changes

  • on() will now ignore the handler's callback by default. Prefix the event name with '?' to use the return value.
  • on()'s argument order has changed. This only affects you if you have been using selectors, which are now called 'bubble selectors'. Please read the API documentation to understand the difference between bubble selectors and regular selectors.
  • on() does no longer support setting 'this' directly. Use bind() or write your own callback if you need to set 'this'.
  • animate() does not support the state object anymore. You can obtain the stop() function from the returned promise.
  • Support for the relative syntax ("+=10px") has been removed from animate(). Instead you can use a callback to calculate the target value.
  • EE() and clone() do not create element factories anymore, but just the elements wrapped in a list. In most code that should not make any difference, since add() and its sibling functions will now automatically clone elements when added to lists longer than one. But if you called the element factories yourself, you need to change your code.
  • EE()'s onCreate parameter has been removed. Since it returns the element itself now, you can call on() directly on its return value.

New: Util module (minified-util.js)

Util provides general utility functions for JavaScript that are also useful outside of a browser. All Util functions are in the default namespace '_', so you can easily see which functions are located in Util. There is only one Minified list implementation though, and you can use methods from both modules interchangeably. For example, you can modify a list using Util's map() and then animate the result using animate().
Util has far too many functions to show them all, but here are the basics:

Example: Importing all Util and Web symbols
var MINI = require('minified');                               // Util is also in 'minified'!
var _ = MINI._;                                               // _ is Util's namespace
var $ = MINI.$, $$ = MINI.$$, EE = MINI.EE, HTML = MINI.HTML; // Web module. HTML is new!
Example: Creating a list with _()
var list1 = _('a', 'b', 'c', 'd'); 
var list2 = $(['a', 'b', 'c', 'd']);       // $() and _() create the same list type!
var list3 = _(['a', 'b'], 'c', ['d']);     // same as list1 and 2: first list level is flattened to allow merging
console.log(_.equals(list1, list2) && _.equals(list2, list3));
Example: Formatting and numbers dates
var n1 = _.formatValue('#.00', 2.5);                   // number format: returns '2.50'
var n2 = _.formatValue('<10:#.99|<100:#.9|#', 7.356);  // choice format: returns '7.36'
var n3 = _.formatValue('<10:#.99|<100:#.9|#', 91.42);  // choice format: returns '91.4'
var n4 = _.formatValue('<10:#.99|<100:#.9|#', 1012);   // choice format: returns '1012'

var c1 = _.formatValue('1:one item|2:two items|>2:# items', 2); // choice format: returns 'two items'
var c2 = _.formatValue('1:one item|2:two items|>2:# items', 5); // choice format: returns '5 items'
var c3 = _.formatValue('true:positive|negative', true);   // choice format: returns 'positive'
var c4 = _.formatValue('true:positive|negative', false);  // choice format: returns 'negative'

var d1  = _.formatValue('M/d', _.now());              // e.g. '8/25'
var d2  = _.formatValue('yyyy-MM-dd', _.now());       // e.g. '2013-08-25'
var d3  = _.formatValue('dd.MM.yyyy HH:mm:ss', _.now());          // e.g. '25.08.2013 23:07:38'
var d4  = _.formatValue('yyyy-MM-ddTHH:mm:ss.SS z', _.now());     // e.g. '2013-08-25T23:07:38.472 +0700'
var d5  = _.formatValue('d.N[Januar,Februar,Maerz,April,Mai,Juni,Juli,'+   // German translation: '9. Juli'
				 'August,September,Oktober,November,Dezember]', _.now()); 
Example: Date Arithmetic
var inputDate1 = _.parseDate('yyyy-MM-dd', $$('#myDateInput1).value);
var inputDate2 = _.parseDate('yyyy-MM-dd', $$('#myDateInput2).value);
var oneDayLater = _.dateAdd(inputDate1, 'day', 1);
var twoMonthsEarlier = _.dateAdd(inputDate1, 'month', -2);
var daysPasses = _.dateDiff(inputDate1, inputDate2, 'day');
var secondsPasses = _.dateDiff(inputDate1, inputDate2, 'second');
Example: Using Templates
var template1 = _.template('{{a}} plus {{b}} is {{a+b}}');
var r1 = template1({a: 2, b: 9});                              // returns '2 plus 9 is 11'

var r2 = _.format('{{a}} plus {{b}} is {{a+b}}'{a: 2, b: 9});  // templated compiled (and cached) on-the-fly

var r3 = _.format('{{a :: #.9}} * {{b :: #.9}} = {{a*b :: #.99}}'{a: 2.27, b: 3});  // with format: '2.3 * 3.0 = 6.81'

var template4 = _.template('Hello {{if visits==0}}New{{else if visits<10}}Returning{{else}}Regular{{/if}} Customer.');
var r4 = template4({visits: 2});   //returns 'Hello Returning Customer.'

var template5 = _.template('{{each n: names}}{{n.firstName}} {{n.lastName}}
{{/each}}');
var r5 = template5({names: [{firstName: 'Joe', lastName: 'Jones'}, 
                            {firstName: 'Marc', lastName: 'Meyer'}]});

New: HTML templates with ht()

ht() executes a HTML template and replaces the list elements' content with the created HTML.
Please note that ht() is only available in the full distribution.

$('#name').ht('<b>{{first}} {{last}}</b>', {first: 'Tim', last: 'Taylor'});

New: Creating HTML Elements with HTML()

HTML() creates a list of elements from the given HTML template.
Please note that HTML() is only available in the full distribution.

$('ul.users').add(HTML('<li>{{first}} {{last}}</li>', {first: 'Tim', last: 'Taylor'}));

New: Getting notified of text field changes with onChange()

onChange() registers an event handler for input fields that will be notified in real-time when the field content changes.

$('#myField').onOver(function(newValue, index, ev) { 
    $('#target').fill(newValue); 
});

New: Getting page coordinates with offset()

offset() returns the page coordinates of an element.

var pos = $('#myElem').offset();
console.log('x=', pos.x, ' y=', pos.y);

New: Virtual properties $$scrollX and $$scrollY for get()/set()/animate()

The virtual properties $$scrollX and $$scrollY allow you to scroll the main window.

$(window).animate({$$scrollY: $('#myElem').offset().y}, 1000);  // smooth-scroll to element

New: Interpolate styles with dial()

dial() returns a function that can set an interpolated state for the list's elements. It is somewhat similar to toggle() and is helpful for complex or interactive animation. animate() uses dial() internally.

var myDimmer = $('#myElem').dial({$backgroundColor: '#000'}, {$backgroundColor: '#fff'});
myDimmer(0); // make element black (#000)
myDimmer(1); // make element white (#fff)
myDimmer(0.25);  // light gray (#444)
myDimmer(0.5);   // gray (#888)
myDimmer(0.75);  // dark gray (#ccc)

New: Destination callback for animate()

animate() got support for functions as destination. The function will be called once for each animated element to determine its actual destination. This replaces the old relative syntax (e.g. '+=10px').

$('.animated').animate({$top: function(oldValue, index, obj) { return (parseInt(oldValue)+10) + 'px'; }});

New: Creating Promises with _.promise()

You can now use promise() to create your own promises. To fulfill or pass them, just call the promise as a function. The constructor also allows you to unite promises, so it creates a promise that is fulfilled when either all promises succeeded or one failed.
function animateAndRequest() {
	var prom1 = $('.animated').animate({$backgroundColor: '#fff'}, 1000);
	var prom2 = $.request('get', '/some/data');
	return _.promise(prom1, prom2); // promise fulfilled when both animation and HTTP request end
}

function myTimeout(ms) {
	var p = _.promise();
	setTimeout(function() { p(true, ['Timeout over']); }, ms);
	return p;
}

Change: Sub-selectors and different invocation of on()

on()'s syntax for selectors have changed. You can now specify an selector to register directly for children of the list. This is mostly useful if you create new elements using HTML() and want to register events in the same step. The selector for event bubbling moved to the last argument. Support for 'this' has been removed to simplify the invocation. .

$('#myForm').add(HTML("<li><button>click me</button></li>").on('button', 'click', myClickHandler));

Change: Optional cancelling of events with on()

on() supports a new event name prefix '?' which is required if you want to cancel an event depending on the handler's return value. If you use an event name without prefix, the return value of the handler will be ignored now. .

$('#myForm').on('?submit', function() { return window.confirm('Really submit?'); });

Change: Replacing 'element factory' concept with smarter add()

Before beta 3, EE() and clone() returned an 'element factory' (a function creating the actual elements). I abandoned this concept as it was too complex and hard to understand. Instead both function will now return regular lists containing the new elements.
The new add() (and all the methods based on it, such as fill() and replace()) will clone HTML nodes if they are added more than once to a document.

Change: New prefix '?' in on()

Before beta 3, the return value of event handlers was evaluated by default. Event processing would be aborted unless the handler returned true.
Now the return value will be ignored by default. A new event name prefix '?' allows you to specify that the return value must be used.

Build System: Switched to grunt

The old ant-based build system has been replaced with a shiny new one based on grunt. All tests have been converted to Mocha and can be executed by grunt.

To build Minified, you need to install Node.js and Grunt. Then enter the Minified directory and install the dependencies:

 npm install

To build the whole project including the site, use:

 grunt all

If you only want to compile the code, use:

 grunt code

Distribution: Support for Bower

Minified is now available as a Bower package. The package name is 'Minified'.

Download

You can download beta 3 on the download page.