© 2015 X2Engine Inc.

Difference between revisions of "Widgets"

From X2Engine
Jump to: navigation, search
(Creating a widget)
(Creating a widget)
 
(13 intermediate revisions by 2 users not shown)
Line 7: Line 7:
 
The first step to creating a new widget is to make a new PHP class that extends [[x2doc:X2Widget|X2Widget]], name the file after the class, and to place the widget in the <tt>protected/components</tt> directory. Note the inheritance of properties from [[yii:CWidget|CWidget]], the parent class of X2Widget. A complete widget should contain, at minimum, an override of the [[yii:CWidget#run-detail|CWidget::run()]] method that constructs the markup associated with that widget.
 
The first step to creating a new widget is to make a new PHP class that extends [[x2doc:X2Widget|X2Widget]], name the file after the class, and to place the widget in the <tt>protected/components</tt> directory. Note the inheritance of properties from [[yii:CWidget|CWidget]], the parent class of X2Widget. A complete widget should contain, at minimum, an override of the [[yii:CWidget#run-detail|CWidget::run()]] method that constructs the markup associated with that widget.
  
== Adding the widget to the registry ==
+
== Widget Templates ==
Widgets loaded by <tt>filterSetPortlets</tt> are loaded are contained in the application configuration parameter "registeredWidgets" (in <tt>protected/config/main.php</tt>), in the format "ClassName" => "Widget Title":
+
Widgets use view files to generate the final HTML that comprises their front-end. By default, widgets look for view files in <tt>protected/components/views</tt>. The markup associated with a widget can therefore be placed in such a view file, then rendered in the widget's <tt>run()</tt> method, passing it any parameters needed in the view. For example, the action menu widget's run method contains the following:
 +
<syntaxhighlight lang="php">
 +
$this->render('actionMenu', array(
 +
'total' => $total,
 +
'unfinished' => $unfinished,
 +
'overdue' => $overdue,
 +
'complete' => $complete,
 +
));</syntaxhighlight>
 +
In this example, the menu would open and render <tt>protected/components/views/actionMenu.php</tt>, inside of which the local variables <tt>$total</tt>, <tt>$unfinished</tt>, <tt>$overdue</tt> and <tt>$complete</tt> would be available as part of the template's dynamic content.
 +
 
 +
== Adding the widget to the app ==
 +
Widgets are loaded by [[x2propdoc:class-x2base.html#_filterSetPortlets|x2base::filterSetPortlets()]], and the widgets that are loaded depend on the application configuration parameter "registeredWidgets" (in <tt>protected/config/main.php</tt>), which is an array in the format "WidgetClassName" => "Widget Title":
  
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
Line 28: Line 39:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Widget views ==
+
Thus, to enable or disable a widget, add or remove an entry from that array.
All widgets will by default render views named in <tt>protected/components/views</tt>. Thus, to build the display markup for a widget, it is not necessary to generate it all within the widget class itself; the markup associated with a widget can be placed within a view file in that directory and then used with a call to <tt>renderPartial</tt> similar to how one would do so in a controller.
 

Latest revision as of 01:29, 25 October 2012


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.