# 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: 20240122
- 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 string pure value from an input of any kind
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}
@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 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}
@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 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} num, {Boolean} allow_negatives ) => {} . {Integer}
@return: {Integer} An integer number
@param: {Numeric} num A numeric value
@param: {Boolean} 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} num, {Integer} decimals, {Boolean} allow_negatives, {Boolean} discard_trailing_zeroes, {Boolean} decimals_separator ) => {} . {String}
@return: {String} A decimal number as string to keep the fixed decimals as specified
@param: {Numeric} num A numeric value as Number or String ; decimal separator is `.` (dot)
@param: {Integer} decimals *Optional* Default is 2 ; The number of decimal to use (between 1 and 13)
@param: {Boolean} allow_negatives *Optional* Default is TRUE ; If FALSE will disallow negative (will return just positive / unsigned values)
@param: {Boolean} discard_trailing_zeroes *Optional* Default is FALSE ; If set to TRUE will discard trailing zeroes
@param: {Boolean} decimals_separator *Optional* Default is FALSE ; If set to TRUE will add thousands separator `,` (comma)
Format a number as DECIMAL
public static randNum = ( {Integer} min, {Integer} max ) => {} . {Integer}
@return: {Integer} The random value
@param: {Integer} min The min value
@param: {Integer} max The max value
Get a Random (Integer) Number between Min and Max
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 utf8Enc ( {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 utf8Dec ( {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} isBinary ) {} . {String}
@hint: It is compatible with PHP bin2hex() method.
@return: {String} The processed string
@param: {String} s The string to be processed
@param: {Boolean} isBinary Encoding character set mode ; default is FALSE ; set to TRUE if the string is binary ASCII to avoid normalize as UTF-8 ; for normal, UTF-8 content this must be set to FALSE
Convert data into hexadecimal representation.
public static function hex2bin ( {String} hex, {Boolean} isBinary ) {} . {String}
@hint: It is compatible with PHP hex2bin() method.
@return: {String} The processed string
@param: {String} hex The string to be processed
@param: {Boolean} isBinary Decoding character set mode ; default is FALSE ; set to TRUE if the string is binary ASCII to avoid normalize as UTF-8 ; for normal, UTF-8 content this must be set to FALSE
Decodes a hexadecimally encoded string.
public static function b64Enc ( {String} str, {Boolean} isBinary ) {} . {String}
@throws: console.error
@return: {String} the Base64 encoded string or empty string if errors
@param: {String} str The plain string (to be encoded)
@param: {Boolean} isBinary Encoding character set mode ; default is FALSE ; set to TRUE if the string is binary ASCII to avoid normalize as UTF-8 ; for normal, UTF-8 content this must be set to FALSE
Encode a string to Base64, using browser native implementation: btoa()
Supports also UTF-8
public static function b64Dec ( {String} str, {Boolean} isBinary ) {} . {String}
@throws: console.error
@return: {String} the plain (B64 decoded) string or empty string if errors
@param: {String} str The B64 encoded string
@param: {Boolean} isBinary Decoding character set mode ; default is FALSE ; set to TRUE if the string is binary ASCII to avoid normalize as UTF-8 ; for normal, UTF-8 content this must be set to FALSE
Decode a string from Base64
Supports also UTF-8
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: 2024-12-16 17:00:46 +0000

Smart.Framework © 2009-2024 unix-world.org