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.

Adding the widget to the registry

Widgets loaded by filterSetPortlets are loaded are contained in the application configuration parameter "registeredWidgets" (in protected/config/main.php), in the format "ClassName" => "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',
		),

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.