application-prototype
Version:
Application builder - prototype
617 lines (519 loc) • 17 kB
Markdown
# Documentation of **extensions/prototype**
Links: [Index](../../../README.md)
## Contribution to documentation
if you find code interesting you may participate by updating documentation using pull request or mail messages to [sergiu.gordienco@gmail.com](mailto:sergiu.gordienco@gmail.com)
# Extensions
## prototype
This module will extend default object prototypes as explained below. In addition this module returns a object consisting of following:
```js
{
fn : Object,
object : Object,
string : Object,
_ : function (a, b) { ... },
__ : function (v) { ... }
}
```
Bellow will be explanation for each.
### fn
`fn._`- represent [slDOM library](./sl-dom.md)
`fn.__`- represent slDOMSet library ( **Documentation in Progress** )
`fn.IframeAddContent( iframe, content )` - writes into an iframe content. returns an object with iframe `document` object and iframe `window`.
`fn.base64toBlob( b64Data[,contentType, sliceSize])` - converts and returns a blob from base64 string.
`fn.dataURItoBlobUrl( dataURI[,mimeString] )` - converts and returns a blob from dataURI string.
`fn.downloadFile( filename[,content,encoding,mimetype] )` - creates and start download after 2 seconds of a file/content from page.
`fn.getRandId( [,str] )` - appends `str` to the beginning of a random generated number and returns it. If `str` is true, it will generate a string in base36.
`fn.insertAtCursor( myField, myValue )` - inserts `myValue` string into a text area at current cursor position.
`fn.keyCapture( [,event],[key_map],[vars] )` - allows to create function handlers for keyboard shortcuts. `key_map` is an object of object pairs, where the key is the shortcut, and value is a function to be executed when the key is pressed. `vars` is an additional parameter that does not have any importance, it may be used for `keypress` handler functions.
Key code is generated following way:
`'k_' + ('ctrl'|'shift'|'alt'|'none') + '_' ... + another control key + '_' + keycode`
Example:
```js
'k_ctrl_alt_80'
'k_alt_shift_120'
'k_ctrl_20'
// and so on
```
`fn.mouse = Object`
`fn.mouse.position( [,eventMouseMove, windowOrDocumentObject] )` - returns current mouse position from client area and max possible x/y coordinates.
`fn.window = Object`
`fn.window.size( )` - returns current client area width and height.
`fn.window.sizeLimit` - it's and object. It allows you to set max/min window size.
`fn.window.sizeActive( )` - returns modified client area width and height.
### object
`object.encodeURL( obj [,prefix] )` - URL encode any JavaScript data type.
`object.extend( target, protParams )` - extents target prototype with the prototypes included in `protParams` object.
`protParams` example:
```js
{
key : 'someTitle',
someFuncName : function () {
// some function
},
otherFunc : function () {
// some function
}
visible : true | false,
readonly: true | false,
configurable : false | true
}
```
`object.merge( [ obj ], [ obj ], [ obj ], ... )` - returns an object that has all other objects merged inside it. Can take any number of arguments.
### string
`string` implements 6 encryption algorithms : `aes`, `base64`, `md5`, `sha1`, `sha256`, `tea`.
Each of those may have another functions inside that are straight implementation of algorithms.
### String Prototype
#### Subs Method:
```javascript
String.prototype.subs = function(string, offset, length) {}
```
> `"abcdefghi".subs(2)` is equal to `"ab"`
> `"abcdefghi".subs(2,3)` is equal to `"cde"`
> `"abcdefghi".subs(-2)` is equal to `"hi"`
> `"abcdefghi".subs(1,-2)` is equal to `"bcdefg"`
> `"abcdefghi".subs(-4,3)` is equal to `"fgh"`
#### Subs Method:
```javascript
String.prototype.toHex = function(utf8String) { /*...*/ return hex_str; }
String.prototype.fromHex = function(){ /*...*/ retrun utf8_str; }
String.prototype.fromHtml = function () { /*...*/ return utf8_str}
```
> `"TEST".toHex()` is equal to `"54455354"`
> `"54455354".fromHex()` is equal to `"TEST"`
> `"54455354".fromHex()` is equal to `"TEST"`
> **UTF-8** vs Unicode
> Function `.toHex()` and `.fromHex` is working with **UTF-8** Strings
but javascript is working with **Unicode**
> `"€".toHex()` _(Unicode)_ 1 char in HEX is 2 chars `"20ac"`
> `"20ac".fromHex()` is " ¬"
> So correctly to encode UnicodeText to Hex is
> "€".utf8encode().toHex() and the result is `"e282ac"`
> and `"e282ac".fromHex().utf8decode()` is `"€"`
#### Escape HTML
```javascript
String.prototype.toHtmlSimple = function() { /*...*/ return str; },
String.prototype.toHtml = function(){ /*...*/ return str;},
String.prototype.cleanTags = function() { /*...*/ return str; }
```
#### Check if word exists in a list of words separated by `" "`
```javascript
// add class
String.prototype.add_Class = function(x){},
// remove class
String.prototype.del_Class = function(x){},
// check is calss exists
String.prototype.fnd_Class = function(x){},
```
#### String letterCase change
```javascript
String.prototype.swp_case = function(){ return str; }
String.prototype.ucfirst = function(k){ return str; }
String.prototype.lcfirst = function(k){ return str; }
```
#### Encoding Conversions
```javascript
String.prototype.utf8need = function() { return bool_utf8 }
String.prototype.utf8encode = function() { return utf8_str; }
String.prototype.utf8decode = function(strUtf) { return unicode_str; }
String.prototype.utf8 = String.prototype.utf8encode;
String.prototype.unicode = String.prototype.utf8decode;
String.prototype.escapeHex = function() { /* ... */ return str; },
// on execution: "#$%#$%^".escapeHex()
// return "\x23\x24\x25\x23\x24\x25\x5E"
String.prototype.escape = function() { return escape(this); },
String.prototype.encodeURI = function() { return encodeURIComponent(this); },
String.prototype.unescape = function() { return unescape(this); },
String.prototype.decodeURI = function() { return decodeURIComponent(this); },
String.prototype.toRegexp = function(flags){ return reg_exp_object; }
// on execution: ".*".toRegexp("g")
// returns: /.*/g
```
#### Parse URL links
```javascript
String.prototype.parseUrlVars = function(json,params) { retrun data_object; },
String.prototype.parseUrl = function(url) { return object; }
```
**Examples**
##### Parse URL
```javascript
"http://www.example.com/test?nr=1&module=mvc#link-1".parseUrl()
```
**Returns**
```javascript
{
original : "http://www.example.com/test?nr=1&module=mvc#link-1",
origin : "http://www.example.com",
domain : "www.example.com",
domain_short : "example.com",
pathname: "/test",
reqQuery : "nr=1&module=mvc",
protocol: "http",
protocoll: "http://"
};
```
##### Parse URL with GET vars
```javascript
"http://www.example.com/test?nr=1&module=mvc&val[x]=5#link-1".parseUrl(true)
```
**Returns**
```javascript
{
get_vars : {
nr : 1,
module : mvc,
val : {
x : 5
}
},
original : "http://www.example.com/test?nr=1&module=mvc#link-1",
origin : "http://www.example.com",
domain : "www.example.com",
domain_short : "example.com",
pathname: "/test",
reqQuery : "nr=1&module=mvc",
protocol: "http",
protocoll: "http://"
};
```
##### Parse URL retrieve only GET vars
```javascript
"http://www.example.com/test?nr=1&module=mvc&val[x]=5#link-1".parseUrl("get_vars")
```
**Returns**
```javascript
{
nr : 1,
module : mvc,
val : {
x : 5
}
}
```
##### Parse URL and retrieve only a property from parsed Object
```javascript
"http://www.example.com/test?nr=1&module=mvc&val[x]=5#link-1".parseUrl("origin")
```
**Returns**
```javascript
"http://www.example.com"
```
----
```javascript
"http://www.example.com/test?nr=1&module=mvc&val[x]=5#link-1".parseUrl("reqQuery")
```
**Returns**
```javascript
"nr=1&module=mvc"
```
#### Match a string using a reg expression described in a string
```javascript
String.prototype.match_str = function(regexp_str,regexp_flags) { /* ... */ }
```
#### Make a SHA1 Hash
```javascript
String.prototype.sha1 : function(utf8){return Sha1.hash(this,( utf8 || typeof(utf8) == "undefined" ) ? true : false)},
// "utf8" indicates that code firstly should be encoded to UTF-8 from UNICODE
// default "utf8" argument is true
```
**Example:**
```javascript
"password".sha1();
// returns
"5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8"
```
#### Make a SHA2 Hash
```javascript
String.prototype.sha256 : function(utf8){return Sha256.hash(this,( utf8 || typeof(utf8) == "undefined" ) ? true : false)},
// "utf8" indicates that code firstly should be encoded to UTF-8 from UNICODE
// default "utf8" argument is true
```
**Example:**
```javascript
"password".sha256();
// returns
"5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
```
#### Make a MD5 Hash
```javascript
String.prototype.md5 : function() { /* ... */},
```
**Example:**
```javascript
"password".md5();
// returns
"5f4dcc3b5aa765d61d8327deb882cf99"
```
#### For encoding JavaScript UNICODE code into Base64
```javascript
String.prototype.base64encode : function() { return btoa(this.utf8need()); },
```
#### For decoding JavaScript UNICODE code into Base64
```javascript
String.prototype.base64decode : function() { return atob(this).unicode(); },
```
#### For encoding JavaScript UTF8 and ASCII code into Base64
```javascript
String.prototype.base64encodeClean : function() { return btoa(this); },
```
#### For decoding JavaScript UTF8 and ASCII code into Base64
```javascript
String.prototype.base64decodeClean : function() { return atob(this); },
```
#### Encrypt a String using a passKey and TEA algorithm
```javascript
String.prototype.encryptTea : function(p) { /* ... */ },
```
#### Decrypt a String using a passKey and TEA algorithm
```javascript
String.prototype.decryptTea : function(p) { /* ... */ },
```
#### Encrypt a String using a passKey and passlength ( 128, 192, 256 ) in AES algorithm
```javascript
String.prototype.encryptAes : function(passKey, passlength) { /* ... */ },
```
#### Decrypt a String using a passKey and passlength ( 128, 192, 256 ) in AES algorithm
```javascript
String.prototype.decryptAes : function(passKey, passlength) { /* ... */ },
```
#### String Method buildQuery
```javascript
String.prototype.buildQuery : function() {
var r = /^\s*([a-z]+)\:\s*(\S[^\:]*?|)\s*(\s[a-z]+\:.*|)$/i
var s = this, o = { "_keys" : [] }, m, k, f = s.split(/([a-z]+)\:/i);
if( m = f[0].match(/^\s*(\S[\s\S]*?)\s*$/) ) {
o["_keys"].push("_");
o['_'] = m[1];
};
f = s.substring(f[0].length,s.length);
while( m = f.match(r) ) {
o[k = m[1].toLowerCase()] = m[2];
o["_keys"].push(k);
f = f.split(m[0]).join(m[3]);
};
return o;
},
```
**Example:**
```javascript
"test:234 val:foo bar".buildQuery()
// returns
{
"_keys" : ["test", "val"],
"test" : "234",
"val" : "foo bar"
}
```
#### String Method buildSearchArray
```javascript
String.prototype.buildSearchArray : function() { /*...*/ return arr; }
```
**Example:**
```javascript
"test 'foo bar'".buildSearchArray()
// returns
["test", "foo bar"]
```
#### String Method toArrayBufferFromUtf8, toStringUtf8
```js
String.prototype.toArrayBufferFromUtf8 : function () { /*...*/ return arr;}
String.prototype.toStringUtf8 : function () { /*...*/ return arr;}
```
Example:
```js
'123456'.toArrayBufferFromUtf8()
//returns
[/* 12 bytes*/].toStringUtf8()
//returns
'123456'
```
***
### Blob prototype
#### Blob method toArrayBuffer
```js
Blob.prototype.toArrayBuffer : function () { /*...*/ return arr;}
```
Example:
```js
var a = new Array(10);
a.fill(Math.random());
var b = new Blob(a);
b.toArrayBuffer();
// returns an array that is equal to a
```
#### Blob method toURL
```js
Blob.prototype.URL : function (options) { /*...*/ return url_str;}
```
Example:
```js
var a = new Blob(["test"], { type: "text/css" });
var url = a.toURL();
var url_text_plain = a.toURL({ type: "text/plain" })
```
***
### Array prototype
#### Array method (inArray) - search an element in a array with a defined comparator
```javascript
/*
comparator posible values:
1. '===' - check if is strict equal
2. '==' - check if is equal
3. a _function_ :
function(searched_item,array_item) {
return searched_item === array_item
}
*/
Array.prototype.inArray = function(a,comparator) { /*...*/ },
```
#### Split an Array by an a value of one octet
```javascript
Array.prototype.split = function (elem, num, cmp) { /*...*/ },
```
#### Split an Array by an a section value of one or more bytes
```javascript
Array.prototype.splitSect = function(elem, num) {
return this.split(elem, (num || 0), "indexOfSect");
},
```
#### Array to Blob » array of bytes to Blob
```javascript
Array.prototype.toBlob = function (mimetype, sliceSize) {
return _public.fn.base64toBlob(
this.base64encode(),
mimetype || this.type || "application/octet-binary",
sliceSize
);
};
```
#### Array to base64 » array of bytes to base64 String
```javascript
Array.prototype.base64encode = function () {
return this.toBinaryString().base64encode();
}
```
#### Array to binary » array of bytes to Binary String
```javascript
Array.prototype.toBinaryString = function () {
return this.toBytesBinary().join('');
}
```
#### Array to binary array » array of bytes to array of binary string
```javascript
Array.prototype.toBytesBinary = function () {
return this.map(function (v) { return unescape('%' + ( v < 16 ? '0' : '' ) + v.toString(16)); });
}
```
#### Array to array escaped » array of bytes to array of binary string escaped
```javascript
Array.prototype.toBytesEscaped = function () {
return this.map(function (v) { return '%' + ( v < 16 ? '0' : '' ) + v.toString(16); });
}
```
#### Array to array of hex » array of bytes to array of hex strings
```javascript
Array.prototype.bytesToHex = function() {
return this.map(function (v) { return ( v < 16 ? '0' : '' ) + v.toString(16); });
}
```
#### Convert a Array to an parameter object
```javascript
Array.prototype.toParamObj = function() { /*...*/ },
```
#### Remove from Array undefined values
```javascript
Array.prototype.resetArray = function() {return this.filter(function(v) { return ( typeof(v) != "undefined" ); })},
```
#### Find IndexOf position of a set of elements in a Array
```javascript
Array.prototype.indexOfSect = function (searchElement, fromIndex) { /*...*/ }
```
#### Find min/max in an Array
```js
Array.prototype.min = function () { /*...*/ return min};
Array.prototype.max = function () { /*...*/ return max};
```
Example:
```js
var a = [2,5,7,0,1,2];
a.min(); // returns 0
a.max(); // returns 7
```
#### Mix values in an array aka shuffle
```js
Array.prototype.shuffle = function () { /*...*/ return arr};
```
Example:
```js
var a = [1,2,3,4,5,6,7,8,9,0];
a.shuffle() // returns [4, 2, 6, 1, 5, 8, 9, 3, 7, 0]
a.shuffle() // returns [6, 4, 1, 8, 2, 3, 7, 9, 0, 5]
```
#### Get last index of a value in Array
```js
Array.prototype.lastIndexOf = function (value) { /*...*/ return lastIndex};
```
Example:
```js
var a = [1,2,3,4,5,6,7,3,9,0];
a.lastIndexOf(3); // returns 7
```
#### Find first occurrence and return index or value
```js
Array.prototype.find = function (function (value, index, arr) {
return true | false;
}) { /*...*/ return value};
Array.prototype.findIndex = function (function (value, index, arr) {
return true | false;
}) { /*...*/ return index};
```
Example:
```js
var a = [1,2,3,4,5,6,7,3,9,0];
a.find(function (value, i, arr) {
return value === 3 ? true : false;
});
// returns 3
a.findIndex(function (value, i, arr) {
return value === 3 ? true : false
});
// returns 2
```
#### Find unique values in Array
```js
var a = [1,2,3,4,1,7,8,2,3];
a.unique();
// returns [1,2,3,4,7,8]
```
### Number prototype
```js
Number.prototype.round = function(k) { if(k) return parseFloat(this.toFixed(k)); return Math.round(this); },
```
```js
Number.prototype.ceil = function() { return Math.ceil(this); },
```
```js
Number.prototype.floor = function() { return Math.floor(this); }
```
***
### Function prototype
#### Function method toWorkerURL
```js
Function.prototype.toWorkerURL : function () { /*...*/ return blob_url};
```
#### Function method toWorker
```js
Function.prototype.toWorker : function () { /*...*/ return worker};
```
#### Function method runInWorker
```js
Function.prototype.runInWorker : function () { /*...*/ return worker};
```
***
### Online / offline mode
This library can detect if page is being currently used, if device is offline, inactive, online etc. For this there are several events fired in window:
- device offline: `jsevt-offline`
- device online: `jsevt-online`
- every 500ms is fired visible state event: `jsevt-docview-visible` (currently only visible event is fired)
- on unload : `jsevt-unload`
- on load : `jsevt-load`
To check if user is active or not, call `jsEvtUserActive()`, which will return `true` / `false` depending on user status.