5.16.2

Utilities

Fine Uploader contains a number of utility functions and shims to keep it dependency free and lightweight. These functions are found in the same namespace as Fine Uploader, qq.

qQuery

The qQuery object is much like a poor man's jQuery. If you cannot or do not want to import a 3rd-party library such as jQuery or Zepto to do cross-browser DOM manipulation, then qQuery will be your friend.

qq (element)

Selects an HTMLElement and returns a qq 'wrapped object.'

Parameters:
HTMLElement
element

A HTML element.


Returns:
qq instance
A wrapped DOM object with a variety of cross-browser shims as methods.

qq functions similar to the jQuery function in terms of the operations it can perform. For now, though, qq only accepts HTMLElements as input. To be able to use the qq methods, first one must wrap some HTMLElement in the qq function as such:

For example, if you wanted to hide an element with the id of "myDiv":

var myDiv, qqMyDiv;
myDiv = document.getElementById("myDiv");
qqMyDiv = qq(myDiv);

// Now we can call other qq methods:
qqMyDiv.hide();
var children = qqMyDiv.children();

// etc ...

Once you've wrapped an element, you have access to a wealth of cross-browser shims that will let you manipulate the DOM and CSS as you please. Just make sure to wrap any elements before calling these methods on them.

DOM Selection and Traversal

children (element)

Returns an array of all immediate children of this element.

Parameters:
HTMLElement
element

An HTMLElement or an already wrapped qq object.


Returns:
Array
An array of HTMLElements who are children of the `element` parameter.

contains (element)

Returns true if the element contains the passed element.

Parameters:
HTMLElement
element

An HTMLElement or an already wrapped qq object.


Returns:
Boolean
The result of the contains test.

hasAttribute (attributeName)

Returns true if the attribute exists on the element and the value of the attribute is not 'false' case-insensitive.

Parameters:
String
attributeName

An attribute to test for.


Returns:
Boolean
The result of the `hasAttribute` test.

DOM Manipulation

clearText ()

Clears all text for this element


insertBefore (element)

Inserts the element directly before the passed element in the DOM.

Parameters:
HTMLElement
element

remove ()

Removes the element from the DOM.


setText (text)

Sets the inner text for this element.

Parameters:
String
text

The text to set.


CSS Operations

addClass (className)

Add a class to this element.

Parameters:
String
className

The name of the class to add to the element.


css (styles)

Add CSS style(s) to this element.

Parameters:
Object
styles

An object with styles to apply to this element.


Returns:
Object
Returns the current context to allow method chaining.

getByClass (className)

Returns an array of all descendants of this element that contain a specific class name.

Parameters:
String
className

The name of the class to look for in each element.


Returns:
Array
An array of `HTMLElements`

hasClass (className)

Returns true if the element has the class name

Parameters:
String
className

The name of the class to look for in each element.


Returns:
Boolean
Result of the `hasClass` test

hide ()

Hide this element.

Returns:
Object
Returns the current context to allow method chaining.

removeClass (className)

Remove the provided class from the element

Parameters:
String
className

The name of the class to look for in each element.


Returns:
Object
Returns the current context to allow method chaining.

Event Attaching and Detaching

attach (event, handler)

Attach an event handler to this element for a specific DOM event.

Parameters:
String
event

A valid DOM Event


Function
handler

A function that will be invoked whenever the respective event occurs


Returns:
Function
Call this function to detach the event.

detach (event, originalHandler)

Detach an already attached event handler from this element for a specific DOM event.

Parameters:
String
event

A valid DOM Event


Function
originalHandler

A function that will be detached from this event.


Returns:
Object
Returns the current context to allow method chaining.

Utility Functions

bind (oldFunc, context)

Shim for Function.prototype.bind. Creates a new function that, when called, has its this keyword set to the provided context. Pass comma-separated values after the `context parameter for all arguments to be passed into the new function (when invoked). you can still pass in additional arguments during invocation.

Parameters:
Function
oldFunc

The function that will be bound to.


Object
context

The context the function will assume.


Returns:
Function
A new function, same as the old one, but bound to the passed in`context`.

each (iterable, callback)

Iterates through a collection, passing the key and value into the provided callback. return false; to stop iteration.

Parameters:
Array or Object
iterable

The array or object containing items/properties to loop through.


Function
callback

A function that will be called for each item returned by looping through the iterable. This function takes an index and an item.


extend (firstObj, secondObj[, extendNested])

Shallowly copies the parameters of secondobj to firstobj. if extendnested is true then a deep-copy is performed.

Parameters:
Object
firstObj

The object to copy parameters to.


Object
secondObj

The object to copy parameters from.


Boolean
extendNested

If true then a deep-copy is performed, else a shallow copy.


Returns:
Object
The new object created by the extension.

format (message)

Returns a string, swapping argument values with the associated occurrence of {} in the passed string.

Parameters:
String
message

Returns:
String
The formatted string

getExtension (filename)

Return the extension for the filename, if any.

Parameters:
String
filename

The file's name to rip the extension off of.


Returns:
String
The new filename

getUniqueId

Returns a version4 uuid

Returns:
String
A version 4 unique identifier

indexOf (array, item[, startingIndex])

Returns the index of item in the Array starting the search from startingindex.

Parameters:
Array
array

Object
item

Integer
startingIndex

Returns:
Integer
The index of `item` in the array.

isFunction (func)

true if the parameter is a function.

Parameters:
Object
func

The Object to test.


Returns:
Boolean
The result of the `isfunction` test.

isObject (obj)

true if the parameter is a 'simple' object.

Parameters:
Object
obj

The 'thing' to test.


Returns:
Boolean
Result of the `isobject` test

isString (str)

true if the parameter is a string.

Parameters:
Object
str

The Object to test


Returns:
Boolean
The result of the `isstring` test.

log (logMessage[, logLevel])

Log a message to the console. no-op if console logging is not supported. shim for console.log.

Parameters:
String
logmessage

The message to log.


String
logLevel

The logging level, such as 'warn' and 'info'. If null, then 'info' is assumed.


preventDefault (event)

Prevent the browser's default action on an event.

Parameters:
String
event

The name of the default event to prevent.


toElement (str)

Creates and returns a new <div> element

Parameters:
String
str

Valid HTML that can be parsed by a browser.


Returns:
HTMLElement
An newly created `HTMLElement` from the input.

trimstr (str)

Removes whitespace from the ends of a string. Shim for String.prototype.trim.

Parameters:
String
str

The string to remove whitespace from.


Returns:
String
The new string sans whitespace.