Skip to content

Commit ef6d07e

Browse files
dealfonsodealfonso
committed
update docs
1 parent 03287b9 commit ef6d07e

File tree

2 files changed

+268
-30
lines changed

2 files changed

+268
-30
lines changed

‎README.md‎

Lines changed: 214 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,214 @@
1-
# common
2-
Common utilities for jsutils library
1+
# jsutilslib common utilities
2+
This is a set of javascript helper classes and functions for javascript applications.
3+
4+
_jsutilslib_ can be used by themselves in your web applications, but they are also part of [`jsutilslib`](https://github.com/jsutilslib/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.
5+
6+
> 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.
7+
8+
## Common utilities
9+
The library consists of the next utilities:
10+
11+
- tag: enables to create html elements using a notation similar to pug or jade.
12+
- processprops: processes the properties of an object by applying a function to each of them; it is also able to clone the object.
13+
- clone: is a shorthand for processprops that forces cloning the object.
14+
- merge: merges two objects into a single one, but only those properties that are part of the first one.
15+
- Array._trim: appends a function to the Array prototype that removes the empty elements from an array.
16+
- Element._append: is a proxy to Element.append() function that returns the element thus enabling to chain multiple actions on the object.
17+
18+
## Using
19+
20+
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`).
21+
22+
A `Makefile` is provided to create the single all-in-one `js` files for the library.
23+
24+
```console
25+
# npm install -g uglify-js
26+
...
27+
# git clone https://github.com/jsutilslib/common
28+
# cd common
29+
# make
30+
uglifyjs js/*.js -b | cat notice - > common.js
31+
uglifyjs js/*.js | cat notice.min - > common.min.js
32+
```
33+
34+
Now you can use files `common.min.js`:
35+
36+
```html
37+
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
38+
<script src="common.min.js"></script>
39+
```
40+
41+
### From a CDN
42+
43+
It is possible to use `common` directly from a CDN:
44+
45+
```html
46+
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
47+
<script src="https://cdn.jsdelivr.net/gh/jsutilslib/common@1.0.0-beta/common.min.js"></script>
48+
```
49+
50+
## Documentation
51+
52+
### Tag
53+
54+
This is a helper function, used to create html objects from pug-like object description.
55+
56+
```javascript
57+
jsutilslib.tag('p#id1.class1.class2');
58+
```
59+
60+
will create a tag like
61+
62+
```html
63+
<p id="id1" class="class1 class2"></p>
64+
```
65+
66+
The prototype of `tag` function is
67+
68+
```javascript
69+
jsutilslib.tag(htmldescription, text)
70+
jsutilslib.tag(htmldescription, properties, text)
71+
```
72+
73+
The parameter description is the next:
74+
- _htmldescription_: is the description of the object, using the notation `[tag name][#id][.class1][.class2]...[.classN]`. If ommited, the tag name will be considered as `div`; if ommited the other parts, they will not be included in the html tag.
75+
- _text_: is the text content for the object.
76+
- _properties_: is a dictionary of attributes that will appear in the html tag.
77+
78+
**Examples**
79+
80+
- `jsutilslib.tag("p.small", "New tag")` creates `<p class="small">New tag</p>`
81+
- `jsutilslib.tag(".selectable", {style: "width: 100%"})` creates `<div class="selectable" style="width: 100%;"></div>`
82+
- `jsutilslib.tag("#selection.selectable")` creates `<div id="selection" class="selectable"></div>`
83+
84+
85+
### processprops
86+
87+
`processprops` is a function that processes the properties of an object, by applying a function to each of them.
88+
89+
The prototype of `processprops` of the function is the next:
90+
91+
```javascript
92+
function processprops(target, objectfnc = v => v, clone = false)
93+
```
94+
95+
Where
96+
- _target_: is the object whose properties are to be processed.
97+
- _objectfnc_: is the function to apply to each property. The prototype is `function(value, name_of_propery, object)`.
98+
- _clone_: if true, a new object will be
99+
100+
Let's explain it by an example:
101+
102+
```javascript
103+
let obj = { a:1, b:2, c:3 };
104+
let obj1 = jsutilslib.processprops(obj, (x) => (x + 1));
105+
```
106+
107+
In this example, the function `(x) => (x + 1)` is applied to each property, and the result is the next:
108+
109+
```javascript
110+
{a: 2, b: 3, c: 4}
111+
```
112+
113+
As we did not clone the object (parameter clone set to `false` by default), both obj and obj1 objects are the same. Then if we change a property in obj1, it will be reflected in obj:
114+
115+
```javascript
116+
$ obj1.a = 10
117+
10
118+
$ obj
119+
{a: 10, b: 3, c: 4}
120+
```
121+
122+
If we wanted each object to be different, we could clone the object:
123+
124+
```javascript
125+
$ obj = { a:1, b:2, c:3 };
126+
$ let obj2 = jsutilslib.processprops(obj, (x) => (x + 1), true)
127+
{a: 2, b: 3, c: 4}
128+
```
129+
130+
And if we modify obj2, we'll see that obj keeps its state:
131+
132+
```javascript
133+
$ obj2.a = 20
134+
20
135+
$ obj
136+
{a: 1, b: 2, c: 3}
137+
$ obj2
138+
{a: 20, b: 3, c: 4}
139+
```
140+
141+
The function also works with arbitrary object and arbitrary processing functions.
142+
143+
```javascript
144+
$ class TestClass {
145+
constructor (a) {
146+
this.a = a;
147+
}
148+
}
149+
$ a1 = new TestClass("simpleA")
150+
TestClass {a: 'simpleA'}
151+
a: "simpleA"
152+
[[Prototype]]: Object
153+
$ a2 = jsutilslib.processprops(a1, (x) => new TestClass(x))
154+
TestClass {a: TestClass}
155+
a: TestClassa: "simpleA"
156+
[[Prototype]]: Object
157+
[[Prototype]]: Object
158+
```
159+
160+
Even it works when cloning the object
161+
162+
```javascript
163+
$ a3 = new TestClass("simpleA")
164+
TestClass {a: 'simpleA'}
165+
a: "simpleA"
166+
[[Prototype]]: Object
167+
$ a4 = jsutilslib.processprops(a3, (x) => new TestClass(`independent ${x}`), true)
168+
TestClass {a: TestClass}
169+
a: TestClass
170+
a: "independent simpleA"
171+
[[Prototype]]: Object
172+
[[Prototype]]: Object
173+
```
174+
175+
### clone
176+
177+
Function `clone` is a shorthand for `processprops` which clones the object and its properties. The prototype is the next
178+
179+
```javascript
180+
function clone(target, objectfnc = x => clone(x))
181+
```
182+
183+
### merge
184+
185+
This function walks over the properties of one object and sets the properties to the values of the properties with the same name in other project. The function returns a different object. This is useful for e.g. creating settings from default values and user provided ones.
186+
187+
```javascript
188+
$ defaults = {
189+
classdragging: 'grabbing',
190+
callbackstart: function() {},
191+
callbackend: function() {},
192+
callbackmove: function(dx, dy) {}
193+
}
194+
$ settings = jsutilslib.merge(defaults, { classdragging: "dragging" });
195+
```
196+
197+
### Array._trim
198+
199+
Function `_trim` is appended to the prototype of class Array. This function removes the _empty elements_ from the array (those that evaluate to a string equal to "").
200+
201+
```javascript
202+
$ a = ['a', 'b', '', 'd' ]
203+
$ a._trim()
204+
['a', 'b', 'd']
205+
```
206+
207+
### Element._append
208+
209+
Function `_append` is appended to the prototype of class Element. This function simply calls function `Element.append`, but also returns the object in order to enable function chaining.
210+
211+
```javascript
212+
$ document.querySelector('body')._append(jsutilslib.tag("p", "content"))._append(jsutilslib.tag("p", "more content"))
213+
```
214+

‎test/test.html‎

Lines changed: 54 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,71 @@
11
<html><head>
22
<title>Test</title>
33
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
4-
<script src="utils.js"></script>
4+
<script src="../js/utils.js"></script>
55
<style>
66
p.white {
77
color: white;
88
}
99
p.bold {
1010
font-weight: bold;
1111
}
12+
code {
13+
display: block;
14+
white-space: pre !important;
15+
background-color: #eee;
16+
padding: 10px;
17+
border: 1px solid #ccc;
18+
color: #333;
19+
overflow: auto;
20+
}
1221
</style>
22+
<script>
23+
$(function() {
24+
$('pre').each(function() {
25+
$(this).html($(this).html().trim());
26+
})
27+
$('body script').each(function() {
28+
$('<code>').text($(this).html().trim()).insertBefore($(this))
29+
})
30+
})
31+
</script>
1332
</head>
1433
<body>
15-
<h1>Test</h1><p id="p1" class="white bold" style="background: green;">Hello World!</p>
16-
34+
<h1>Tag</h1>
1735
<script>
18-
$(function() {
19-
$('h1').after(jsutils.tag('p#p1.white.bold', {style:"background: green"}, 'Hello World!'));
20-
console.assert($('#p1').get(0).outerHTML == '<p id="p1" class="white bold" style="background: green;">Hello World!</p>', "the html tag differs from expected");
21-
22-
let obj = {
23-
a: 1,
24-
b: 2,
25-
c: 3
26-
};
27-
let obj1 = jsutils.processprops(obj, (x) => (x + 1));
28-
obj1.a = 1;
29-
console.assert(obj.a === obj1.a, "not cloned object should be the same");
30-
31-
let obj2 = jsutils.processprops(obj, (x) => (x + 1), true);
32-
obj2.a = 2;
33-
console.assert(obj.a !== obj2.a, "cloned object should be different");
36+
$('h1').after(jsutilslib.tag('p#p1.white.bold', {style:"background: green"}, 'Hello World!'));
37+
console.assert($('#p1').get(0).outerHTML == '<p id="p1" class="white bold" style="background: green;">Hello World!</p>', "the html tag differs from expected");
38+
</script>
39+
<h1>processprops</h1>
40+
<script>
41+
let obj = {
42+
a: 1,
43+
b: 2,
44+
c: 3
45+
};
46+
let obj1 = jsutilslib.processprops(obj, (x) => (x + 1));
47+
obj1.a = 1;
48+
console.log(obj.a === obj1.a, "not cloned object should be the same");
49+
console.assert(obj.a === obj1.a, "not cloned object should be the same");
3450

35-
let obj3 = jsutils.clone(obj);
36-
obj3.a = 3;
37-
console.assert(obj.a !== obj3.a, "cloned object should be different");
51+
let obj2 = jsutilslib.processprops(obj, (x) => (x + 1), true);
52+
obj2.a = 2;
53+
console.log(obj.a !== obj2.a, "cloned object should be different");
54+
console.assert(obj.a !== obj2.a, "cloned object should be different");
3855

39-
let a = Array("a", "", "c", "d", "");
40-
let b = a._trim();
41-
console.assert(b.length === 3, "array should have 5 elements");
42-
console.assert(b.filter(x => a.includes(x)).length === 3, "all elements from the resulting array must exist in the original array")
43-
})
56+
let obj3 = jsutilslib.clone(obj);
57+
obj3.a = 3;
58+
console.log(obj.a !== obj3.a, "cloned object should be different");
59+
console.assert(obj.a !== obj3.a, "cloned object should be different");
60+
</script>
61+
<h1>array trim</h1>
62+
<script>
63+
let a = Array("a", "", "c", "d", "");
64+
let b = a._trim();
65+
console.log(b.length === 3, "array should have 5 elements");
66+
console.assert(b.length === 3, "array should have 5 elements");
67+
console.log(b.filter(x => a.includes(x)).length === 3, "all elements from the resulting array must exist in the original array")
68+
console.assert(b.filter(x => a.includes(x)).length === 3, "all elements from the resulting array must exist in the original array")
4469
</script>
45-
</body></html>
70+
</body>
71+
</html>

0 commit comments

Comments
 (0)