FreePBX Open Source - Developing for UCP 14+

Table of Contents

1 File Structure
2 PHP Module Methods
- 2.1 getSimpleWidgetList
- 2.2 getWidgetList
- 2.3 getSimpleWidgetDisplay
- 2.4 getWidgetDisplay
- 2.5 getWidgetSettingsDisplay
- 2.6 getSimpleWidgetSettingsDisplay
- 2.7 getUserSettingsDisplay
- 2.8 poll (PHP)
- 2.9 getChatHistory
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
- 4.1 post-body.simplewidget
- 4.2 post-body.widgets
- 4.3 post-body.widget-added
- 4.4 post-body.widget-removed
- 4.5 post-body.widgetsettings
- 4.6 post-body.simplewidgetsettings
- 4.7 logIn
- 4.8 logOut
- 4.9 chatWindowAdded
- 4.10 chatWindowRemoved
5 Getting logged in User Information
6 Available Libraries
- 6.1 Javascript
- 6.2 PHP
7 Styling/Library Options
- 7.1 Bootstrap Tables
- 7.2 Bootstrap Toggle
- 7.3 Bootstrap Select
- 7.4 Bootstrap Multiselect
8 UCP Javascript Dialogs
- 8.1 Alerts
- 8.2 Confirms
- 8.3 Dialogs
9 UCP Javascript Date Methods
- 9.1 UCP.humanDiff
- 9.2 UCP.dateTimeFormatter
- 9.3 UCP.timeFormatter
- 9.4 UCP.dateFormatter
- 9.5 UCP.durationFormatter
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

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.

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

Method	Description	Returns
Developing for UCP 14+#getSimpleWidgetList	Widgets to add to left bar	array
Developing for UCP 14+#getWidgetList	Widgets for page	array
Developing for UCP 14+#getSimpleWidgetDisplay	Get Simple Widget Display Content	array
Developing for UCP 14+#getWidgetDisplay	Get Widget display content	array
Developing for UCP 14+#getWidgetSettingsDisplay	Get widget settings display	array
Developing for UCP 14+#getSimpleWidgetSettingsDisplay	Get simple widget settings display	array
Developing for UCP 14+#getUserSettingsDisplay	Display a tab in the user settings modal	array
Developing for UCP 14+#poll	Used to send and get information to/from the UCP interface. On a 5 second interval	mixed
Developing for UCP 14+#getChatHistory	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

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

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:

/**
 * Get Simple Widget Display
 * @method getWidgetDisplay
 * @param  string           $id The widget id. This is the key of the 'list' array in getSimpleWidgetList
 * @param  string           $uuid The UUID of the widget
 * @return array               Array of information
 */
public function getSimpleWidgetDisplay($id,$uuid) {
    $displayvars = array();
    return array(
        'title' => _("Follow Me"),
        'html' => $this->load_view(__DIR__.'/views/widget.php',$displayvars)
    );
}

Array:

Key	Type	Required	Notes

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:

/**
 * Get Widget Display
 * @method getWidgetDisplay
 * @param  string           $id The widget id. This is the key of the 'list' array in getWidgetList
 * @param  string           $uuid The UUID of the widget
 * @return array               Array of information
 */
public function getWidgetDisplay($id, $uuid) {
    $displayvars = array();
    return array(
        'title' => _("Follow Me"),
        'html' => $this->load_view(__DIR__.'/views/widget.php',$displayvars)
    );
}

Array:

Key	Type	Required	Notes

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:

/**
 * Get Widget Settings Display
 * @method getWidgetDisplay
 * @param  string           $id The widget id. This is the key of the 'list' array in getWidgetList
 * @param  string           $uuid The UUID of the widget
 * @return array               Array of information
 */
public function getWidgetSettingsDisplay($id, $uuid) {
    $displayvars = array();
    return array(
        'title' => _("Follow Me"),
        'html' => $this->load_view(__DIR__.'/views/widget.php',$displayvars)
    );
}

Array:

Key	Type	Required	Notes

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:

/**
 * Get Simple Widget Settings Display
 * @method getSimpleWidgetDisplay
 * @param  string           $id The widget id. This is the key of the 'list' array in getWidgetList
 * @param  string           $uuid The UUID of the widget
 * @return array               Array of information
 */
public function getSimpleWidgetSettingsDisplay($id, $uuid) {
    $displayvars = array();
    return array(
        'title' => _("Follow Me"),
        'html' => $this->load_view(__DIR__.'/views/widget.php',$displayvars)
    );
}

Array:

Key	Type	Required	Notes

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:

/**
 * Display a Tab in the user settings modal
 * @method getUserSettingsDisplay
 * @return array               Array of information
 */
function getUserSettingsDisplay() {
    return array(
        array(
            "rawname" => "zulu",
            "name" => _("Zulu"),
            "html" => $this->load_view(__DIR__.'/views/zulu.php',$vars)
        )
    );
}

Array:

Key	Type	Required	Notes

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

/**
 * Poll for information
 * @method poll
 * @param array     $data     Data from Javascript prepoll function (if any)
 * @return mixed              Data you'd like to send back to the javascript for this module
 */
function poll($data) {
    return array("data" => "goes here");
}

getChatHistory

Returns an array of chat history to load when a new chat window is created in UCP

Code:
/**
 * Get Chat History
 * @method getChatHistory
 * @param string      $from       The 'from' set by UCP.addChat javascript function
 * @param string      $to         The 'to' set by UCP.addChat javascript function
 * @param boolean     $newWindow  Is this a new window? (true or false)
 * @return array                  Array of information
 */
function getChatHistory($from, $to, $newWindow) {
    $final = array();
    $final['messages'][] = array(
        'id' => 'msgid',
        'from' => 'from',
        'message' => $body,
        'date' => '1517696178',
        'direction' => 'in'
    );
    reutrn array('messages' => $final, 'lastMessage' => $final['messages'][0]);
}

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":

var FindmefollowC = UCPMC.extend({
    init: function(){
         
    },
    displayWidget: function(widget_id,dashboard_id) {

All of these methods will only execute for the widget's parent module.

Method	Description

Method	Description
Developing for UCP 14+#addSimpleWidget	Triggered when a module has been added to the sidebar
Developing for UCP 14+#displayWidget	Triggered when a module's widget is displayed
Developing for UCP 14+#displaySimpleWidget