Widgets

Introduction

One immediately recognizable features of the web application is the diversity of widgets on the right-hand side of the window, each containing some user input and/or output. Each of those widgets is generated by a class that extends X2Widget, which can be found in protected/components. The widgets are loaded into the controller by the setPortlets filter (and inherited by all subclasses of x2base).

Creating a widget

The first step to creating a new widget is to make a new PHP class that extends X2Widget, name the file after the class, and to place the widget in the protected/components directory. Note the inheritance of properties from CWidget, the parent class of X2Widget. A complete widget should contain, at minimum, an override of the CWidget::run() method that constructs the markup associated with that widget.

Widget Templates

Widgets use view files to generate the final HTML that comprises their front-end. By default, widgets look for view files in protected/components/views. The markup associated with a widget can therefore be placed in such a view file, then rendered in the widget's run() method, passing it any parameters needed in the view. For example, the action menu widget's run method contains the following:

$this->render('actionMenu', array(
	'total' => $total,
	'unfinished' => $unfinished,
	'overdue' => $overdue,
	'complete' => $complete,
));

In this example, the menu would open and render protected/components/views/actionMenu.php, inside of which the local variables $total, $unfinished, $overdue and $complete would be available as part of the template's dynamic content.

Adding the widget to the app

Widgets are loaded by x2base::filterSetPortlets(), and the widgets that are loaded depend on the application configuration parameter "registeredWidgets" (in protected/config/main.php), which is an array in the format "WidgetClassName" => "Widget Title":

		'registeredWidgets'=>array(
			'TimeZone' => 'Time Zone',
			'MessageBox'=>'Message Board',
			'QuickContact'=>'Quick Contact',
			'GoogleMaps'=>'Google Map',
			'TwitterFeed'=>'Twitter Feed',
			'ChatBox'=>'Chat',
			'NoteBox'=>'Note Pad',
			'ActionMenu'=>'My Actions',
			'TagCloud'=>'Tag Cloud',
			'OnlineUsers'=>'Active Users',
			'MediaBox' => 'Media',
			'DocViewer' => 'Doc Viewer',
			'TopSites' => 'Top Sites',
		),

Thus, to enable or disable a widget, add or remove an entry from that array.