lb.core.plugins.utils

Define methods in the ‘utils’ property of given sandbox.

Parameters

Check whether given value is null or undefined

The intent of this method is to replace unsafe tests relying on type coercion for optional arguments or object properties:

function onEvent(name,data){
  if (!name || !data || !data.value){
    // unsafe due to type coercion: all falsy values '', false, 0
    // are discarded, not just null and undefined
    return;
  }
  // ...
}

with a safer test without type coercion:

function onEvent(event,options){
  if ( no(name) || no(data) || no(data.value) ){
    // safe check: only null/undefined values are rejected;
    return;
  }
  // ...
}

Parameter

Returns

boolean, false when the value is null or undefined, true otherwise

Get a default value when given value is null or undefined

The intent of this method is to replace unsafe initialization of optional parameters to a default value relying on type coercion:

function on(event,options){
  options = options || {}; // type coercion
  var isUser = options.isUser || false; // type coercion
  // ...
}

with a safer initialization without type coercion:

function on(event,options){
  options = or(options, {}); // no type coercion
  var isUser = or(options.isUser, false); // no type coercion
  // ...
}

Parameters

Returns

any, the default value when the value is null or undefined, the value itself otherwise.

Check whether an object property is present and not null nor undefined.

A chain of nested properties may be checked by providing more than two arguments.

The intent of this method is to replace unsafe tests relying on type coercion for optional arguments or object properties:

function on(event,options){
  options = options || {}; // type coercion
  if (!event || !event.data || !event.data.value){
    // unsafe due to type coercion: all falsy values '', false, 0
    // are discarded, not just null and undefined
    return;
  }
  // ...
}

with a safer test without type coercion:

function on(event,options){
  options = or(options, {}); // no type coercion
  if ( !has(event,'data','value') ){
    // safe check: only null/undefined values are rejected;
    return;
  }
  // ...
}

Parameters

Returns

• false if no argument is provided or if the object is null or undefined, whatever the number of arguments
• true if the full chain of nested properties is found in the object and the corresponding value is neither null nor undefined
• false otherwise

Check the type of a value, possibly nested in sub-properties.

The method may be called with a single argument to check that the value is neither null nor undefined.

If more than two arguments are provided, the value is considered to be nested within a chain of properties starting with the first argument:

is(object,'parent','child','leaf','boolean')

will check whether the property object.parent.child.leaf exists and is a boolean.

The intent of this method is to replace unsafe guard conditions that rely on type coercion:

if (object && object.parent && object.parent.child) {
  // Issue: all falsy values are treated like null and undefined:
  // '', 0, false...
}

with a safer check in a single call:

if ( is(object,'parent','child','number') ) {
  // only null and undefined values are rejected
  // and the type expected (here 'number') is explicit
}

Parameters

Returns

• false, if no argument is provided
• false, if a single argument is provided which is null or undefined
• true, if a single argument is provided, which is not null/undefined
• if the type argument is a non-empty string, it is compared with the internal class of the value, put in lower case
• if the type argument is a function, the instanceof operator is used to check if the value is considered an instance of the function
• otherwise, the value is compared with the provided type using the strict equality operator ===

Type Reference

Notes

This method retrieves the internal class of the provided value using

Object.prototype.toString.call(value).slice(8, -1)

The class is then converted to lower case.

See “The Class of an Object” section in the JavaScript Garden for more details on the internal class: http://bonsaiden.github.com/JavaScript-Garden/#types.typeof

The internal class is only guaranteed to be the same in all browsers for Core JavaScript classes defined in ECMAScript.  It differs for classes part of the Browser Object Model (BOM) and Document Object Model (DOM): window, document, DOM nodes:

Get current timestamp, in milliseconds.

Returns

number, the number of milliseconds ellapsed since the epoch (January 1st, 1970 at 00:00:00.000 UTC).

Plan the delayed execution of a callback function.

Parameters

Returns

number, the timeout identifier to be passed to utils.clearTimeout() to cancel the planned execution.

Cancels the planned execution of a callback function.

Parameter

Remove leading and trailing whitespace from a string.

Parameter

Returns

string, a copy of the string with no whitespace at start and end

Log a message.

Log messages will be printed in the browser console, when available, and if the log output has been activated, which happens when Debug=true is included anywhere in the URL.

Parameter

Open a confirmation (OK/Cancel) dialog.

Parameter

Returns

boolean, true if user clicked OK, false is she clicked Cancel button.