Noosev1.0.0 Documentation

Installation

Download or install from git or npm.

npm -i noose
git clone https://github.com/tokafew420/noose.git

or

Use a CDN (jsDelivr).

<script src="https://cdn.jsdelivr.net/npm/noose/dist/noose.min.js"></script>

Distribution

These files are available in the distribution directory.

• noose.js - ES6 source file
• noose.min.js - Minified ES6 source file
• noose.es5.js - Transpiled ES5 source file
• noose.es5.min.js - Minified and transpiled ES5 source file

Basic Usage

Initialize Noose with default options by passing in a valid css selector or a reference to a HTMLElement.

var noose = new Noose('.my-container');

See example

classes

object - A hash of classes to apply.

• noose string - Class is added to the noose. Default is 'noose'.
• selected string - Class is applied to selected elements. Default is 'selected'.

See example

Note: If the default options.style options are applied, then use !important in your CSS rules to override them.

compute

boolean - Whether computing of selected elements is enabled. Default is true.

This is different from options.select = false as it will still allow for manual calls to compute().

See example

container

string | Element - Specify the containing parent element for the noose. Default is 'body'.

This option is an alternative way initialize noose.

var noose = new Noose({
    container: '.my-container'
});

ctrl

boolean - Whether support for multiselect using the ctrl key is enabled. Default is true.

detach

boolean - Whether the noose element is detached from the container after noose-ing ends. Setting this to false has the affect of keeping the noose area visible even after selection.

Default is true.

See example

enabled

boolean - Whether the noose action is enabled. Default is true.

mode

string - Specify the selection criteria. There are 2 possible values.

• fit - The candidate element must fit entirely inside the noose region.
• touch - Any part of the candidate element is touching the noose region.

Default is 'touch'.

See example

move

function( event , coordinates , selected ) - Called when noose is moved.

• The context is the noose instance.
• event - The event that prompted recalculation of the noose (ie: mousemove, touchmove, or scroll).
• coordinates - The object containing the coordinates used in the noose calculations.
• selected - The selected elements.

See example

scroll

number - When auto scrolling, this is the amount of pixels to scroll. Set to 0 to disable auto scrolling. Default is 10.

See example

scrollEdge

number - The offset amount from the container's edge where auto scrolling will be initiated. Set to 0 to disable auto scrolling. Default is 10.

See example

scrollbar

number - The size (in pixel) of the scrollbar. When scrollbars are present in the container, clicking within this region will not start the noose action. This is to allow interaction with the scrollbars. Default is 17.

See example

select

string - Specify the selector for selecting child elements. Default is '*'.

It is recommended to narrow the scope of what is selectable for better performance.

See example

Setting this value to false will bypass the selection process. Do this if you don't care for selecting elements but want the noose to be rendered.

This is different from options.compute = false as it will not attempt to run the selection process because a selector is undefined.

See example

shift

boolean - Whether support for extending the noose region using the shift key is enabled. Default is true.

See Shift Support for more information.

start

function( event , coordinates ) - Called on start of the noose action. Return false to prevent noosing.

• The context is the noose instance.
• event - The event that initiated the noose action (ie: mousedown or touchstart).
• coordinates - The object containing the coordinates used in the noose calculations.

See example

stop

function( event , coordinates , selected ) - Called when noose action is complete.

• The context is the noose instance.
• event - The event ending the noose action (ie: mouseup or touchend).
• coordinates - The object containing the coordinates used in the noose calculations.
• selected - The selected elements.

See example

style

object - A hash containing the style for the noose.

• border - The border style. Default is '1px dotted #000'
• zIndex - The z-index. Default is 1000

See example

throttle

number - The delay (in ms) between computations of the selected elements. Setting this value to 0 will disable throttling. Default is 200.

Adjust for performace by increasing or decreasing this value depending on the number of selectable elements you have.

See example

compute()

Computes the selected elements given the current coordinates. When compute option is disabled, call this manually to get selected elements.

Returns - Noose - The current instance of Noose. (for chaining).

See example

deregister(container)

Un-registers a container from the Noose instance. Interacting with the container Element will no longer activate nooosing.

• container HTMLElement - An existing container that is registered on the 'noose' instance.

Returns - Noose - The current instance of Noose. (for chaining).

See example

destroy()

Destroy and cleanup the current instance.

Returns - Noose - The current instance of Noose. (for chaining).

register(container)

Registers a container Element to the Noose instance.

• container HTMLElement - An new container Elmenet to be registered on the 'noose' instance.

Returns - Noose - The current instance of Noose. (for chaining).

See example

containers

NodeList - Collection of elements (containers) which were queried from the container option and are initialized for noosing.

coors

Object - Holds the calculated coordinates of the current noosing operation.

• container - Object - Coordinates for the current container.

  • h - number - The height of the container
  • w - number - The width of the container.
  • maxScrollX - number - The max amount of scrolling available on the x axis.
  • maxScrollY - number - The max amount of scrolling available on the y axis.
  • scrollX - boolean - Whether the container can scroll left/right.
  • scrollY - boolean - Whether the container can scroll up/down.
  • x - number - The x (left) position of the container relative to the page.
  • y - number - The y (top) position of the container relative to the page.
• noose - Object - Coordinates for the current noose.

  • bottom - Object - Contains the x,y (bottom/right) coordinates relative to the current container.
  • start - Object - Contains the original starting x,y coordinates relative to the current container.
  • top - Object - Contains the x,y (top/left) coordinates relative to the current container.
• pointer - Object - Coordinates for the mouse/touch events.

  • end - Object - Contains the most recent x,y coordinates relative to the page.
  • start - Object - Contains the original starting x,y coordinates relative to the page.

lastSelection

Array[HTMLElement] - When performing a multiselect action using the ctrl key, this property will contain the previously selected elements from the previous noose action.

noose

HTMLDivElement - The rendered noose element.

opts

Object - A reference to the initialized options object.

selected

Array[HTMLElement] - An array of all the selected element from the noosing operation.

version

string - The version number.

Browser Selection

To prevent the default browser behavior of selecting the text when the mouse is dragged, apply this CSS to the containers. (This is used in all examples.)

.no-select {
    -webkit-touch-callout: none;
    -webkit-user-select: none;
    -khtml-user-select: none;
    -moz-user-select: none;
    -ms-user-select: none;
    user-select: none;
}

Positioning

All containers should be positioned. This means anything but the default position, which is static. This allows the noose to be rendered relative to the container. If the container is not positioned, then the noose will not be render correctly and also will not correctly calculate the selected elements.

Shift Support

The previous noose region can be extended by holding the shift key during the start of the noose action. The noose region will be started using the opposing quadrant of the previous noose region.

Hover over the quadrants to hightlight its opposing quadrant where the noose will be extended from. Note: The blue dashed borders are inclusive and the red dashed borders are exclusive.

Touch Scrolling

On touch enabled devices, scrolling will be prevent when Noose is enabled and the touch event is within the container. For pages with long content, it is recommended that Noose is only enabled in a smaller region that will not take up the entire viewport. This will allow the user to scroll the page when touching outside the Noose enabled container. Another approach can be to allow the user to enable/disable the noose action.