Developing for UCP 14+
UCP for FreePBX 14 changed substantially. This is a working list of all the functions/methods and calls that can be used in UCP 14 from any module.
- 1 File Structure
- 2 PHP Module Methods
- 3 Javascript Module Methods
- 3.1 addSimpleWidget
- 3.2 displayWidget
- 3.3 displaySimpleWidget
- 3.4 displayWidgetSettings
- 3.5 displaySimpleWidgetSettings
- 3.6 showDashboard
- 3.7 resize
- 3.8 windowState
- 3.9 prepoll
- 3.10 poll (Javascript)
- 4 UCP Javascript Events
- 5 Getting logged in User Information
- 6 Available Libraries
- 6.1 Javascript
- 6.2 PHP
- 7 Styling/Library Options
- 8 UCP Javascript Dialogs
- 9 UCP Javascript Date Methods
- 10 UCP Javascript Date/Time Specific Variables
- 11 UCP Javascript Utility Functions
- 11.1 UCP.parseUrl
- 11.2 UCP.callModuleByMethod
- 11.3 UCP.callModulesByMethod
- 11.4 UCP.validMethod
- 12 UCP Javascript Chat Functions Methods
- 12.1 UCP.addChat
- 12.2 UCP.addChatMessage
- 12.3 UCP.removeChat
- 13 UCP PHP Chat functions
- 14 Code Snippets
File Structure
The file structure of a UCP module is very similar to that of FreePBX. Firstly create a UCP directory under your module. In there you'll need to create a new class called: Rawname.class.php
There should also be an assets folder, within the assets folder you can have images, css, less and js.
Any javascript files placed in the js folder will be included globally in all of UCP so be careful of conflicts with other libraries!!
Less and CSS will be merged and compiled on the fly. Less is also global so make sure that you aren't rewriting the entire interface which may cause issues for other modules. It's best to use CSS selectors in LESS files or CSS to contain your styling changes to your module only:
.grid-stack-item[data-rawname=conferencespro] { |
PHP Module Methods
Method | Description | Returns |
---|---|---|
Widgets to add to left bar | array | |
Widgets for page | array | |
Get Simple Widget Display Content | array | |
Get Widget display content | array | |
Get widget settings display | array | |
Get simple widget settings display | array | |
Display a tab in the user settings modal | array | |
Used to send and get information to/from the UCP interface. On a 5 second interval | mixed | |
Used to get chat history when a new chat window is created | array |
getSimpleWidgetList
Get Side Bar Widgets List. This will group all widgets for this module's sidebar under the module's group.
Generates:
Code:
/**
* Get Simple Widget List
* @method getSimpleWidgetList
* @return array Array of information
*/
function getSimpleWidgetList() {
return array(
"rawname" => "findmefollow",
"display" => _("Find Me / Follow Me"),
"icon" => "fa fa-binoculars",
"list" => array(
"1000" => array(
"display" => "Dev4",
)
)
);
} |
Array:
Key | Type | Required | Notes |
|
|
---|---|---|---|---|---|
rawname | string | Yes | module rawname |
|
|
display | string | Yes | The Widget Main Title |
|
|
icon | string | Yes | The Widget Icon |
|
|
list | array | Yes | List of Widgets this module provides |
|
|
|__(ID)__> | Key | Type | Keys | Required | Notes |
| display | string |
| Yes | The widget sub title |
| description | string |
| No | The widget description |
| hasSettings | boolean |
| No | Set to true if this widget has settings. This will make the cog (gear) icon display on the widget display |
| icon | string |
| No | If set the widget in on the side bar will use this icon instead of the main icon |
| dynamic | boolean |
| No | If set to true then this widget can be added multiple times |
getWidgetList
Get the Widget List provided by this module. Grouped by this module.
Generates:
Code:
/**
* Get Widget List
* @method getWidgetList
* @return array Array of information
*/
function getWidgetList() {
return array(
"rawname" => "findmefollow",
"display" => _("Find Me / Follow Me"),
"icon" => "fa fa-binoculars",
"list" => array(
"1000" => array(
"display" => "Dev4",
"hasSettings" => true,
"defaultsize" => array("height" => 2, "width" => 3)
)
)
);
} |
Array:
Key | Type | Required | Notes |
|
|
---|---|---|---|---|---|
rawname | string | Yes | module rawname |
|
|
display | string | Yes | The Widget Main Title |
|
|
icon | string | Yes | The Widget Icon |
|
|
list | array | Yes | List of Widgets this module provides |
|
|
|__(ID)__> | Key | Type | Keys | Required | Notes |
| display | string |
| Yes | The widget sub title |
| description | string |
| No | The widget description |
| hasSettings | boolean |
| No | Set to true if this widget has settings. This will make the cog (gear) icon display on the widget |
| defaultsize | array | height, width | Yes | The default size of the widget when placed in the dashboard |
| minsize | array | height, width | No | The minimum size a widget can be when resized on the dashboard |
| maxsize | array | height, width | No | The max size a widget can be when resized on the dashboard |
| noresize | boolean |
| No | If set to true the widget will not be allowed to be resized |
| icon | string |
| No | If set the widget in the dashboard will use this icon instead of the main icon |
| dynamic | boolean |
| No | If set to true this widget can be added multiple times |
| noload | boolean |
| No | If set to true then this widget will not load html through ajax |
getSimpleWidgetDisplay
Get the Side Bar Widget Display.
Generates:
Code:
Array:
Key | Type | Required | Notes |
---|---|---|---|
title | string | Yes | Not Used at this time but still required (will be soon) |
html | string | Yes | The widget HTML |
getWidgetDisplay
This returns the HTML that will be displayed within the widget. The cog (Gear) will only display if getWidgetList stated there were settings available through "hasSettings"
Generates:
Code:
Array:
Key | Type | Required | Notes |
---|---|---|---|
title | string | Yes | Not Used at this time but still required (will be soon) |
html | string | Yes | The widget HTML |
getWidgetSettingsDisplay
This returns the HTML to be displayed when the user hits the cog (gear) icon on the widget title bar.
Generates:
Code:
Array:
Key | Type | Required | Notes |
---|---|---|---|
title | string | Yes | Not Used at this time but still required (will be soon) |
html | string | Yes | The widget HTML |
getSimpleWidgetSettingsDisplay
This returns the HTML to be displayed when the user hits the cog (gear) icon in the side bar.
Generates:
Code:
Array:
Key | Type | Required | Notes |
---|---|---|---|
title | string | Yes | Not Used at this time but still required (will be soon) |
html | string | Yes | The widget HTML |
getUserSettingsDisplay
Get user settings display. When the modal has finished loading Developing for UCP 14+#post-body.simplewidgetsettings is triggered with a widget_id of 'settings' and a widget_type_id of null
The return array is nested so that you can have multiple views from one module
Generates:
Code:
Array:
Key | Type | Required | Notes |
---|---|---|---|
rawname | string | Yes | module rawname |
name | string | Yes | The Tab's Title |
html | string | Yes | HTML for the tab |
poll (PHP)
Used to send and get information to/from the UCP interface. On a 5 second interval. This would be the PHP side. Make sure to utilize the javascript side as well
getChatHistory
Returns an array of chat history to load when a new chat window is created in UCP
Javascript Module Methods
All of these methods should be in your module's javascript class definition, class definitions should be <modulerawname>C. Thus "findmefollow" turns into "FindmefollowC":
All of these methods will only execute for the widget's parent module.
Method | Description |
---|---|
Triggered when a module has been added to the sidebar | |
Triggered when a module's widget is displayed | |
Triggered when a module's simple display finishes | |
Triggered when a module's widget settings are displayed | |
Triggered when a module's simple widget settings are displayed | |
Triggered when a dashboard has finished loading | |
Triggered when a module's widget is resized | |
Triggered when the browser window is hidden (Values: hidden, visible) | |
Used to generate data to send to the PHP poll function for this module | |
Used to process data sent from the PHP poll function for this module |
addSimpleWidget
This method is executed when the side bar widget has been added to the side bar.
The widget id is UUID string. You can find your widget by running:
displayWidget
This method is executed when the side bar widget has finished loading.
The widget id is UUID string. You can find your widget by running:
displaySimpleWidget
This method is executed after the side bar widget has been clicked and the window has fully extended has finished loading.
The widget ID is a UUID string. You can find your side bar widget by running:
displayWidgetSettings
This method is executed when the settings window has finished loading.
The widget ID is a UUID string. You can find the widget settings by running:
displaySimpleWidgetSettings
This method is executed when the settings window has finished loading.
The widget ID is a UUID string. You can find the widget settings by running:
showDashboard
This method is executed when the dashboard has finished loading
resize
The method is executed when the widget has been resized
The widget id is a UUID string. You can find your widget by running:
windowState
The method is executed when the tab in the browser (Or the browser itself) is brought into focus or out of focus
prepoll
This method is used to populate data to send to the PHP poll function for this module
poll (Javascript)
This method is used to process data returned from the PHP poll function for this module
UCP Javascript Events
Event | Description |
---|---|
Triggered when the simple widget display finishes loading | |
Triggered when all widgets on the active dashboard finish loading | |
Triggered when a single widget is added | |
Triggered when a single widget is removed | |
Triggered when the module settings window finishes loading | |
Triggered when the simple settings window finishes loading | |
Triggered when the user is "logged in" (after a login or a refresh if already logged in) | |
Triggered when the user clicks log out | |
Triggered when a chat window has been added to the screen | |
Triggered when a chat window has been removed from the screen |
post-body.simplewidget
This trigger is executed after the side bar widget has been clicked and the window has fully extended has finished loading.
The widget ID is a UUID string. You can find your side bar widget by running:
post-body.widgets
This trigger is executed after all widgets have finished loading on a dashboard.
post-body.widget-added
This trigger is executed after the widget has finished loading after being added on a dashboard.
The widget id is a UUID string. You can find your widget by running:
post-body.widget-removed
This trigger is executed after a widget has been removed from a dashboard
The widget is the jquery object of the element before it was deleted
post-body.widgetsettings
This trigger is executed after the html has finished loading inside a settings modal
The widget id is a UUID string. You can find your widget by running:
post-body.simplewidgetsettings
This trigger is executed after the html has finished loading inside a settings modal
The widget id is a UUID string. You can find your widget by running:
logIn
This trigger is executed when the user logs in
logOut
This trigger is executed when the user logs out
chatWindowAdded
This is triggered when a new chat window has been added to the page
chatWindowRemoved
This is triggered when a chat window has been removed from the page
Getting logged in User Information
To get logged in user information anywhere in your PHP script just run $this->user. All of the logged in user's information will be in this property as an array:
Available Libraries
Javascript
Async 2.1.4: Home - Documentation
Bootstrap 3.3.7: Bootstrap
Bootstrap Multi Select 0.9.13: http://davidstutz.github.io/bootstrap-multiselect/ (See Also: Developing for UCP 14+#Bootstrap Multiselect)
Bootstrap Select 1.12.1: Getting Started | bootstrap-select · SnapAppointments Developer (See Also: Developing for UCP 14+#Bootstrap Select
Bootstrap Table 1.11.0: Bootstrap Table · An extended table to the integration with some of the most widely used CSS frameworks. (Supports Bootstrap, Semantic UI, Bulma, Material Design, Foundation) (See Also: Developing for UCP 14+#Bootstrap Tables)
Bootstrap Toggle 2.2.2: Bootstrap Toggle
Emojione 2.2.7: http://emojione.com/
JED: GitHub - messageformat/Jed: Gettext Style i18n for Modern JavaScript Apps
The way we use this is for translations. So any string would be _(“String”). You can also use sprint(_(“String %s”),”word”)
jQuery 3.1.1: jQuery
jQuery UI 1.12.1: https://jqueryui.com/
jQuery Migrate: 3.0.0:
jPlayer 2.9.2: jPlayer : HTML5 Audio & Video for jQuery
js.cookie 2.1.3: GitHub - js-cookie/js-cookie: A simple, lightweight JavaScript API for handling browser cookies
modernizr 3.3.1: https://modernizr.com/
moment 2.20.2: Moment.js | Home
moment-duration 2.21.1: GitHub - jsmreese/moment-duration-format: Format function plugin for the Moment Duration object.
notify 2.0.3: https://alexgibson.github.io/notify.js/
http://socket.io 1.7.2: Socket.IO
Sortable 1.4.2: http://rubaxa.github.io/Sortable/
node-uuid: GitHub - uuidjs/uuid: Generate RFC-compliant UUIDs in JavaScript
PHP
mobile_detect 2.8: https://github.com/serbanghita/Mobile-Detect
symfony 3.0: https://symfony.com/
uuid 3.4: https://github.com/ramsey/uuid
moment 1.20: https://github.com/fightbulc/moment.php
carbon 1.22.1: https://github.com/briannesbitt/Carbon
Styling/Library Options
Bootstrap Tables
All available options can also be set through HTML5 data tags: http://bootstrap-table.wenzhixin.net.cn/documentation/
Bootstrap Toggle
For checkboxes we recommend styling them using bootstrap toggle which is included
All available options can also be set through HTML5 data tags: Bootstrap Toggle
Bootstrap Select
We recommend using this method over multiselect because the dropdown will not get stuck inside of modal boxes or containers as the dropdown is attached to the entire document body.
All available options can also be set through HTML5 data tags: https://silviomoreto.github.io/bootstrap-select/options/
Bootstrap Multiselect
This is not a recommended way to show dropdowns in UCP but it is supported for legacy reasons. Options can not be set through HTML5 data tags and the drop down can get stuck in containers (see image below)
UCP Javascript Dialogs
Alerts
Alert styling uses http://getbootstrap.com/components/#alerts for colors. Using the global UCP.showAlert function is preferred over the standard javascript alert().
The ID for the global Alert Box is "alert_modal". You can use this in conjunction with bootstrap modal events or methods: http://getbootstrap.com/javascript/#modals
The callback function is executed when the window is displayed.
Function:
Example:
Confirms
Confirm styling uses http://getbootstrap.com/components/#alerts for colors. Using the global UCP.showConfirm function is preferred over the standard javascript confirm().
The ID for the global Alert Box is "confirm_modal". You can use this in conjunction with bootstrap modal events or methods: http://getbootstrap.com/javascript/#modals
The callback function is only executed if the user hits accept
Function:
Example:
Dialogs
The ID for the global Dialog Box is "globalModal". You can use this in conjunction with bootstrap modal events or methods: http://getbootstrap.com/javascript/#modals
Function:
Example:
UCP Javascript Date Methods
Additionally there are some new methods provided by UCP for date conversions from PHP timestamps to the user's date formats that have been set either in UCP or in the Administration panel. These methods should be used whenever parsing and displaying time/date based data is need
UCP.humanDiff
UCP.dateTimeFormatter
UCP.timeFormatter
UCP.dateFormatter
UCP.durationFormatter
UCP Javascript Date/Time Specific Variables
UCP Javascript Utility Functions
UCP.parseUrl
UCP.callModuleByMethod
UCP.callModulesByMethod
UCP.validMethod
UCP Javascript Chat Functions Methods
UCP.addChat
Brings up a chat window, calling this method multiple times will add additional chat messages to the window utilizing the function UCP.addChatMessage
Function:
Example:
UCP.addChatMessage
Adds a single message to an already existing chat window. The window must already exist utilizing UCP.addChat
Example:
UCP.removeChat
Remove the chat window from display
UCP PHP Chat functions