Skip to content
This repository
Browse code

MINOR Pointer to new widget module location in docs

  • Loading branch information...
commit e4c33686f9423c493e2403a2b31f4009d0a11315 1 parent d8bb1b2
Ingo Schommer authored April 18, 2012

Showing 1 changed file with 1 addition and 346 deletions. Show diff stats Hide diff stats

  1. 347  docs/en/topics/widgets.md
347  docs/en/topics/widgets.md
Source Rendered
... ...
@@ -1,348 +1,3 @@
1 1
 # Widgets
2 2
 
3  
-## Introduction
4  
-
5  
-[Widgets](http://silverstripe.org/widgets) are small pieces of functionality such as showing the latest Comments or Flickr Photos. They normally display on
6  
-the sidebar of your website. To check out a what a [Widget](http://silverstripe.org/widgets) can do watch the
7  
-[Widget video](http://silverstripe.com/assets/screencasts/SilverStripe-Blog-DragDrop-Widgets.swf) and try out the
8  
-[demo site](http://demo.silverstripe.org/)
9  
-
10  
-
11  
-## How to Use A Widget
12  
-
13  
-### Downloading and Contributing Widgets
14  
-
15  
-*  To download widgets visit [Widgets section](http://silverstripe.org/widgets)
16  
-*  Upload widgets you want to share to
17  
-[http://silverstripe.org/widgets/manage/add](http://silverstripe.org/widgets/manage/add). Make sure you read the
18  
-packaging instructions at the bottom of the page about how to make your widget package.
19  
-
20  
-
21  
-### Installing a widget
22  
-
23  
-By following the "Packaging" rules below, widgets are easily installed. 
24  
-
25  
-* Install the [blog module](http://www.silverstripe.org/blog-module/) (by default only the Blog has widgets enabled)
26  
-* Download the file and unzip to the main folder of your SilverStripe website, e.g. to `/widget_<widget-name>/`. The folder
27  
-will contain a few files, which generally won't need editing or reading.
28  
-* Run `http://my-website.com/dev/build`
29  
-* Login to the CMS and go to the 'Blog' page. Choose the "widgets" tab and drag n drop the new widget to activate it.
30  
-* Your blog will now have the widget shown
31  
-
32  
-### Adding widgets to other pages
33  
-
34  
-<div class="notice" markdown='1'>
35  
-As of version 2.2.1 there is a way to add widgets to other pages. In future releases we will hopefully make widgets part
36  
-of SiteTree therefore available on every page.
37  
-</div>
38  
-
39  
-You have to do a couple things to get a Widget to work on a page.
40  
-
41  
-First step is to add an WidgetArea to the Database to store the widget details. Then you have to edit the CMS to add a
42  
-Widget Form to manage the widgets. An example of this is below
43  
-
44  
-**mysite/code/Page.php**
45  
-
46  
-	:::php
47  
-	class Page extends SiteTree {
48  
-	
49  
-	...
50  
-	    static $has_one = array(
51  
-		"Sidebar" => "WidgetArea",
52  
-	    );
53  
-		
54  
-	    public function getCMSFields() {
55  
-		$fields = parent::getCMSFields();
56  
-		$fields->addFieldToTab("Root.Content.Widgets", new WidgetAreaEditor("Sidebar"));
57  
-		return $fields;
58  
-	    }
59  
-	....
60  
-	}
61  
-
62  
-
63  
-Then in your Template you need to call $SideBar wherever you want to render the widget
64  
-
65  
-For example: using the blackcandy theme I put this piece of code above the closing `</div>`
66  
-
67  
-**themes/blackcandy/templates/Includes/Sidebar.ss**
68  
-
69  
-	:::ss
70  
-	$Sidebar
71  
-
72  
-
73  
-## Writing your own widgets
74  
-
75  
-To create a Widget you need at least three files - a php file containing the class, a template file of the same name and
76  
-a config file called *_config.php* (if you dont need any config options for the widget to work then you can make it
77  
-blank). Each widget should be in its own folder like widgets_widgetName/
78  
-
79  
-After installing or creating a new widget, **make sure to run db/build?flush=1** at the end of the URL, *before*
80  
-attempting to use it.
81  
-
82  
-The class should extend the Widget class, and must specify three static variables - $title, the title that will appear
83  
-in the rendered widget (eg Photos), $cmsTitle, a more descriptive title that will appear in the cms editor (eg Flickr
84  
-Photos), and $description, a short description that will appear in the cms editor (eg This widget shows photos from
85  
-Flickr). The class may also specify functions to be used in the template like a page type can.
86  
-
87  
-If a Widget has configurable options, then it can specify a number of database fields to store these options in via the
88  
-static $db array, and also specify a getCMSFields function that returns a !FieldList, much the same way as a page type
89  
-does.
90  
-
91  
-An example widget is below:
92  
-
93  
-**FlickrWidget.php**
94  
-
95  
-	:::php
96  
-	<?php
97  
-	
98  
-	class FlickrWidget extends Widget {
99  
-		static $db = array(
100  
-			"User" => "Varchar",
101  
-			"Photoset" => "Varchar",
102  
-			"Tags" => "Varchar",
103  
-			"NumberToShow" => "Int"
104  
-		);
105  
-		
106  
-	
107  
-		static $defaults = array(
108  
-			"NumberToShow" => 8
109  
-		);
110  
-		
111  
-	
112  
-		static $title = "Photos";
113  
-		static $cmsTitle = "Flickr Photos";
114  
-		static $description = "Shows flickr photos.";
115  
-		
116  
-		public function Photos() {
117  
-			Requirements::javascript(THIRDPARTY_DIR . "/prototype/prototype.js");
118  
-			Requirements::javascript(THIRDPARTY_DIR . "/scriptaculous/effects.js");
119  
-			Requirements::javascript("mashups/javascript/lightbox.js");
120  
-			Requirements::css("mashups/css/lightbox.css");
121  
-			
122  
-			$flickr = new FlickrService();
123  
-			if($this->Photoset == "") {
124  
-				$photos = $flickr->getPhotos($this->Tags, $this->User, $this->NumberToShow, 1);
125  
-			} else {
126  
-				$photos = $flickr->getPhotoSet($this->Photoset, $this->User, $this->NumberToShow, 1);
127  
-			}
128  
-			
129  
-			$output = new DataObjectSet();
130  
-			foreach($photos->PhotoItems as $photo) {
131  
-				$output->push(new ArrayData(array(
132  
-					"Title" => $photo->title,
133  
-					"Link" => "http://farm1.static.flickr.com/" . $photo->image_path .".jpg",
134  
-					"Image" => "http://farm1.static.flickr.com/" .$photo->image_path. "_s.jpg"
135  
-				)));
136  
-			}
137  
-			
138  
-			return $output;
139  
-		}
140  
-	
141  
-		public function getCMSFields() {
142  
-			return new FieldList(
143  
-				new TextField("User", "User"),
144  
-				new TextField("PhotoSet", "Photo Set"),
145  
-				new TextField("Tags", "Tags"),
146  
-				new NumericField("NumberToShow", "Number to Show")
147  
-			);
148  
-		}
149  
-	}
150  
-	
151  
-	?>
152  
-
153  
-
154  
-**FlickrWidget.ss**
155  
-
156  
-	:::php
157  
-	<% control Photos %>
158  
-		<a href="$Link" rel="lightbox" title="$Title"><img src="$Image" alt="$Title" /></a>
159  
-	<% end_control %>
160  
-
161  
-
162  
-## Extending and Customizing
163  
-
164  
-### Rendering a $Widget Individually
165  
-
166  
-To call a single Widget in a page - without adding a widget area in the CMS for you to add / delete the widgets, you can
167  
-define a merge variable in the Page Controller and include it in the Page Template. 
168  
-
169  
-This example creates an RSSWidget with the SilverStripe blog feed.
170  
-
171  
-	:::php
172  
-	<?php
173  
-		public function SilverStripeFeed() {
174  
-			$widget = new RSSWidget();
175  
-			$widget->RssUrl = "http://feeds.feedburner.com/silverstripe-blog";
176  
-			return $widget->renderWith("WidgetHolder");
177  
-		}
178  
-	?>
179  
-
180  
-
181  
-To render the widget, simply include $SilverStripeFeed in your template:
182  
-
183  
-	:::ss
184  
-	  $SilverStripeFeed
185  
-
186  
-
187  
-As directed in the definition of SilverStripeFeed(), the Widget will be rendered through the WidgetHolder template. This
188  
-is pre-defined at `framework/templates/WidgetHolder.ss` and simply consists of: 
189  
-
190  
-	:::ss
191  
-	<div class="WidgetHolder">
192  
-		<h3>$Title</h3>
193  
-		$Content
194  
-	</div>
195  
-
196  
-
197  
-You can override the WidgetHolder.ss and Widget.ss templates in your theme too by adding WidgetHolder and Widget
198  
-templates to `themes/myThemeName/templates/Includes/`
199  
-
200  
-### Changing the title of your widget
201  
-
202  
-To change the title of your widget, you need to override the Title() method. By default, this simply returns the $title
203  
-variable. For example, to set your widgets title to 'Hello World!', you could use:
204  
-
205  
-**widgets_yourWidget/YourWidgetWidget.php**
206  
-
207  
-	:::php
208  
-	public function Title() {
209  
-		return "Hello World!";
210  
-	}
211  
-
212  
-
213  
-but, you can do exactly the same by setting your $title variable.
214  
-
215  
-A more common reason for overriding Title() is to allow the title to be set in the CMS. Say you had a text field in your
216  
-widget called WidgetTitle, that you wish to use as your title. If nothing is set, then you'll use your default title.
217  
-This is similar to the RSS Widget in the blog module.
218  
-
219  
-	:::php
220  
-	public function Title() {
221  
-		return $this->WidgetTitle ? $this->WidgetTitle : self::$title;
222  
-	}
223  
-
224  
-
225  
-This returns the value inputted in the CMS, if it's set or what is in the $title variable if it isn't.
226  
-
227  
-### Forms within Widgets
228  
-
229  
-To implement a form inside a widget, you need to implement a custom controller for your widget to return this form. Make
230  
-sure that your controller follows the usual naming conventions, and it will be automatically picked up by the
231  
-`[api:WidgetArea]` rendering in your *Page.ss* template.
232  
-
233  
-**mysite/code/MyWidget.php**
234  
-
235  
-	:::php
236  
-	class MyWidget extends Widget {
237  
-	  static $db = array(
238  
-	    'TestValue' => 'Text'
239  
-	  );
240  
-	}
241  
-	
242  
-	class MyWidget_Controller extends Widget_Controller {
243  
-	  public function MyFormName() {
244  
-	    return new Form(
245  
-	      $this, 
246  
-	      'MyFormName', 
247  
-	      new FieldList(
248  
-	        new TextField('TestValue')
249  
-	      ), 
250  
-	      new FieldList(
251  
-	        new FormAction('doAction')
252  
-	      )
253  
-	    );
254  
-	  }
255  
-	  
256  
-	  public function doAction($data, $form) {
257  
-	    // $this->widget points to the widget
258  
-	  }
259  
-	}
260  
-
261  
-
262  
-To output this form, modify your widget template.
263  
-
264  
-**mysite/templates/MyWidget.ss**
265  
-
266  
-	:::ss
267  
-	$Content
268  
-	$MyFormName
269  
-
270  
-<div class="notice" markdown='1'>
271  
-**Note:** The necessary controller actions are only present in subclasses of `[api:Page_Controller]`. To use
272  
-widget forms in other controller subclasses, have a look at *ContentController->handleWidget()* and
273  
-*ContentController::$url_handlers*.
274  
-</div>
275  
-
276  
-See an [alternative recipe for SilverStripe 2.3 or earlier](http://doc.silverstripe.org/old/recipes/widget-forms-2.3).
277  
-
278  
-## But what if I have widgets on my blog currently??
279  
-
280  
-If you currently have a blog installed, the widget fields are going to double up on those pages (as the blog extends the
281  
-Page class). One way to fix this is to comment out line 30 in BlogHolder.php and remove the DB entry by running a
282  
-`http://www.mysite.com/db/build`.
283  
-
284  
-**blog/code/BlogHolder.php**
285  
-
286  
-	:::php
287  
-	<?php
288  
-	
289  
-	class BlogHolder extends Page {
290  
-		
291  
-	      ........
292  
-		static $has_one = array(
293  
-		//	"SideBar" => "WidgetArea", COMMENT OUT
294  
-			'Newsletter' => 'NewsletterType'
295  
-	      .......
296  
-		public function getCMSFields() {
297  
-			$fields = parent::getCMSFields();
298  
-			$fields->removeFieldFromTab("Root.Content","Content");
299  
-		//	$fields->addFieldToTab("Root.Content.Widgets", new WidgetAreaEditor("SideBar")); COMMENT OUT
300  
-	
301  
-		........
302  
-
303  
-
304  
-Then you can use the Widget area you defined on Page.php
305  
-
306  
-## Releasing Your Widget
307  
-
308  
-### Packaging
309  
-
310  
-For a widget to be put in our official widget database they must follow this convention - If the name of your widget was
311  
-"YourName" then:
312  
-
313  
-#### File Structure for your widget
314  
-
315  
-You should have a folder called widget_YourName in the top level (the one with framework, cms..) with all your files. See
316  
-the example below. Your widget **MUST** have at least 1 Template file, 1 PHP file, the README File
317  
-[(Example)](http://open.silverstripe.com/browser/modules/widgets/twitter/trunk/README)and an _config.php file for
318  
-configuration. If you dont need any config options for the widget to work then you still need an _config.php by you can
319  
-make it blank
320  
-
321  
-The decision over whether to configure a widget in _config.php or in the CMS is important:
322  
-
323  
-*  If the setting is the kind of thing that a website author, familiar with common business apps such as Word and
324  
-Outlook, would understand - then make it configurable in the CMS.
325  
-*  If the setting is the kind of thing that the person setting up the website - doing the design and/or development -
326  
-would understand, then make it configurable in the _config.php file.
327  
-
328  
-This way, the CMS remains an application designed for content authors, and not developers. 
329  
-
330  
-*widget_name/_config.php*
331  
-
332  
-	:::php
333  
-	<?php /*  */ ?>
334  
-
335  
-
336  
-**Example Widget Structure**
337  
-
338  
-![](_images/widget_demo.gif)
339  
-
340  
-
341  
-#### How to make the Package
342  
-
343  
-*  Make a tar.gz file called widgets_YourName-0.1.tar.gz (where 0.1 is the version number).
344  
-     * Ensure when you "unzip" the compressed file it has everything the "widgets_YourName" folder with everything inside
345  
-it.
346  
-*  If made official, it will be given these locations at silverstripe.com:
347  
-    * SVN location: http://svn.silverstripe.com/open/modules/widgets/flickr/trunk
348  
-    * Official download: http://www.silverstripe.com/assets/downloads/widgets/widgets_flickr-0.1.1.tar.gz
  3
+[Widgets](http://silverstripe.org/widgets) are small pieces of functionality such as showing the latest Comments or Flickr Photos. Since SilverStripe 3.0, they have been moved into a standalone module at [github.com/silverstripe/silverstripe-widgets](https://github.com/silverstripe/silverstripe-widgets).

0 notes on commit e4c3368

Please sign in to comment.
Something went wrong with that request. Please try again.