static class smartJ$Utils
{ } .

CLASS :: Smart CoreUtils (ES6, Strict Mode)
The class provides the core methods for JavaScript API of Smart.Framework

Language: Javascript
Located at: lib/js/framework/smart-framework.pak.js; core_utils.js
Package: Sf.Javascript:Core
Class Name: smartJ$Utils
Frozen: Yes
Version: 20231010
Usage: smartJ$Utils.method();

class Methods

public static evalJsFxCode = ( {String} fxContext, {JS-Code} jsCode, {Boolean} alertErr ) => {} . {Boolean}

@return: {Boolean} TRUE if successful, FALSE otherwise
@param: {String} fxContext The Fx context where is executed, used just for logging if fails to know which context is
@param: {JS-Code} jsCode Js callable method or Js plain code
@param: {Boolean} alertErr *Optional* Default is FALSE ; If set to TRUE if eval fails will display an alert message

Evaluate Mixed Js Code in a context
Will evalute and execute mixed Js Code (Js callable method or Js plain code) within a try/catch context
If fails, will log errors to the console and optional if set so it can display an alert message

public static isFiniteNumber = ( {Number} num ) => {} . {Boolean}

@return: {Boolean} TRUE is number is Finite and !NaN ; FALSE otherwise
@param: {Number} num The number to be tested

Check if a number is valid: must be Number, Finite and !NaN

public static stringPureVal = ( {Mixed} input, {Boolean} trim ) => {} . {String}

@return: {String} The value converted to string, using rules from above
@param: {Mixed} input The input
@param: {Boolean} trim If TRUE will trim the output result

Return a pure string value from an input
RULES:
- Undefined, Null or False will be casted to empty string as ''
- True will be casted to '1' as in PHP not to 'true' as in Javascript
- Object or Function will be casted to empty string for safety, as ''
- Numerioc values will be casted to string as they are

public static stringTrim = ( {String} str ) => {} . {String}

@return: {String} The trimmed string
@param: {String} str The string to be trimmed

Trim a string for whitespaces (at begining and/or end) ; whitespaces: space \ n \ r \ t)

public static stringLeftTrim = ( {String} str ) => {} . {String}

@return: {String} The trimmed string (left only)
@param: {String} str The string to be trimmed on Left

Left Trim a string for whitespaces (at begining and/or end) ; whitespaces: space \ n \ r \ t)

public static stringRightTrim = ( {String} str ) => {} . {String}

@return: {String} The trimmed string (right only)
@param: {String} str The string to be trimmed on Right

Right Trim a string for whitespaces (at begining and/or end) ; whitespaces: space \ n \ r \ t)

public static stringUcFirst = ( {String} str ) => {} . {String}

@hint: The implementation is compatible with PHP unicode mb_convert_case/MB_CASE_UPPER on the first letter
@return: {String} The processed string
@param: {String} str The string to be processed

Make uppercase the first character of a string

public static stringUcWords = ( {String} str ) => {} . {String}

@hint: The implementation is compatible with PHP unicode mb_convert_case/MB_CASE_TITLE
@return: {String} The processed string
@param: {String} str The string to be processed

Make uppercase the first character of each word in a string while making lowercase the others

public static stringReplaceAll = ( {String} token, {String} newToken, {String} str ) => {} . {String}

@return: {String} The processed string
@param: {String} token The string part to be replaced
@param: {String} newToken The string part replacement
@param: {String} str The string where to do the replacements

Replace all occurences in a string - Case Sensitive

public static function stringIReplaceAll ( {String} token, {String} newToken, {String} str ) {} . {String}

Replace all occurences in a string - Case Insensitive

public static function stringRegexMatchAll ( {String} str, {Regex} regexp ) {} . {Array}

@hint: It is compatible just with the PHP preg_match_all()
@return: {Array} The array with matches
@param: {String} str The string to be searched
@param: {Regex} regexp A valid regular expression

Regex Match All occurences.

public static stringContains = ( {String} str, {String} search, {Integer} pos ) => {} . {Boolean}

@return: {Boolean} TRUE if the str contains search begining from the pos
@param: {String} str The string to search in (haystack)
@param: {String} search The string to search for in haystack (needle)
@param: {Integer} pos *Optional* ; Default is zero ; The position to start (0 ... n)

Find if a string contains another sub-string, case sensitive

public static stringIContains = ( {String} str, {String} search, {Integer} pos ) => {} . {Boolean}

Find if a string contains another sub-string, case insensitive

public static stringStartsWith = ( {String} str, {String} search ) => {} . {Boolean}

@return: {Boolean} TRUE if the str starts with the search
@param: {String} str The string to search in (haystack)
@param: {String} search The string to search for in haystack (needle)

Find if a string starts with another sub-string, case sensitive

public static stringIStartsWith = ( {String} str, {String} search ) => {} . {Boolean}

@return: {Boolean} TRUE if the str starts with the search
@param: {String} str The string to search in (haystack)
@param: {String} search The string to search for in haystack (needle)

Find if a string starts with another sub-string, case insensitive

public static stringEndsWith = ( {String} str, {String} search ) => {} . {Boolean}

@return: {Boolean} TRUE if the str ends with the search
@param: {String} str The string to search in (haystack)
@param: {String} search The string to search for in haystack (needle)

Find if a string ends with another sub-string, case sensitive

public static stringIEndsWith = ( {String} str, {String} search ) => {} . {Boolean}

@return: {Boolean} TRUE if the str ends with the search
@param: {String} str The string to search in (haystack)
@param: {String} search The string to search for in haystack (needle)

Find if a string ends with another sub-string, case insensitive

public static preg_quote = ( {String} str ) => {} . {String}

@hint: It is compatible with PHP preg_quote() method.
@return: {String} The processed string
@param: {String} str The string to be processed

Quote regular expression characters in a string.

public static stringSplitbyEqual = ( {String} str ) => {} . {Array}

@return: {Array} The array with string parts splitted
@param: {String} str The string to be splitted by = (equal)

Split string by equal (=) with trimming prefix/suffix

public static stringSplitbyColon = ( {String} str ) => {} . {Array}

@return: {Array} The array with string parts splitted
@param: {String} str The string to be splitted by : (colon)

Split string by colon (:) with trimming prefix/suffix

public static stringSplitbySemicolon = ( {String} str ) => {} . {Array}

@return: {Array} The array with string parts splitted
@param: {String} str The string to be splitted by ; (semicolon)

Split string by semicolon (;) with trimming prefix/suffix

public static stringSplitbyComma = ( {String} str ) => {} . {Array}

@return: {Array} The array with string parts splitted
@param: {String} str The string to be splitted by , (comma)

Split string by comma (,) with trimming prefix/suffix

public static arrayGetFirst = ( {Array} arr ) => {} . {Mixed}

@return: {Mixed} The first element from the array
@param: {Array} arr The array to be used

Get the first element from an Array

public static arrayGetLast = ( {Array} arr ) => {} . {Mixed}

@return: {Mixed} The last element from the array
@param: {Array} arr The array to be used

Get the last element from an Array

public static format_number_float = ( {Numeric} num, {Boolean} allow_negatives ) => {} . {Float}

@return: {Float} A float number
@param: {Numeric} num A numeric value
@param: {Boolean} allow_negatives *Optional* ; default is TRUE ; If set to FALSE will disallow negative values and if negative value detected will reset it to zero

Format a number as FLOAT

public static format_number_int = ( {Numeric} y_number, {Boolean} y_allow_negatives ) => {} . {Integer}

@return: {Integer} An integer number
@param: {Numeric} y_number A numeric value
@param: {Boolean} y_allow_negatives If TRUE will allow negative values else will return just positive (unsigned) values

Format a number as INTEGER

public static format_number_dec = ( {Numeric} y_number, {Integer} y_decimals, {Boolean} y_allow_negatives, {Boolean} y_discard_trailing_zeroes ) => {} . {String}

@return: {String} A decimal number as string to keep the fixed decimals as specified
@param: {Numeric} y_number A numeric value as Number or String
@param: {Integer} y_decimals *Optional* Default is 2 ; The number of decimal to use (between 1 and 13)
@param: {Boolean} y_allow_negatives *Optional* Default is TRUE ; If FALSE will disallow negative (will return just positive / unsigned values)
@param: {Boolean} y_discard_trailing_zeroes *Optional* Default is FALSE ; If set to TRUE will discard trailing zeroes

Format a number as DECIMAL

public static function stripslashes ( {String} str ) {} . {String}

@hint: It is compatible with PHP stripslashes() method.
@return: {String} The processed string
@param: {String} str The string to be processed

Un-quotes a quoted string.
It will remove double / quoted slashes.

public static function addcslashes ( {String} str, {String} charlist ) {} . {String}

@hint: It is compatible with PHP addcslashes() method.
@return: {String} Returns the escaped string
@param: {String} str The string to be escaped
@param: {String} charlist A list of characters to be escaped. If charlist contains characters \n, \r etc., they are converted in C-like style, while other non-alphanumeric characters with ASCII codes lower than 32 and higher than 126 converted to octal representation

Quote string with slashes in a C style.

public static escape_css = ( {String} str ) => {} . {String}

@hint: It is like the Smart::escape_css() from the PHP Smart.Framework.
@return: {String} The safe escaped string to be injected in CSS code
@param: {String} str The string to be escaped

Convert special characters to HTML entities.

public static escape_html = ( {String} str ) => {} . {String}

@hint: It is like the Smart::escape_html() from the PHP Smart.Framework.
@return: {String} The safe escaped string to be injected in HTML code
@param: {String} str The string to be escaped

Convert special characters to HTML entities.
These values will be converted to safe HTML entities: < > & "

public static function escape_js ( {String} str ) {} . {String}

@hint: It is like the Smart::escape_js() from the PHP Smart.Framework.
@return: {String} The escaped string using the json encode standard to be injected between single quotes '' or double quotes ""
@param: {String} str The string to be escaped

Convert special characters to escaped entities for safe use with Javascript Strings.

public static escape_url = ( {String} str ) => {} . {String}

@hint: It is like the Smart::escape_url() ; can be used as a shortcut to the encodeURIComponent() to provide a standard into Smart.Framework/JS.
@return: {String} The escaped URL variable
@param: {String} str The URL variable value to be escaped

Safe escape URL Variable (using RFC3986 standards to be full Unicode compliant).

public static nl2br = ( {String} str ) => {} . {String}

@hint: It is compatible with the PHP nl2br() method.
@return: {String} The processed string with <br> html tags if new lines were detected
@param: {String} str The string to be processed

Replace new lines \ r \ n ; \ n with the <br> html tag.

public static function utf8_encode ( {String} str ) {} . {String}

@return: {String} The processed string
@param: {String} str The string to be processed

Encodes an ISO-8859-1 string to UTF-8

public static function utf8_decode ( {String} utftext ) {} . {String}

@return: {String} The processed string
@param: {String} utftext The string to be processed

Decodes an UTF-8 string to ISO-8859-1

public static function deaccent_str ( {String} strIn ) {} . {String}

@hint: It is like PHP SmartUnicode deaccent str
@return: {String} The de-accented string
@param: {String} strIn The string to be de-accented

De-Accent a latin-based Unicode string
Will convert all accented characters in UTF-8 / ISO-8859-* with their unnaccented versions into ISO-8859-1

public static function bin2hex ( {String} s, {Boolean} bin ) {} . {String}

@hint: It is compatible with PHP bin2hex() method.
@return: {String} The processed string
@param: {String} s The string to be processed
@param: {Boolean} bin Set to TRUE if the string is binary to avoid re-encode to UTF-8

Convert binary data into hexadecimal representation.

public static function hex2bin ( {String} hex, {Boolean} bin ) {} . {String}

@hint: It is compatible with PHP hex2bin() method.
@return: {String} The processed string
@param: {String} hex The string to be processed
@param: {Boolean} bin Set to TRUE if the string is binary to avoid re-decode as UTF-8

Decodes a hexadecimally encoded binary string.

public static function uuid ( ) {} . {String}

@return: {String} A unique UUID, time based, base36 ; Ex: 1A2B3C4D5E

Generate a base36 10-chars length UUID

public static function textSort ( {Mixed} property, {Boolean} useLocale ) {} . {Method}

@return: {Method} The stack sort method
@param: {Mixed} property The stack to be sorted
@param: {Boolean} useLocale *Optional* default is FALSE ; if TRUE will try sort using locales and if fail will fallback on raw string comparison ; if FALSE will use the default string comparison

Sort a stack (array / object / property) using String Sort algorithm

public static numericSort = ( {Mixed} property ) => {} . {Method}

@return: {Method} The stack sort method
@param: {Mixed} property The stack to be sorted

Sort a stack (array / object / property) using Numeric Sort algorithm

public static url_add_suffix = ( {String} url, {String} suffix ) => {} . {String}

@return: {String} The prepared URL in the standard RFC3986 format (all values are escaped using escape_url() to be Unicode full compliant
@param: {String} url The base URL to use as prefix like: script.php or script.php?a=b&c=d or empty
@param: {String} suffix A RFC3986 URL segment like: a=b or E=%20d (without ? or not starting with & as they will be detected if need append ? or &; variable values must be encoded using escape_url() RFC3986)

Add URL Suffix (to a standard RFC3986 URL) as: script.php?a=b&C=D&e=%20d

public static create_slug = ( {String} str, {Boolean} lowercase, {Integer} maxlen ) => {} . {String}

@return: {String} The slug which will contain only: a-z 0-9 _ - (A-Z will be converted to a-z if lowercase is enforced)
@param: {String} str The string to be processed
@param: {Boolean} lowercase *OPTIONAL* If TRUE will return the slug with enforced lowercase characters ; DEFAULT is FALSE
@param: {Integer} maxlen *OPTIONAL* If a positive value greater than zero is supplied here the slug max length will be constrained to the value

Creates a Slug (URL safe slug) from a string

public static create_htmid = ( {String} str ) => {} . {String}

@return: {String} The HTML-ID which will contain only: a-z A-Z 0-9 _ -
@param: {String} str The string to be processed

Creates a compliant HTML-ID (HTML ID used for HTML elements) from a string

public static create_jsvar = ( {String} str ) => {} . {String}

@return: {String} The Js-Var which will contain only: a-z A-Z 0-9 _ $
@param: {String} str The string to be processed

Creates a compliant Js-Var (JavaScript Variable Name) from a string

public static function renderMarkersTpl ( {String} template, {ArrayObj} arrobj, {Boolean} isEncoded, {Boolean} revertSyntax ) {} . {String}

@hint: To be used together with the server-side Marker-TPL templating (ex; PHP), to avoid the server-side markers to be rendered ; ex: `[###MARKER###]` will need the template to be escape_url+escape_js ; for this purpose the 3rd param can be set to true: isEncoded = TRUE
@return: {String} The processed string
@param: {String} template The string template with markers
@param: {ArrayObj} arrobj The Object-Array with marker replacements as { 'MAR.KER_1' => 'Value 1', 'MARKER-2' => 'Value 2', ... }
@param: {Boolean} isEncoded If TRUE will do a decoding over template string (apply if TPL is sent as encoded from server-side or directly in html page)
@param: {Boolean} revertSyntax If TRUE will do a revertNosyntaxContentMarkersTpl() over template string (apply if TPLs is sent with syntax escaped)

Render Simple Marker-TPL Template + Comments + Specials (only markers replacements with escaping or processing syntax and support for comments and special replacements: SPACE, TAB, R, N ; no support for IF / LOOP / INCLUDE syntax since the js regex is too simplistic and it can be implemented using real js code)
It is compatible just with the REPLACE MARKERS of Smart.Framework PHP server-side Marker-TPL Templating for substitutions on client-side, except the extended syntax as IF/LOOP/INCLUDE.

Sample code: JavaScript
 // sample client side MarkersTPL rendering
 // HINTS on using |js escaping:
 // - never use a marker inside javascript backticks (`) ; ex: don't do this: const test = `[###TEST|js###]`; // it will raise js code compile errors if a string contains a backtick (`) ... this is because the backticks are not escaped by json escaping ...
 // - when using TPL markers inside javascript single quotes (') or double quotes (") just use the escaping: |js ; ex: const test = '[###TEST|js###]'; const test2 = "[###TEST|js###]";
 // - if the context of javascript is using escaped single quotes ('\'\'') or escaped double quotes ("\"\""), if possible use ("''") or ('""') as ("'[###TEST|js###]'") or ('"[###TEST|js###]"') is OK ; but ('\'[###TEST|js###]\'') or ("\"[###TEST|js###]\"") IS NOT OK because the js code will compile but when the js will evaluate the context will raise an error as the strings will terminate premature if they contain a single or double quote ; also using backticks like (`'[###TEST|js###]'`) or (`"[###TEST|js###]"`) is wrong, it is explained above ...
 // - if the javascript context is using escaped single quotes, have to use: ('\'[###TEST|js|js###]\''), which is OK
 // - if the javascript context is using escaped double quotes, have to use: ("\"[###TEST|js|js###]"') + "\""), which is OK
 // see below a real life situation when have to use this:
 const question = '[###QUESTION|js###]'; // OK
 console.log('Question:', question);
 const tpl = '<div onclick="let Question=\'[###QUESTION|js|js###]\'; alert(Question);">[###TITLE|html|js###]</div>'; // the TPL ; OK because is using double |js escaping with single quotes escaping to avoid js errors when js is evaluating the string ...
 const tpl2 = '<div onclick="alert(question);">[###TITLE|html|js###]</div>'; // alternate TPL ; OK, will use the global variable / constant question so making like this avoid adding escaped single or double quotes
 // it is a common situation when building html syntax with javascript to have combined single quotes (javascript) with double quotes (html), so adding in a html attribute another javascript have no other solution than using again single quotes but escaped like \' and if a marker is placed, must add like: let html = '<button onClick="let test = \'[###TEST|js|js###]\';">Test</button>'; // notice the double escaping
 let html = smartJ$Utils.renderMarkersTpl( // render TPL
 		tpl,
 		{
 			'TITLE': 'A Title',
 			'QUESTION': 'A Question'
 		}
 jQuery('body').append(html); // display TPL

class Properties

class Constants

documentation generated on: 2023-10-19 23:19:04 +0000

static class smartJ$Utils { } .

class Methods

class Properties

class Constants

static class smartJ$Utils
{ } .