# static class smartJ$Browser
{ } .

CLASS :: Smart BrowserUtils (ES6)
The JavaScript class provides methods to simplify the interraction with the Browser, Ajax XHR Requests, Forms, Message Alerts and Message Dialogs, Growl and provide many useful methods for browser interraction.

- Language: Javascript
- Located at: lib/js/framework/smart-framework.pak.js; browser_utils.js
- Package: Sf.Javascript:Browser
- Class Name: smartJ$Browser
- Frozen: Yes
- Version: 20241125
- Usage: smartJ$Browser.method();
- Depends: smartJ$Utils, smartJ$Date, smartJ$CryptoHash, smartJ$TestBrowser, jQuery, *smartJ$ModalBox, *jQuery.toastr, *jQuery.alertable, *smartJ$UI (optional) [ smartJ$UI.GrowlAdd ; smartJ$UI.GrowlRemove ; smartJ$UI.DialogAlert ; smartJ$UI.DialogConfirm ; smartJ$UI.overlayCssClass ]

## class Methods

public static setFlag = ( {String} flag, {Mixed} value ) => {} . {Boolean}
@return: {Boolean} TRUE if success, FALSE if not
@param: {String} flag The flag to set
@param: {Mixed} value The value of that flag
Set an internal flag
Available flags are:
PageUnloadConfirm {Boolean}
PageAway {Boolean}
RefreshState {0/1}
RefreshURL {String} || ''
public static getFlag = ( {String} flag ) => {} . {Mixed}
@return: {Mixed} The value of that flag
@param: {String} flag The flag to return
Get an internal flag
Available flags are:
PageUnloadConfirm {Boolean}
PageAway {Boolean}
RefreshState {0/1}
RefreshURL {String} || ''
public static getRefPopup = ( ) => {} . {Mixed}
@return: {Mixed} NULL or Object (PopUp Window Reference)
Get the popUp Window Object Reference if any
public static getCurrentIsoDateTime = ( ) => {} . {String}
@return: {String} The Current ISO Date and Time as YYYY-MM-DD HH:II:SS
Get the Current ISO Date and Time
public static stripTags = ( {String} html ) => {} . {String}
@return: {String} Plain Text
@param: {String} html The html code to be processed
Strip HTML Tags and return plain text from HTML Code
public static function parseCurrentUrlGetParams ( {Boolean} semantic_sf_url ) {} . {Object}
@return: {Object} { param1:'value1', param1:'value 2', ... }
@param: {Boolean} semantic_sf_url *Optional* ; Default is TRUE ; If set to FALSE will not post-process the semantic URL parts from Smart.Framework such as: `/page/one/something/else`
Parse Current URL to extract GET Params

    Sample code: JavaScript
     'http(s)://some.url/?param1=value1&param2=value%202' // sample URL

public static PrintPage = ( ) => {} . {Void}
@fires: Print Dialog Show Event
Print current Browser Page
public static function CountDown ( {Integer} counter, {String} elID, {JS-Code} evcode, {Boolean} prettyFormat ) {} . {Void}
@fires: A custom event set in the Js Code to execute when done
@param: {Integer} counter The countdown counter, Min value is 1
@param: {String} elID The HTML Element ID to bind to or NULL
@param: {JS-Code} evcode *Optional* the JS Code to execute on countdown complete (when countdown to zero)
@param: {Boolean} prettyFormat *Optional* if set to TRUE instead to display the left time in seconds will display as pretty format like: Days, Hours, Minutes, Seconds
Count Down handler that bind to a HTML Element
public static windowFocus = ( {Object} wnd ) => {} . {Void}
@fires: activate Focus on a PopUp window
@param: {Object} wnd The window (reference) object ; which ? self, window, ...
Focus a browser window by reference
public static WindowIsiFrame = ( ) => {} . {Boolean}
@return: {Boolean} TRUE if iFrame, FALSE if not
Detect if a Browser Window is an iFrame
public static WindowIsPopup = ( ) => {} . {Boolean}
@return: {Boolean} TRUE if PopUp, FALSE if not
Detect if a Browser Window is a PopUp
public static function PageAwayControl ( {String} the_question ) {} . {Void}
@fires: Ask Confirmation Dialog to confirm navigate away of the page
@listens: Browser Page Unload
@param: {String} the_question The Question to confirm for navigate away of the page
Page Away control handler. Take control over the events as onbeforeunload to prevent leaving the browser page in unattended mode
public static RedirectToURL = ( {String} yURL ) => {} . {Void}
@fires: Browser Location Redirect or Location Reload
@param: {String} yURL The URL (relative or absolute) to redirect to ; if = '@' will just autorefresh the page
Redirect to a new URL or Reload the current browser location
public static function RedirectDelayedToURL ( {String} yURL, {Integer} ytime ) {} . {Void}
@fires: Redirect Browser to a new URL
@listens: TimeOut counter on Set as Delay
@param: {String} yURL The URL (relative or absolute) to redirect to
@param: {Integer} ytime The time delay in milliseconds
Delayed Redirect to URL current browser window
public static function RedirectParent ( {String} yURL ) {} . {Void}
@fires: Redirect Browser to a new URL
@param: {String} yURL The URL (relative or absolute) to redirect to
Redirect to URL the browser parent window
public static function RefreshParent ( {String} yURL ) {} . {Void}
@hint: It will just trigger a lazy refresh on parent that will be executed later, after closing current child window.
@fires: Refresh Parent Window direct (instant) / or indirect (after closing modal)
@param: {String} yURL *Optional* The URL (relative or absolute) to redirect to ; if the parameter is not specified will just reload the parent window with the same URL
Lazy Refresh parent browser window or Lazy redirect parent window to another URL.
The method is different than RedirectParent() because will be executed just after the child (modal iFrame / PopUp) is closed.
public static function CloseModalPopUp ( ) {} . {Void}
@hint: It is the prefered way to close a child window (modal iFrame / PopUp) using a button or just executing some js code in a child page.
@fires: Closes a Modal Box or PopUp Window
Close a Modal / PopUp child browser window.
If a parent refresh is pending will execute it after.
public static function CloseDelayedModalPopUp ( {Integer} timeout ) {} . {Void}
@hint: It is the prefered way to close a child window (modal iFrame / PopUp) using a button or just executing some js code in a child page.
@fires: Closes a Modal Box or PopUp Window
@listens: TimeOut counter on Set
@param: {Integer} timeout The time delay in milliseconds ; If is NULL or 0 (zero) will use the default timeout
Delayed Close a Modal / PopUp child browser window.
If a parent refresh is pending will execute it after.
public static function getCurrentPointerEventXY ( {Event} evt, {Boolean} viwePortOnly ) {} . {Object}
@return: {Object} An object with x and y coordinates as: { x: 123, y: 234, t: 'mousemove' } or { x: 123, y: 234, t: 'touchmove' } ; t (type) can be also other event type ... any of supported by browser ; if can't detect will return by default: { x: -1, y: -1 }
@param: {Event} evt The EVENT Object Reference (must be a pointer event: mouse or touch)
@param: {Boolean} viwePortOnly Default is FALSE ; if TRUE will return clientX / clientY instead of pageX / pageY
Get the Pointer Event pageX / pageY or clientX / clientY coordinates, depending how viwePortOnly is set.
It works on both: mouse or touch devices.
On touch devices will look after: event.touches[0]
On mouse devices directly to: event
The pageX/Y coordinates are relative to the top left corner of the whole rendered page (including parts hidden by scrolling), while clientX/Y coordinates are relative to the top left corner of the visible part of the page (aka ViewPort)
public static function getHighestZIndex ( ) {} . {Integer}
@return: {Integer} The highest available Z-Index from current page
Get the highest available Z-Index from a browser page taking in account all visible layers (div).
It will ignore non-visible layers for speed-up, as they have anyway no Z-Index assigned.
public static function createMaxContainer ( {String} id, {Boolean} maximized ) {} . {Void}
@hint: When the selected element will be maximized the page will be protected by an overlay (all content below the element).
@param: {String} id The HTML id of the HTML element to bind to
@param: {Boolean} maximized *Optional* Default is FALSE ; If set to TRUE the element will be auto-maximized when bind to it
Create a Max Container arround a HTML Element that will add the Maximize View handler over it ; element must be a layer (div, iframe, ...).
It will add a maximize / un-maximize button and the handler for it to be able to maximize the element to match full window width and height.
public static function OverlayShow ( {String} text, {String} title, {String} css_class, {String} overlay_id, {Boolean} clear ) {} . {Object}
@hint: The ZIndex of the overlay is: 2147400000
@return: {Object} The overlay as HTML object
@param: {String} text *Optional* a text to display (HTML) in overlay as notification
@param: {String} title *Optional* a title to display (Plain Text) for overlay as notification
@param: {String} css_class *Optional* a CSS class name for the notification (if any)
@param: {String} overlay_id *Optional* the overlay ID ; default is null and will use a hard-coded ID
@param: {Boolean} clear *Optional* clear the overlay from loading img
Display a page overlay in the current browser window
All page elements that must be visible over the overlay must have zIndex in range: 2147401000 - 214740999
public static OverlayClear = ( {String} overlay_id ) => {} . {Void}
@param: {String} overlay_id *Optional* the overlay ID ; default is null and will use a hard-coded ID
Clear all notifications from the page overlay in the current browser window
public static function OverlayHide ( ) {} . {Void}
Hide (destroy) the page overlay in the current browser window
public static function GrowlNotificationAdd ( {String} title, {String} text, {String} image, {Integer} time, {Boolean} sticky, {Enum} css_class, {Array-Obj} options, {Boolean} isTitleHtml ) {} . {Boolean}
@return: {Boolean} TRUE if Success FALSE if Fail
@param: {String} title a title for the notification (Plain Text) ; it can be empty string
@param: {String} text the main notification message (HTML) ; it is mandatory
@param: {String} image the URL link to a notification icon image (svg/gif/png/jpg/webp) or null
@param: {Integer} time the notification display time in milliseconds ; use 0 for sticky ; between 0 (0 sec) and 60000 (60 sec)
@param: {Boolean} sticky *Optional* FALSE by default (will auto-close after the display time expire) ; TRUE to set sticky (require manual close, will not auto-close)
@param: {Enum} css_class *Optional* a CSS class name for the notification or empty string to use default one: darknote (black), notice (white), info (blue), success (green), warning (yellow), error (red)
@param: {Array-Obj} options *Optional* Extra Growl Properties:
@param: {Boolean} isTitleHtml *Optional* The Dialog Type ; default is FALSE ; If TRUE, will allow HTML Title
Create a Message Growl Notification
{ // example of extra Options
before_open: () => {},
after_open: () => {},
before_close: () => {},
after_close: () => {}
}
public static function GrowlNotificationRemove ( ) {} . {Boolean}
@return: {Boolean} TRUE if Success FALSE if Fail
Remove all Growl Notifications from the current browser window (page)
public static function AlertDialog ( {String} y_message, {JS-Code} evcode, {String} y_title, {Integer} y_width, {Integer} y_height, {String} dialogType, {Boolean} isTitleHtml ) {} . {Void}
@fires: open an Alert Dialog (custom or default, depends on settings)
@param: {String} y_message The message to display (HTML)
@param: {JS-Code} evcode *Optional* the JS Code to execute on closing the alert / Dialog by pressing the OK button (the alert / Dialog can be closed only if OK button is clicked)
@param: {String} y_title *Optional* a title for the alert / Dialog (Plain Text)
@param: {Integer} y_width *Optional* the width of the Dialog (will be used just if UIDialog / SimpleDialog are detected) ; if not set the default width will be used
@param: {Integer} y_height *Optional* the height of the Dialog (will be used just if UIDialog / SimpleDialog are detected) ; if not set the default height will be used
@param: {String} dialogType *Optional* The Dialog Type ; default is 'auto'
@param: {Boolean} isTitleHtml *Optional* The Dialog Type ; default is FALSE ; If TRUE, will allow HTML Title
Create a Browser Alert Dialog that will have just the OK button.
It will detect if the UIDialog is available and will prefer to use it if set.
Otherwise will try to detect if SimpleDialog is available and will use it if UIDialog is not available - fallback.
If none of the above are available will try to use jQuery.alertable/alert else just display a simple alert() - fallback.
public static function ConfirmDialog ( {String} y_question, {JS-Code} evcode, {String} y_title, {Integer} y_width, {Integer} y_height, {String} dialogType, {Boolean} isTitleHtml ) {} . {Void}
@fires: open a Confirmation Dialog (custom or default, depends on settings)
@param: {String} y_question The question / message to display (HTML)
@param: {JS-Code} evcode *Optional* the JS Code to execute on closing the confirm / Dialog by pressing the OK button (the confirm / Dialog can be closed by either OK button clicked or Cancel button clicked ; the code will be not executed on Cancel button click / close)
@param: {String} y_title *Optional* a title for the confirm / Dialog (HTML)
@param: {Integer} y_width *Optional* the width of the Dialog (will be used just if UIDialog / SimpleDialog are detected) ; if not set the default width will be used
@param: {Integer} y_height *Optional* the height of the Dialog (will be used just if UIDialog / SimpleDialog are detected) ; if not set the default height will be used
@param: {String} dialogType *Optional* The Dialog Type ; default is 'auto'
@param: {Boolean} isTitleHtml *Optional* The Dialog Type ; default is FALSE ; If TRUE, will allow HTML Title
Create a Browser Confirm Dialog that will have 2 buttons: OK / Cancel.
It will detect if the UIDialog is available and will prefer to use it if set.
Otherwise will try to detect if SimpleDialog is available and will use it if UIDialog is not available - fallback.
If none of the above are available will try to use jQuery.alertable/confirm else display a simple confirm() - fallback.
public static function MessageNotification ( {String} ytitle, {String} ymessage, {String} yredirect, {Yes/No} growl, {Enum} class_growl, {Integer} timeout ) {} . {Void}
@param: {String} ytitle The Title
@param: {String} ymessage The Message (HTML code)
@param: {String} yredirect *Optional* The URL to redirect
@param: {Yes/No} growl *Optional* If 'yes' will use the Growl notifications otherwise (default: if 'no') will use Dialog notification
@param: {Enum} class_growl *Optional* If Growl is used, a CSS class for Growl is required
@param: {Integer} timeout *Optional* If Growl is used, the Growl timeout in milliseconds
Create a Message (Dialog or Growl) Notification
public static function confirmSubmitForm ( {String} y_confirm, {Html-Form} y_form, {String} y_target, {Integer} windowWidth, {Integer} windowHeight, {Enum} forcePopUp, {Enum} forceDims ) {} . {Void}
@hint: The function is using ConfirmDialog() and will detect and prefer in the specific order if UIDialog / SimpleDialog or just confirm() are available in Browser.
@fires: open a confirmation dialog
@listens: form submit event
@param: {String} y_confirm The question / message to display for confirmation (HTML)
@param: {Html-Form} y_form The HTML Form Object to bind to
@param: {String} y_target The window target to send the form to
@param: {Integer} windowWidth *Optional* the width of the new Modal/PopUp child window if new window target is used ; if not set the default width will be used
@param: {Integer} windowHeight *Optional* the height of the new Modal/PopUp child window if new window target is used ; if not set the default height will be used
@param: {Enum} forcePopUp *Optional* if a new target window is required, 0 = default, use modal/iFrame if set by smartJ$Browser.param_ModalBoxActive, 1 = force PopUp ; -1 force modal/iFrame
@param: {Enum} forceDims *Optional* if set to 1 will try force set the width/height for the new modal/iFrame or PopUp
Confirm a Form Submit by a confirm / Dialog, with OK and Cancel buttons.
The form will be submitted just if OK button is clicked.
public static function PopUpSendForm ( {Html-Form} objForm, {String} strTarget, {Integer} windowWidth, {Integer} windowHeight, {Enum} forcePopUp, {Enum} forceDims, {JS-Code} evcode ) {} . {Void}
@hint: The function if used in a button with 'return false;' will catch the form send behaviour and will trigger it just after the child modal/iFrame or PopUp child window (new) target is opened and available.
@fires: send a form in a pop-up window to avoid loose the current page
@listens: form submit event
@param: {Html-Form} objForm The HTML Form Object reference
@param: {String} strTarget The child window target to post the form to
@param: {Integer} windowWidth *Optional* the width of the new Modal/PopUp child window if new window target is used ; if not set the default width will be used
@param: {Integer} windowHeight *Optional* the height of the new Modal/PopUp child window if new window target is used ; if not set the default height will be used
@param: {Enum} forcePopUp *Optional* if a new target window is required, 0 = default, use modal/iFrame if set by smartJ$Browser.param_ModalBoxActive, 1 = force PopUp ; -1 force modal/iFrame
@param: {Enum} forceDims *Optional* if set to 1 will try force uwing the width/height set for the new modal/iFrame or PopUp
@param: {JS-Code} evcode *Optional* the JS Code to execute after submit the form
Open a Modal/iFrame or PopUp child window with a new target to post a form within.
It will get the form URL and form method GET/POST directly from the objForm.
The function must be called by a form button onClick followed by 'return false;' not by classic submit to avoid fire the form send twice 1st before (in a _blank window) and 2nd after opening the child popup/modal.
public static function PopUpLink ( {String} strUrl, {String} strTarget, {Integer} windowWidth, {Integer} windowHeight, {Enum} forcePopUp, {Enum} forceDims, {Enum} handlerMode ) {} . {Void}
@hint: The function can be called by a button, a link or other HTML elements at onClick (if 'a' element onClick is used must be followed by 'return false;' to avoid fire page refresh.
@fires: open a Modal Box or a PopUp Window
@param: {String} strUrl The URL link to be opened in a new browser child window target or modal iframe (modalbox)
@param: {String} strTarget The child window target to post the form to ; name ; do not use _self or _blank here, and try ensure a compliant name
@param: {Integer} windowWidth *Optional* the width of the new Modal/PopUp child window if new window target is used ; if not set the default width will be used
@param: {Integer} windowHeight *Optional* the height of the new Modal/PopUp child window if new window target is used ; if not set the default height will be used
@param: {Enum} forcePopUp *Optional* if a new target window is required, 0 = default, use modal/iFrame if set by smartJ$Browser.param_ModalBoxActive, 1 = force PopUp ; -1 force modal/iFrame
@param: {Enum} forceDims *Optional* if set to 1 will try force uwing the width/height set for the new modal/iFrame or PopUp
@param: {Enum} handlerMode *Optional* If explicit set to 1 or 2 will use only a simple modal/popup without binding to the parent window ; if set to 2, the popup will not use redirect handler in addition to no binding ; if set to -1 the popup will not use redirect handler, but will use binding ; if set to -2 (default) will use same domain detection
Open a Modal/iFrame or PopUp child window with a new target to open a URL link within.
public static function getCookie ( {String} name ) {} . {String}
@return: {String} The cookie Value
@param: {String} name The cookie Name ; must be a valid cookie name
Get a Cookie from Browser by Name and return it's Value
public static function setCookie ( {String} name, {String} value, {Numeric} expire, {String} path, {String} domain, {Enum} samesite, {Boolean} secure ) {} . {Boolean}
@return: {Boolean} TRUE on success and FALSE on failure
@param: {String} name The cookie Name
@param: {String} value The cookie Value
@param: {Numeric} expire *Optional* The cookie expire time in seconds since now ; if set to zero will expire by session ; if set to -1 will be unset (deleted) ; if set to NULL will use the value from smartJ$Browser.param_CookieLifeTime ; default is 0
@param: {String} path *Optional* The cookie path (default is /)
@param: {String} domain *Optional* The cookie domain (default is @ and will use '@' to use the smartJ$Browser.param_CookieDomain)
@param: {Enum} samesite *Optional* The SameSite cookie policy ; Can be: None, Lax, Strict or Empty ; (default is @ and will use '@' to use the smartJ$Browser.param_CookieSameSitePolicy: Lax)
@param: {Boolean} secure *Optional* Force Cookie Secure Mode (default is FALSE)
Set a Cookie in Browser by Name and Value
public static deleteCookie = ( {String} name, {String} path, {String} domain, {Enum} samesite, {Boolean} secure ) => {} . {Boolean}
@return: {Boolean} TRUE on success and FALSE on failure
@param: {String} name The cookie Name
@param: {String} path *Optional* The cookie path (default is /)
@param: {String} domain *Optional* The cookie domain (default is @ and will use '@' to use the smartJ$Browser.param_CookieDomain)
@param: {Enum} samesite *Optional* The SameSite cookie policy ; Can be: None, Lax, Strict ; (default is @ and will use '@' to use the smartJ$Browser.param_CookieSameSitePolicy)
@param: {Boolean} secure *Optional* Force Cookie Secure Mode (default is FALSE)
Delete a Cookie from Browser by Name
public static function TextAreaAddLimit ( {String} elemID, {Integer+} maxChars ) {} . {Void}
@fires: limits the text area for input more than max allowed characters
@listens: typing text in a text area, paste or other input methods
@param: {String} elemID The TextArea field name
@param: {Integer+} maxChars The max limit of characters to accept in the TextArea
Force a text limit on a TextArea (will also attach a CounterField)
public static function catchKeyENTER ( {Event} evt ) {} . {Void}
@hint: Usage: onKeyDown ="smartJ$Browser.catchKeyENTER(event);"
@fires: Catch and Disable use of ENTER key in a field
@listens: ENTER Key press event
@param: {Event} evt The EVENT Object Reference
Catch ENTER Key in an Input[type=text] or other compatible input field

    Sample code: JavaScript
     <input type="text" onKeyDown="smartJ$Browser.catchKeyENTER(event);">

public static function catchKeyTAB ( {Event} evt ) {} . {Void}
@hint: Usage: onKeyDown ="smartJ$Browser.catchKeyTAB(event);"
@fires: Insert a real TAB character in the selected input
@listens: TAB Key press event
@param: {Event} evt The EVENT Object Reference
Catch TAB Key and insert a TAB character (\t) at the cursor instead to switch to next input field as default in html
It works on TextArea or other compatible input fields ...

    Sample code: JavaScript
     <textarea id="txt" onKeyDown="smartJ$Browser.catchKeyTAB(event);">

public static function CheckAllCheckBoxes ( {String} y_form_name, {String} y_element_id, {Boolean} y_element_checked ) {} . {Void}
@fires: check/uncheck all the checkboxes inside a form
@param: {String} y_form_name The form name (if empty string will operate on all checkboxes in the page otherwise just inside the form)
@param: {String} y_element_id The checkboxes element ID
@param: {Boolean} y_element_checked If TRUE will do check ; If FALSE will do uncheck ; otherwise will just inverse check
Check or Uncheck all checkboxes in a form element
public static function CloneElement ( {String} elID, {String} containerID, {Enum} elType, {Integer} maxLimit ) {} . {Void}
@param: {String} elID The element ID to be cloned
@param: {String} containerID The destination container ID
@param: {Enum} elType The type of the element to be cloned: text-input ; text-area ; file-input ; html-element
@param: {Integer} maxLimit The max limit number of elements includding the element itself and the cloned elements: between 1 and 255
Clone a HTML Element

    Sample code: JavaScript
     <div id="multifile_list" style="text-align:left; max-width:550px;">
     		<input id="multifile_uploader" type="file" name="myvar[]" style="width:90%;">
     </div>
     <script>
     		smartJ$Browser.CloneElement('multifile_uploader', 'multifile_list', 'file-input', 10);
     </script>

public static function SerializeFormAsObject ( {String} formID, {String} rKey ) {} . {Object}
@return: {Object} Serialized data: ex: { "#":{ "levels": 2, "keys":6, "size":11}, "data":{...} }
@param: {String} formID The element ID of the Form to be serialized
@param: {String} rKey The object root key ; Optional ; if not specified will be set as 'data' ; '#' is the object metainfo
Serialize Form as Object
public static function SubmitFormByAjax ( {String} the_form_id, {String} url, {Yes/No} growl, {JS-Code} evcode, {JS-Code} everrcode, {JS-Code} evfailcode, {Boolean} failalertable ) {} . {Void}
@hint: It supports simple forms or complex forms with multipart/form-data and file attachments.
@fires: send a form by ajax
@listens: fire a form submit
@param: {String} the_form_id The form ID ; Set it to FALSE/NULL/'' (to use without a real form by emulating a form like XHR request from URL)
@param: {String} url The destination URL where form or XHR request will be sent to
@param: {Yes/No} growl *Optional* If 'yes' will use the Growl notifications otherwise (if 'no') will use Dialog notifications ; default is set to 'auto'
@param: {JS-Code} evcode *Optional* the JS Code to execute on SUCCESS answer (before anything else) ; params: the_form_id, url, msg
@param: {JS-Code} everrcode *Optional* the JS Code to execute on ERROR answer (before anything else) ; params: the_form_id, url, msg
@param: {JS-Code} evfailcode *Optional* the JS Code to execute on REQUEST FAIL answer ; params: the_form_id, url, msg
@param: {Boolean} failalertable *Optional* if set to TRUE will set the fail dialog to 'alertable' instead of 'auto' if alertable is available
Submit a Form by Ajax via POST and Handle the Answer
The function expects a json answer with the following structure: see more in framework PHP lib SmartComponents::js_ajax_replyto_html_form()

    Sample code: JavaScript
     // Json Structure for Answer
     		{
     			'completed': 	'DONE',
     			'status': 		'OK|ERROR',
     			'action': 		'Notification Button Text: Ok/Cancel',
     			'title': 		'Notification Title',
     			'message': 		'Notification Message HTML Content', // if empty, on success will not show any notification
     			'js_evcode': 	'If non-empty, the JS Code to execute on either SUCCESS or ERROR (before redirect or Div Replace) ; params: the_form_id, url, msg'
     			'redirect': 	'If non-empty, a redirect URL on either SUCCESS or ERROR ; on SUCCESS if message is Empty will redirect without confirmation: Growl / Dialog',
     			'replace_div': 	'If non-empty, an ID for a div to be replaced with content from [replace_html] on Success',
     			'replace_html': 'If non-empty, a HTML code to populate / replace the current Content for the [replace_div] on Success'
     		}
     // #END Json Structure

public static function AjaxRequestByForm ( {String} the_form_id, {String} url, {Enum} data_type ) {} . {Object}
@return: {Object} The Ajax XHR Request Object ; The following methods must be bind to the object and redefined:
@param: {String} the_form_id The element ID of the form to be create the Ajax XHR Request for
@param: {String} url The URL to send form to via POST
@param: {Enum} data_type The type of Data served back by the Request: json | html | text
Create an Ajax XHR Request (POST) by Form
It supports simple forms or complex forms with multipart/form-data and file attachments.

    Sample code: JavaScript
     let ajax = smartJ$Browser.AjaxRequestByForm('my-form', 'http(s);//url-to', 'json')
     		.done: 		function(msg) {}
     		.fail: 		function(msg) {}
     		.always: 	function(msg) {}

public static function AjaxRequestFromURL ( {String} y_url, {Enum} y_method, {Enum} y_data_type, {Mixed} y_data_arr_or_serialized, {String} y_AuthUser, {String} y_AuthPass, {Object} y_Headers, {Boolean} y_withCredentials, {Boolean} y_crossDomain ) {} . {Object}
@hint: It is NOT intended to be used with HTML forms that may contain multipart/form-data and file attachments or not.
@return: {Object} The Ajax XHR Request Object ; The following methods must be bind to the object and redefined:
@param: {String} y_url The URL to send the Request to
@param: {Enum} y_method The Request Method: HEAD / GET / POST / PUT / DELETE / OPTIONS / HEAD
@param: {Enum} y_data_type The type of Data served back by the Request: json | jsonp | script | html | xml | text
@param: {Mixed} y_data_arr_or_serialized The Data to be sent: a serialized string via serialize() such as: '&var1=value1&var2=value2' or an associative array (Object) as: { var1: "value1", var2: "value2" }
@param: {String} y_AuthUser *Optional* The Authentication UserName (if custom Authentication need to be used) ; set to FALSE to avoid accidental auto-send, if unused, for CORS or 3rd party domains (security !)
@param: {String} y_AuthPass *Optional* The Authentication Password (if custom Authentication need to be used) ; set to FALSE to avoid accidental auto-send, if unused, for CORS or 3rd party domains (security !)
@param: {Object} y_Headers *Optional* Extra Headers to be sent with the Request ; Default is NULL (ex: { 'X-Head1': 'Test1', ... })
@param: {Boolean} y_withCredentials *Optional* Send Credentials over CORS ; default is FALSE ; set to TRUE to send XHR Credentials ; !!! Never set this when URL is a 3rd party domain to avoid leak credentials ; this can be set to TRUE just when exchanging requests between different sub-domains of the same domain !
@param: {Boolean} y_crossDomain *Optional* when set to TRUE will handle a CROSS Domain Request (y_withCredentials is forced to FALSE in this context) ; default is FALSE
Create a general purpose Ajax XHR Request (GET/POST) with Optional support for Authentication and Extra Headers
For creating an Ajax XHR Request to be used with HTML Forms use:
smartJ$Browser.AjaxRequestByForm(); // basic, will detect the form type if must use multipart/form-data + attachments (if any)
or even much better use:
smartJ$Browser.SubmitFormByAjax(); // advanced, will handle the XHR form request and the answer

    Sample code: JavaScript
     let ajax = smartJ$Browser.AjaxRequestFromURL('http(s);//url', 'POST', 'json', '&var1=value1&var2=value2')
     		.done: 		function(msg) {}
     		.fail: 		function(msg) {}
     		.always: 	function(msg) {}

public static function LoadElementContentByAjax ( {String} y_elemID, {String} y_img_loader, {String} y_url, {Enum} y_method, {Enum} y_data_type, {Mixed} y_data_arr_or_serialized, {Boolean} y_replace, {Mixed} y_notifyerr ) {} . {Void}
@hint: It is intended to simplify populating a Div (or other compatible) HTML Element(s) with content(s) by Ajax Requests.
@fires: load the div content by ajax in the background and if successful will replace the div content with what comes by ajax
@param: {String} y_elemID The ID of the Div (or other compatible) HTML Element(s) to bind to
@param: {String} y_img_loader If non-empty, a pre-loader image that will be displayed while loading ; if set to TRUE will use smartJ$Browser.param_LoaderImg;
@param: {String} y_url The URL to send the Request to
@param: {Enum} y_method The Request Method: GET / POST
@param: {Enum} y_data_type The type of Data served back by the Request: html | text | json (div_content_html)
@param: {Mixed} y_data_arr_or_serialized The Data to be sent: a serialized string via serialize() such as: '&var1=value1&var2=value2' or an associative array as: { var1: "value1", var2: "value2" }
@param: {Boolean} y_replace *Optional* Default is FALSE ; If set to TRUE will use the jQuery method .replaceWith() instead of .empty().html()
@param: {Mixed} y_notifyerr *Optional* Default is NULL ; If set to TRUE or FALSE will override the general setting for notification error ; if TRUE on Error loading the content will display a message Dialog instead of logging the errros to console
Loads the contents for a Div (or other compatible) HTML Element(s) by Ajax using a GET / POST Ajax Request
public static windwScrollDown = ( {Object} wnd, {Integer} offset ) => {} . {Void}
@fires: Scroll Down a Browser window
@param: {Object} wnd The window (reference) object
@param: {Integer} offset The offset in pixels to scroll down ; use -1 to scroll to the end of document
Scroll down a browser window by reference.
It will focus the referenced browser window first.
public static function WayPoint ( {String} elSelector, {JS-Code} evcode ) {} . {Void}
@hint: It may be used to make an infinite scroll behaviour to load more content on page when page reach the bottom end
@fires: trigger the function that is set (2nd param)
@listens: the target element (1st param) to be scrolled in the visible area
@param: {String} elSelector The Element Selector ; example: '#elem-id' or '.elem-class' (interpretable by jQuery)
@param: {JS-Code} evcode the JS Code to execute on complete
Trigger a function when you scroll the page to a specific target element
public static copyToClipboard = ( {String} elId ) => {} . {String}
@return: {String} Error or Empty String
@fires: copy text element by using ranges
@param: {String} elId The element ID
Copy Element Text Content to ClipBoard
public static function VirtualFileDownload ( {String} data, {String} fileName, {String} mimeType, {String} charset, {Boolean} isBinary ) {} . {Void}
@fires: emulates a file download
@param: {String} data The content of the file to be downloaded
@param: {String} fileName The file name (ex: 'file.txt')
@param: {String} mimeType The mime type (ex: 'text/plain')
@param: {String} charset *Optional* ; Charset ; Default is NULL, will use the value from param_Charset or if not set will use 'UTF-8' ; set it to FALSE if binary is set to TRUE ; The character set of the file content (ex: 'UTF-8' for text OR FALSE for binary ASCII)
@param: {Boolean} isBinary *Optional* ; Encoding Charset 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
Create a virtual file download from Javascript
public static function VirtualImageUploadHandler ( {String} inputUpldFileId, {String} previewPlaceholderId, {Decimal} imgQuality, {Decimal} imgMaxResizeMBSize, {Integer} imgMaxResizeW, {Integer} imgMaxResizeH, {CallBack} fxDone, {Boolean} clearPreview, {Integer} widthPreview, {Integer} heightPreview, {Boolean} preserveGifs ) {} . {Void}
@param: {String} inputUpldFileId The HTML-Id of the input type file (#1)
@param: {String} previewPlaceholderId The HTML-Id of the preview container (#2)
@param: {Decimal} imgQuality The image quality (0.1 ... 1)
@param: {Decimal} imgMaxResizeMBSize The max resized image size in MB (0.01 ... 2) ; Default is 0.1
@param: {Integer} imgMaxResizeW The max resize width of the image (if the image width is lower will be not resized)
@param: {Integer} imgMaxResizeH The max resize height of the image (if the image height is lower will be not resized)
@param: {CallBack} fxDone A callback function(imgDataURL, w, h, isSVG, type, size, name) { ... } for done
@param: {Boolean} clearPreview If FALSE will not clear the preview container after done; Default is TRUE
@param: {Integer} widthPreview The Preview Width to set if not clearing the preview ; if not defined, full resized image width will be used (imgMaxResizeW)
@param: {Integer} heightPreview The Preview Height to set if not clearing the preview ; if not defined, full resized image height will be used (imgMaxResizeH)
@param: {Boolean} preserveGifs If TRUE will not process GIFS (which will be converted to PNG if processed via canvas) ; it may be used to avoid break animated Gifs
Create a virtual image upload handler
Requires in HTML:
(#1) an input type file (can be any of visible or hidden/triggered by a button click)
(#2) an image preview container (div)

## class Properties

public static var param_LanguageId = 'en' ; . {String}
set [before] smartJ$Options .BrowserUtils.LanguageId
get smartJ$Browser.param_LanguageId
Default Language ID (must be set as in PHP, see the SMART_FRAMEWORK_DEFAULT_LANG)
public static var param_Charset = 'UTF-8' ; . {String}
set [before] smartJ$Options .BrowserUtils.Charset
get smartJ$Browser.param_Charset
Character Set (must be set as in PHP, see the SMART_FRAMEWORK_CHARSET)
public static var param_CookieLifeTime = 0 ; . {Integer}
set [before] smartJ$Options .BrowserUtils.CookieLifeTime
get smartJ$Browser.param_CookieLifeTime
Cookie Domain (must be set as in PHP, see the SMART_FRAMEWORK_UNIQUE_ID_COOKIE_LIFETIME)
public static var param_CookieDomain = '' ; . {String}
set [before] smartJ$Options .BrowserUtils.CookieDomain
get smartJ$Browser.param_CookieDomain
Cookie Domain (must be set as in PHP, see the SMART_FRAMEWORK_UNIQUE_ID_COOKIE_DOMAIN)
public static var param_CookieSameSitePolicy = 'Lax' ; . {String}
set [before] smartJ$Options .BrowserUtils.CookieSameSitePolicy
get smartJ$Browser.param_CookieSameSitePolicy
Cookie SameSite Policy (must be set as in PHP, see the SMART_FRAMEWORK_UNIQUE_ID_COOKIE_SAMESITE) ; To avoid set a policy, use 'Empty'
public static var param_Notifications = 'growl' ; . {String}
set [before] smartJ$Options .BrowserUtils.Notifications
get smartJ$Browser.param_Notifications
Notification Mode
Allowed Values: 'growl' | 'dialog'
public static var param_NotificationDialogType = 'auto' ; . {String}
set [before] smartJ$Options .BrowserUtils.NotificationDialogType
get smartJ$Browser.param_NotificationDialogType
Growl Notification Dialog Type
Allowed Values: 'auto' | 'alertable' | 'ui' | 'native' ; auto=autoselect (reverse order, starting from ui to 'native' with fallback) ; native = browser:alert/prompt ; alertable = use jQuery.alertable ; ui = use smartJ$UI
public static var param_NotificationGrowlType = 'auto' ; . {String}
set [before] smartJ$Options .BrowserUtils.NotificationGrowlType
get smartJ$Browser.param_NotificationGrowlType
Growl Notification Growl Type
Allowed Values: 'auto' | 'toastr' | 'ui' ; If Explicit set on 'ui' and UI is n/a will fallback to alert ; If Explicit set on 'toastr' ; ui = use smartJ$UI ; if any is n/a will fallback to browser:alert
public static var param_NotificationTimeOK = 1000 ; . {Integer}
set [before] smartJ$Options .BrowserUtils.NotificationTimeOK
get smartJ$Browser.param_NotificationTimeOK
Growl Notification Time when OK (in microseconds)
public static var param_NotificationTimeERR = 3500 ; . {Integer}
set [before] smartJ$Options .BrowserUtils.NotificationTimeERR
get smartJ$Browser.param_NotificationTimeERR
Growl Notification Time when ERR (in microseconds)
public static var param_NotifyLoadError = false ; . {Boolean}
set [before] smartJ$Options .BrowserUtils.NotifyLoadError
get smartJ$Browser.param_NotifyLoadError
Errors Notification Mode
If set to FALSE will not raise notifications on errors but only will log them
Allowed Values: true | false
public static var param_ModalBoxActive = 1 ; . {Boolean}
set [before] smartJ$Options .BrowserUtils.ModalBoxActive
get smartJ$Browser.param_ModalBoxActive
Use ModalBox
If set to 0 will disable the modal iframe ; If set to 1 (as default) will use ModalBox except on mobiles ; If set to 2 will use ModalBox also on mobiles
Allowed Values: 2=true (includding mobile) | 1=true (except on mobile) | 0=false
public static var param_ModalBoxNoCascade = true ; . {Boolean}
set [before] smartJ$Options .BrowserUtils.ModalBoxNoCascade
get smartJ$Browser.param_ModalBoxNoCascade
Enable or Disable the ModalBox Cascading
If set to FALSE will enable the ModalBox (iframe) cascading (inefficient) ; otherwise will use PopUp every next level starting from the ModalBox iframe level, but inside PopUp can open another ModalBox ... and so on
Allowed Values: true | false
public static var param_ModalBoxProtected = false ; . {Boolean}
set [before] smartJ$Options .BrowserUtils.ModalBoxProtected
get smartJ$Browser.param_ModalBoxProtected
Set ModalBox protected mode (if used)
If set to TRUE will use the protected mode for the modal iFrame (can be closed just explicit by buttons, not clicking outside of it)
Allowed Values: true | false
public static var param_Prefix = '' ; . {String}
set [before] smartJ$Options .BrowserUtils.Prefix
get smartJ$Browser.param_Prefix
Prefix, for the below Loaders, Images, Icons
public static var param_LoaderImg = 'lib/js/framework/img/loading.svg' ; . {String}
set [before] smartJ$Options .BrowserUtils.LoaderImg
get smartJ$Browser.param_LoaderImg
Loader Image used to display in various contexts when loading ...
public static var param_ImgOK = 'lib/framework/img/sign-ok.svg' ; . {String}
set [before] smartJ$Options .BrowserUtils.ImgOK
get smartJ$Browser.param_ImgOK
OK sign image, used in various contexts
public static var param_ImgNotOK = 'lib/framework/img/sign-warn.svg' ; . {String}
set [before] smartJ$Options .BrowserUtils.ImgNotOK
get smartJ$Browser.param_ImgNotOK
Not OK sign image, used in various contexts
public static var param_CssOverlayBgColor = '#FFFFFF' ; . {String}
set [before] smartJ$Options .BrowserUtils.CssOverlayBgColor
get smartJ$Browser.param_CssOverlayBgColor
Overlay Customization - Background Color
Allowed Values: hexa color between #000000 - #FFFFFF
public static var param_CssOverlayOpacity = 0.85 ; . {Decimal}
set [before] smartJ$Options .BrowserUtils.CssOverlayOpacity
get smartJ$Browser.param_CssOverlayOpacity
Overlay Customization - Opacity
Allowed Values: between 0.1 and 1

## class Constants

documentation generated on: 2024-12-16 17:00:46 +0000

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