This library consists of a set of utility functions, clases, etc. that can be used in JavaScript applications. The underlying idea is to create curated components that are flexible enough to be re-used in different applications.
The library is intended to be used in conjunction with jQuery
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...)
- tag: function that creates an Element from a pug-like description (e.g. p#myid.myclass.myotherclass)
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 uglifycss).
A Makefile is provided to create the single all-in-one js and css files for the library.
# npm install -g uglify-js uglifycss
...
# git clone https://github.com/dealfonso/jsutils
# cd jsutils
# make
uglifyjs js/*.js -o jsutils.min.js
uglifycss css/*.css > jsutils.min.cssNow you can use files jsutils.min.js and jsutils.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="jsutils.min.js"></script>
<link rel="stylesheet" href="jsutils.min.css">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>
jsutils.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>
jsutils.selectable($('.selectable'), {
callbackstart: function () {
$(this).find('.selection').remove();
}
})
<script>The full list of options that jsutils.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}
The selectable element will trigger the next events:
- selectable-start:
- selectable-move:
- selectable-end:
<div class="w-100 h-50 selectable"><div class="selection" style="top:10;left:10;width:100;height:100;"></div></div>
<script>
jsutils.grabbable($('.selection'));
</script>The full list of options that jsutils.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:
() => {}
The grabbable element will trigger the next events:
- grabbable-start:
- grabbable-move:
- grabbable-end:
<div class="w-100 h-50 selectable"><div class="selection sizable" style="top:10;left:10;width:100;height:100;"></div></div>
<script>
jsutils.sizable($('.sizable'),{ autoaddsizers: true});
</script>The full list of options that jsutils.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 // If set, this is the class which will be set for the object while being moved
-
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:
() => {}
The grabbable element will trigger the next events:
- sizable-start:
- sizable-size:
- sizable-end:
This is a helper function, used to create html objects from pug-like object description.
jsutils.tag('p#id1.class1.class2');will create a tag like
<p id="id1" class="class1 class2"></p>The prototype of tag function is
jsutils.tag(htmldescription, text)
jsutils.tag(htmldescription, properties, text)The parameter description is the next:
- htmldescription: is the description of the object, using the notation
[tag name][#id][.class1][.class2]...[.classN]. If ommited, the tag name will be considered asdiv; if ommited the other parts, they will not be included in the html tag. - text: is the text content for the object.
- properties: is a dictionary of attributes that will appear in the html tag.
Examples
jsutils.tag("p.small", "New tag")creates<p class="small">New tag</p>jsutils.tag(".selectable", {style: "width: 100%"})creates<div class="selectable" style="width: 100%;"></div>jsutils.tag("#selection.selectable")creates<div id="selection" class="selectable"></div>