Selection Utilities (part of jsutilslib)

Selection Utilities is a set of javascript components that enable to have components in which draw selections, make html elements grabbable to be moved around the page, and also make div resizable.

Selection Utilities can be used by themselves in your web applications, but they are also part of jsutilslib, which is a library that consists of a set of curated components, utility functions, clases, etc. that are flexible enough to be re-used in different javascript applications.

Some parts of the library are intended to be used in conjunction with jQuery, and so it is advisable to include jQuery in your project prior to including jsutilslib.

Selection Utilities

The library consists of the next utilities:

• selectable: makes one div to be selectable (i.e. enables to draw a selection)
• grabbable: makes an object to be grabbable (i.e. the object can be grabbed using the mouse and the moved around)
• sizable: makes a div to be sizable (i.e. if sizers are present, the size is changed moving these sizers; tipically top, bottom, left, right...)

Using

There are a set of javascript files that contain a part of the library, each one (in folder js). These files can be used individually or combined into a single one, by concatenating them (or by using uglify-js).

There are also a set of css files that contain some styles to be used with the library. These files can also be included individually in your project, or combined into a single file by concatenating them (or by using clean-css).

A Makefile is provided to create the single all-in-one js and css files for the library.

# npm install -g uglify-js clean-css-cli
...
# git clone https://github.com/jsutilslib/common
# cd common
# make
uglifyjs js/*.js  -b | cat notice - > common.js
uglifyjs js/*.js  | cat notice.min - > common.min.js
# git clone https://github.com/jsutilslib/selection
# cd selection
# make
uglifyjs js/*.js  -b | cat notice - > selection.js
uglifyjs js/*.js  | cat notice.min - > selection.min.js
cleancss css/*.css --format beautify | cat notice - > selection.css
cleancss css/*.css | cat notice.min - > selection.min.css

Now you can use files common.min.js, selection.min.js and selection.min.css in your project (jQuery is a prerrequisite):

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
<script src="common.min.js"></script>
<script src="selection.min.js"></script>
<link rel="stylesheet" href="selection.min.css">

Library jsutilslib/common is a prerrequisite for this library.

From a CDN

It is possible to use selection directly from a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/jsutilslib/common@1.0.0-beta/common.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/jsutilslib/selection@1.0.0-beta/selection.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/jsutilslib/selection@1.0.0-beta/selection.min.css">

Selectable

In order to make an object to be selectable, it is needed a code like the next one:

<div class="w-100 h-50 selectable"></div>
<script>
jsutilslib.selectable($('.selectable')
</script>

The code will allow multiple selections to be created. If you only want one selection to exist, the alternative is to provide a callback to be executed upon start selecting:

<div class="w-100 h-50 selectable"></div>
<script>
jsutilslib.selectable($('.selectable'), {
    callbackstart: function () {
        $(this).find('.selection').remove();
    }
})
<script>

The full list of options that jsutilslib.selectable accepts are the next:

• creatediv: is the function used to create the div that will act as the selection. Default: () => $('<div id="selection" class="selection"></div>')
• callbackstart: is a function that will be called prior to starting the selection. If returns false, the selection will not be created. Default: (x0, y0) => true
• callbackmove: is a function that will be called when the selection has changed its size (while is being drawn). Default: (dx, dy) => null
• callbackend: is a function that will be called when the selection has been finally created. Default: (x, y, w, h) => null
• autoappend: if true, the selection will be automatically appended to the selectable element. Default: true
• minw: the minimal width valid for the selection (if the user drawed less, the selection will be discarded). Default: 20
• minh: the minimal height valid for the selection (if the user drawed less, the selection will be discarded). Default: 20
• defaultsize: the default size for the selection, if the selection drawn by the user is to be discarded. Default: {w: 100, h: 100}

Events

The selectable element will trigger the next events:

• selectable-start:
• selectable-move:
• selectable-end:

Grabbable

<div class="w-100 h-50 selectable"><div class="selection" style="top:10;left:10;width:100;height:100;"></div></div>
<script>
jsutilslib.grabbable($('.selection'));
</script>

The full list of options that jsutilslib.grabbable accepts are the next:

• classdragging: If set, this is the class which will be set for the object while being moved. Default: grabbing
• callbackstart: is a function that will be called when the object has been grabbed to be moved. Default: () => {}
• callbackmove: is a function that will be called when the object has changed its position. Default: (dx, dy) => null
• callbackend: is a function that will be called when the object has been released while being grabbed. Default: () => {}

Events

The grabbable element will trigger the next events:

• grabbable-start:
• grabbable-move:
• grabbable-end:

Sizable

<div class="w-100 h-50 selectable"><div class="selection sizable" style="top:10;left:10;width:100;height:100;"></div></div>
<script>
jsutilslib.sizable($('.sizable'),{ autoaddsizers: true});
</script>

The full list of options that jsutilslib.sizable accepts are the next:

• autoaddsizers: If set, a set of divs will be added to the object to be sized. Default: false

• createsizers: Is a function to be called to append the sizers to the object. Default: a function that creates the 8 common sizers

• classsizing: If set, this is the class which will be set for the object while being sized. Default: sizing

• callbackstart: is a function that will be called when a sizer is clicked to start sizing the object. Default: () => {}

• callbackmove: is a function that will be called when the object has changed its size. Default: (dx, dy) => null

• callbackend: is a function that will be called when the object ends its re-sizing. Default: () => {}

Events

The grabbable element will trigger the next events:

• sizable-start:
• sizable-size:
• sizable-end: