# static class smartJ$UI
{ } .

CLASS :: UIUtils # SimpleUI :: (ES6)
The class is a standalone implementation of the UI components (Javascript) in Smart.Framework
An alternate implementation 100% compatible is provided using jQueryUI and can be loaded by loading from Smart.Framework.Modules: modules/mod-ui-jqueryui/toolkit/jquery.smartframework.ui.js
The JavaScript class provides methods to simplify implementation of several basic UI components.

- Language: Javascript
- Located at: lib/js/framework/smart-framework.pak.js; jquery.smartframework.ui.js
- Package: Sf.Javascript:UI
- Class Name: smartJ$UI
- Frozen: Yes
- Version: 20230123
- Usage: smartJ$UI.method();
- Depends: jQuery, smartJ$Utils, smartJ$Date, smartJ$Browser, jQuery.gritter/jQuery.toastr, SmartSimpleDialog, SmartSimpleTabs, SmartAutoSuggest, jQuery.ListSelect, jQuery.DatePicker, jQuery.TimePicker, jQuery.DataTable

## class Methods

public static function GrowlAdd ( {String} title, {String} text, {String} image, {Integer} time, {Boolean} sticky, {Enum} css_class, {Array-Obj} options ) {} . {Boolean}
@return: {Boolean} TRUE if Success FALSE if Fail
@param: {String} title a title for the notification (HTML) ; 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:
@requires: jQuery
@requires: jQuery.gritter/jQuery.toastr
Create a Message Growl Notification
{ // example of extra Options
before_open: () => {},
after_open: () => {},
before_close: () => {},
after_close: () => {}
}
public static function GrowlRemove ( ) {} . {Boolean}
@return: {Boolean} TRUE if Success FALSE if Fail
@requires: jQuery
@requires: jQuery.gritter/jQuery.toastr
Remove all Growl Notifications from the current browser window (page)
public static function ToolTip ( {String} selector ) {} . {Object}
@return: {Object} :: The jQuery HTML Element
@param: {String} selector :: The jQuery element selector ; Ex: '.class' or '#id'
@requires: jQuery
@requires: jquery.tiptop.css
@requires: jquery.tiptop.js
Display a Tooltip ; UI Component
public static function DialogAlert ( {String} y_message_html, {Function} evcode, {String} y_title, {Integer+} y_width, {Integer+} y_height ) {} . {Object}
@return: {Object} :: The jQuery HTML Element
@param: {String} y_message_html :: Message to Display, HTML
@param: {Function} evcode :: The code to execute on press OK: () => {} or null
@param: {String} y_title :: The Title of Dialog, TEXT
@param: {Integer+} y_width :: The Dialog Width, *Optional*, Default: 550 (px)
@param: {Integer+} y_height :: The Dialog Height, *Optional*, Default: 250 (px)
@requires: jQuery
@requires: dialog/simple-dialog.css
@requires: dialog/simple-dialog.js
Display an Alert Dialog, with 1 button: OK ; UI Component
public static function DialogConfirm ( {String} y_question_html, {Function} evcode, {String} y_title, {Integer+} y_width, {Integer+} y_height ) {} . {Object}
@return: {Object} :: The jQuery HTML Element
@param: {String} y_question_html :: Message (Question) to Display, HTML
@param: {Function} evcode :: The code to execute on press OK: () => {} or null
@param: {String} y_title :: The Title of Dialog, TEXT
@param: {Integer+} y_width :: The Dialog Width, *Optional*, Default: 550 (px)
@param: {Integer+} y_height :: The Dialog Height, *Optional*, Default: 250 (px)
@requires: jQuery
@requires: dialog/simple-dialog.css
@requires: dialog/simple-dialog.js
Display a Confirm Dialog, with 2 buttons: OK and Cancel ; UI Component
public static function SelectList ( {String} elemID, {Integer+} dimW, {Integer+} dimH, {Boolean} isMulti, {Boolean} useFilter ) {} . {Object}
@hint: onChange handler is taken from onBlur html attribute of the element the component binds to ; can be: (elemID) => {} or null
@return: {Object} :: The jQuery HTML Element
@param: {String} elemID :: The HTML Element ID to bind to (ussualy a real list single or multi)
@param: {Integer+} dimW :: The element Width (can be overriden with a CSS style !important)
@param: {Integer+} dimH :: The element Height (can be overriden with a CSS style !important)
@param: {Boolean} isMulti :: If the list is multi (TRUE) or single (FALSE)
@param: {Boolean} useFilter :: If TRUE will display a search filter list
@requires: jQuery
@requires: smartJ$Utils
@requires: listselect/css/chosen.css
@requires: listselect/chosen.jquery.js
Display a Single or Multi Select List ; UI Component
public static function DatePickerInit ( {String} elemID, {String} dateFmt, {String} selDate, {Integer+} calStart, {Mixed} calMinDate, {Mixed} calMaxDate, {Integer+} noOfMonths, {Function} evcode ) {} . {Object}
@return: {Object} :: The jQuery HTML Date Picker
@param: {String} elemID :: The HTML Element ID to bind to (ussualy a text input)
@param: {String} dateFmt :: Calendar Date Format, used to display only ; Ex: 'dd.mm.yy'
@param: {String} selDate :: Calendar selected date, ISO format as yyyy-mm-dd or empty string
@param: {Integer+} calStart :: Calendar first day of week (0..6) ; 0 = Sunday, 1 = Monday ...
@param: {Mixed} calMinDate :: Calendar min date to display and allow selection ; Ex Object: new Date(1937, 1 - 1, 1) ; Ex String: '-1y -1m -1d'
@param: {Mixed} calMaxDate :: Calendar max date to display and allow selection ; Ex Object: new Date(2037, 12 - 1, 31) ; Ex String: '1y 1m 1d'
@param: {Integer+} noOfMonths :: Calendar number of months to display ; Default is 1
@param: {Function} evcode :: The code to execute on select: (date, altdate, inst, elemID) => {} or null
@requires: jQuery
@requires: datepicker/css/datepicker.css
@requires: datepicker/datepicker.js
Initialize a Date Picker ; UI Component
The selected date will be in ISO format as yyyy-mm-dd
public static function DatePickerDisplay ( {String} datepicker_id ) {} . {Object}
@return: {Object} :: The jQuery HTML Date Picker
@param: {String} datepicker_id :: The HTML Element ID to bind to (ussualy a text input) ; must be previous initialized with smartJ$UI.DatePickerInit()
@requires: jQuery
@requires: datepicker/css/datepicker.css
@requires: datepicker/datepicker.js
Handle Display for an already Initialized Date Picker ; UI Component
The selected date will be in ISO format as yyyy-mm-dd

    Sample code: JavaScript
     let selectedDate = ''; // or can be yyyy-mm-dd
     let elemID = 'myDatePicker';
     let html = '
     <span id="date-area-' + myDatePicker + '">
       <input type="hidden" id="' + myDatePicker + '" name="date" value="' + selectedDate + '"><!-- holds the ISO formatted date -->
       <input type="text" id="date-entry-' + myDatePicker + '" name="dtfmt__date" maxlength="13" value="' + selectedDate + '" readonly="readonly" class="datetime_Field_DatePicker" autocomplete="off"><!-- holds the custom formatted date -->
     </span>
     ';
     $('body').append(html);
     smartJ$UI.DatePickerInit(elemID, 'dd.mm.yy', '', 1, '-1y -1m -1d', '1y 1m 1d', 1); // initialize the date picker
     $('#date-entry-' + elemID).on('click', (e) => { smartJ$UI.DatePickerDisplay(elemID); })}); // show date picker on click over text input
     $('#date-entry-' + elemID).on('dblclick doubletap', (e) => { $('#' + elemID).val(''); $('#date-entry-' + elemID).val(''); }); // reset on double click the text input

public static function TimePickerInit ( {String} elemID, {Integer+} hStart, {Integer+} hEnd, {Integer+} mStart, {Integer+} mEnd, {Integer+} mInterval, {Integer+} tmRows, {Function} evcode ) {} . {Object}
@return: {Object} :: The jQuery HTML Time Picker
@param: {String} elemID :: The HTML Element ID to bind to (ussualy a text input)
@param: {Integer+} hStart :: Time Start Hour ; 0..22
@param: {Integer+} hEnd :: Time End Hour ; 1..23
@param: {Integer+} mStart :: Time Start Minute ; 0..58
@param: {Integer+} mEnd :: Time End Minute ; 1..59
@param: {Integer+} mInterval :: Time Interval in Minutes ; 1..30
@param: {Integer+} tmRows :: Time Table Rows ; 1..5 ; Default is 2
@param: {Function} evcode :: The code to execute on select: (time, inst, elemID) => {} or null
@requires: jQuery
@requires: timepicker/css/jquery.timepicker.css
@requires: timepicker/jquery.timepicker.js
Initialize a Time Picker ; UI Component
The selected time will be in ISO format as hh:ii
The selected value will be get directly from the `value` attribute of the html element is binded to <input id="MyTimePicker" type="text" value="12:30"> element
public static function TimePickerDisplay ( {String} timepicker_id ) {} . {Object}
@return: {Object} :: The jQuery HTML Time Picker
@param: {String} timepicker_id :: The HTML Element ID to bind to (ussualy a text input) ; must be previous initialized with smartJ$UI.TimePickerInit()
@requires: jQuery
@requires: timepicker/css/jquery.timepicker.css
@requires: timepicker/jquery.timepicker.js
Handle Display for an already Initialized Time Picker ; UI Component
The selected time will be in ISO format as hh:ii

    Sample code: JavaScript
     let selectedTime = ''; // or can be hh:ii
     let elemID = 'myTimePicker';
     let html = '
     <span id="time-area-' + elemID + '" title="[###TEXT-SELECT|html###] [HH:ii]">
       <input type="text" name="time" id="' + elemID + '" maxlength="5" value="' + selectedTime + '" readonly="readonly" class="datetime_Field_TimePicker" autocomplete="off">
     </span>
     ';
     $('body').append(html);
     smartJ$UI.TimePickerInit(elemID, 0, 23, 0, 59, 5, 2); // initialize the time picker
     $('#' + elemID).on('click', (e) => { smartJ$UI.TimePickerDisplay(elemID); })}); // show time picker on click over text input
     $('#' + elemID).on('dblclick doubletap', (e) => { $('#' + elemID).val(''); }); // reset on double click the text input

public static function TabsInit ( {String} tabs_id, {Integer+} tab_selected, {Boolean} prevent_reload ) {} . {Object}
@return: {Object} :: The jQuery HTML Element
@param: {String} tabs_id :: The HTML Element ID to bind to
@param: {Integer+} tab_selected :: The selected tab number ; Default is zero
@param: {Boolean} prevent_reload :: *Optional* ; Default is TRUE ; If TRUE the tab content will not be reloaded after the first load
@requires: jQuery
@requires: tabs/jquery.tabs.css
@requires: tabs/jquery.tabs.js
Initialize Tabs Component ; UI Component
The content of each tab (from the tabs component) can be loaded async by Ajax when the Tab is selected for display

    Sample code: JavaScript
     let tabs = '
     <div id="tabs_draw">
       <div id="tabs_nav">
         <li><a href="#tab-in-page">Tab with Content Preset</a></li>
         <li><a href="?content=external-tab-content-load-by-ajax">Tab which loads contents by Ajax</a></li>
       </div>
       <div id="tab-in-page">
         <h1>The content of the first tab ...</h1>
       </div>
       <!-- second tab does not to be set in HTML, will be created on the fly by the tabs component and populated with the HTML contents that comes by Ajax from a GET request on (example): ?content=external-tab-content-load-by-ajax -->
     </div>
     ';
     $('body').append(html);
     smartJ$UI.TabsInit('tabs_draw');

public static function TabsActivate ( {String} tabs_id, {Boolean} activation ) {} . {Object}
@return: {Object} :: The jQuery HTML Element
@param: {String} tabs_id :: The HTML Element ID to bind to ; must be previous initialized with smartJ$UI.TabsInit()
@param: {Boolean} activation :: If FALSE the Tabs component will become inactive, except the current selected Tab ; when set back to TRUE will re-activate all tabs
@requires: jQuery
@requires: tabs/jquery.tabs.css
@requires: tabs/jquery.tabs.js
Activate or Deactivate the Tabs Component ; UI Component
By default all the Tabs are active ; Use the function to deactivate and perhaps activate again
When deactivated, only the current selected tab can be used
It can be useful for using by example with edit operations to prevent switch tabs before saving the current form from the current active Tab

    Sample code: JavaScript
     smartJ$UI.TabsActivate(false); // deactivate tabs
     smartJ$UI.TabsActivate(true); // re-activate tabs

public static function AutoCompleteField ( {Enum} single_or_multi, {String} elem_id, {String} data_url, {String} param_src, {Integer+} min_term_len, {Function} evcode ) {} . {Object}
@return: {Object} :: The jQuery HTML Element
@param: {Enum} single_or_multi :: Type: can be: 'single' or 'multilist'
@param: {String} elem_id :: The HTML Element ID to bind to ; must be a text input or a text area
@param: {String} data_url :: The Data URL Prefix ; Ex: '?op=list&type=autosuggest'
@param: {String} param_src :: The Data URL Parameter to be appended as suffix to the above Data URL ; Ex: 'searchTerm' (will use: '?op=list&type=autosuggest&searchTerm=')
@param: {Integer+} min_term_len :: The minimum term search length ; expects a value between 0..255 ; will start searching only after the typed term length matches the value
@param: {Function} evcode :: The code to execute on select: (id, value, label, data) => {} or null
@requires: jQuery
@requires: autosuggest/smart-suggest.css
@requires: autosuggest/smart-suggest.js
Creates a Single-Value or Multi-Value AutoComplete (AutoSuggest) Field ; UI Component

    Sample code: JavaScript
     // the expected JSON structure that have to be served via the DataURL + ParamSrc
     [
     		{ "id":"id1", "value":"Value1","label":"Label1" },
     		{ "id":"id2", "value":"Value2","label":"Label2" },
     		// ...
     		{ "id":"idN", "value":"ValueN","label":"LabelN" },
     ]
     // the DataURL + ParamSrc controller must take care to return the values filetered by the value sent from the field via ParamSrc via HTTP GET

public static function DataTableInit ( {String} elem_id, {Object} options ) {} . {Object}
@hint: Add advanced interaction controls to HTML tables
@return: {Object} :: The jQuery HTML Element
@param: {String} elem_id :: The HTML Element ID to bind to ; must be a HTML <table></table>
@param: {Object} options :: The Options for DataTable
@requires: jQuery
@requires: datatables/datatables-responsive.css
@requires: datatables/datatables-responsive.js
@requires: datatables/smart-datatables.js
Creates a DataTable from a regular HTML Table ; UI Component
DataTables is a table enhancing plug-in for the jQuery Javascript library,
adding sorting, paging and filtering abilities to plain HTML tables.

    Sample code: JavaScript
     // <!-- transform the following table into a DataTable with filtering, pagination, column ordering and many other features -->
     //<table id="myTable">
     // <thead>
     // 	<tr>
     // 		<th>Col1</th>
     // 		<th>Col2</th>
     // 	</tr>
     // </thead>
     // <tbody>
     // 	<tr>
     // 		<td>Col1</td>
     // 		<td>Col2</td>
     // 	</tr>
     // </tbody>
     // <tfoot>
     // 	<tr>
     // 		<th>Col1</th>
     // 		<th>Col2</th>
     // 	</tr>
     // </tfoot>
     //</table>
     //--
     smartJ$UI.DataTableInit('myTable', {
     		responsive: false, // if TRUE on responsive mode columns may become fluid on small screens
    		filter: true,
    		sort: true,
    		paginate: true,
     		pagesize: 10,
     		pagesizes: [ 10, 25, 50, 100 ],
     		classField: 'ux-field', // css classes to display input fields (ex: filter)
     		classButton: 'ux-button ux-button-small', // css classes to display the buttons
     		classActiveButton: 'ux-button-primary', // css classes to display the active buttons
    		colorder: [
    			[ 0, 'asc' ], // [ 1, 'desc' ]
    		],
    		coldefs: [
    			{ // column one
    				targets: 0,
    				width: '25px',
     				render: (data, type, row) => {
     					if(type === 'type' || type === 'sort' || type === 'filter') { // preserve special objects from column render
     						return data;
     					} else { // customize the appearance of the 1st column
     						return '<span style="color:#CCCCCC;">' + smartJ$Utils.escape_html(data) + '</span>';
     					}
     				}
     				// for more options see: examples at https://github.com/DataTables/DataTables
    			},
    			{ // column two
    				targets: 1,
    				width: '275px'
    			}
    		]
     });
     //--

public static function DataTableColumnsFilter ( {String} elem_id, {Integer+} filterColNumber, {Regex} regexStr ) {} . {Object}
@return: {Object} :: The jQuery HTML Element
@param: {String} elem_id :: The HTML Element ID to bind to ; must be a DataTable already previous initiated with smartJ$UI.DataTableInit()
@param: {Integer+} filterColNumber :: The DataTable column number 0..n
@param: {Regex} regexStr :: A valid Regex Partial Expression String (without enclosing slashes /../, as string) to filter the column values ; ex: '^(val1|val\-2)$'
@requires: jQuery
@requires: datatables/datatables-responsive.css
@requires: datatables/datatables-responsive.js
@requires: datatables/smart-datatables.js
Apply a Filter over DataTable using a regular expression ; UI Component
If a filter is applied oved data, will display just the filtered data and if no data match the filter will display no data

    Sample code: JavaScript
     // filter a DataTable by column no.1 (2nd column, starting from zero) and display only lines where column no.1 have the value: 'warning' or 'error'
     smartJ$UI.DataTableColumnsFilter('myTable', 1, '^(warning|error)$');

## class Properties

public static var overlayCssClass = 'simpledialog-overlay' ; . {String}
set N/A
get smartJ$UI.overlayCssClass
Overlay CSS class

## class Constants

documentation generated on: 2024-12-16 17:09:48 +0000

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