diff --git a/README.md b/README.md index ab5c46c..aa9c276 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ## Introduction -[Widgets](http://silverstripe.org/widgets) are small pieces of functionality such as showing the latest Comments or Flickr Photos. They normally display on +[Widgets](http://silverstripe.org/widgets) are small pieces of functionality such as showing the latest comments or Flickr photos. They normally display on the sidebar of your website. To check out a what a [Widget](http://silverstripe.org/widgets) can do watch the [Widget video](http://silverstripe.com/assets/screencasts/SilverStripe-Blog-DragDrop-Widgets.swf) and try out the [demo site](http://demo.silverstripe.org/) @@ -13,72 +13,46 @@ the sidebar of your website. To check out a what a [Widget](http://silverstripe. * SilverStripe 3.0 -## How to Use A Widget +### Installation -### Downloading and Contributing Widgets +Install the module through [composer](http://getcomposer.org): -* To download widgets visit [Widgets section](http://silverstripe.org/widgets) -* Upload widgets you want to share to -[http://silverstripe.org/widgets/manage/add](http://silverstripe.org/widgets/manage/add). Make sure you read the -packaging instructions at the bottom of the page about how to make your widget package. + composer require silverstripe/widgets +Widgets are essentially database relations to other models, mostly page types. +By default, they're not added to any of your own models. The easiest and most common +way to get started would be to create a single collection of widgets under the +name "SideBar" on your `Page` class. This is handled by an extension which you +can enable through your `config.yml`: -### Installing the Widgets Module + :::yml + Page: + extensions: + - WidgetPageExtension -Download and unzip the [Widgets Module](http://www.silverstripe.org/widgets-module/) to the main folder of your website and ensure the folder is named `widgets`. +Run a `dev/build`, and adjust your templates to include the resulting sidebar view. +The placeholder is called `$SideBarView`, and loops through all widgets assigned +to the current page. +Alternatively, you can add one or more widget collections to your own page types. +Here's an example on how to just add widgets to a `MyPage` type, and call it +`MyWidgetArea` instead. -### Installing a widget - -By following the "Packaging" rules below, widgets are easily installed. This example uses the Blog module which by default has widgets already enabled. - -* Install the [blog module](http://www.silverstripe.org/blog-module/). -* Download the widget and unzip to the main folder of your SilverStripe website, e.g. to `/widget_/`. The folder -will contain a few files, which generally won't need editing or reading. -* Run `http://my-website.com/dev/build` -* Login to the CMS and go to the 'Blog' page. Choose the "widgets" tab and click the new widget to activate it. -* Your blog will now have the widget shown - - -### Adding widgets to other pages - -You have to do a couple things to get a Widget to work on a page. - -* Install the Widgets Module, see above. -* Add a WidgetArea field to your Page. -* Add a new tab to the CMS with a WidgetAreaEditor field for managing the widgets. -e.g. - -**mysite/code/Page.php** - - class Page extends SiteTree { - ... - static $has_one = array( + :::php + class MyPage extends Page { + // ... + static $has_one = array( "MyWidgetArea" => "WidgetArea", - ); + ); - public function getCMSFields() { + public function getCMSFields() { $fields = parent::getCMSFields(); $fields->addFieldToTab("Root.Widgets", new WidgetAreaEditor("MyWidgetArea")); return $fields; - } - ... + } } - -* Then in your Template you need to call $MyWidgetArea wherever you want to render the widget - -e.g. using the simple theme, add the `$MyWidgetArea` variable above the closing `` - -**themes/simple/templates/Includes/Sidebar.ss** - - - +In this case, you need to alter your templates to include the `$MyWidgetArea` placeholder. ## Writing your own widgets @@ -102,8 +76,8 @@ An example widget is below: **FlickrWidget.php** + :::php "Varchar", @@ -112,11 +86,9 @@ An example widget is below: "NumberToShow" => "Int" ); - static $defaults = array( "NumberToShow" => 8 ); - static $title = "Photos"; static $cmsTitle = "Flickr Photos"; @@ -135,7 +107,7 @@ An example widget is below: $photos = $flickr->getPhotoSet($this->Photoset, $this->User, $this->NumberToShow, 1); } - $output = new DataObjectSet(); + $output = new ArrayList(); foreach($photos->PhotoItems as $photo) { $output->push(new ArrayData(array( "Title" => $photo->title, @@ -143,7 +115,6 @@ An example widget is below: "Image" => "http://farm1.static.flickr.com/" .$photo->image_path. "_s.jpg" ))); } - return $output; } @@ -156,12 +127,11 @@ An example widget is below: ); } } - - ?> **FlickrWidget.ss** + :::ss <% control Photos %> $Title <% end_control %> @@ -176,14 +146,12 @@ define a merge variable in the Page Controller and include it in the Page Templa This example creates an RSSWidget with the SilverStripe blog feed. - RssUrl = "http://feeds.feedburner.com/silverstripe-blog"; - return $widget->renderWith("WidgetHolder"); - } - ?> - + :::php + public function SilverStripeFeed() { + $widget = new RSSWidget(); + $widget->RssUrl = "http://feeds.feedburner.com/silverstripe-blog"; + return $widget->renderWith("WidgetHolder"); + } To render the widget, simply include $SilverStripeFeed in your template: @@ -193,6 +161,7 @@ To render the widget, simply include $SilverStripeFeed in your template: As directed in the definition of SilverStripeFeed(), the Widget will be rendered through the WidgetHolder template. This is pre-defined at `framework/templates/WidgetHolder.ss` and simply consists of: + :::ss

$Title

$Content @@ -209,6 +178,7 @@ variable. For example, to set your widgets title to 'Hello World!', you could us **widgets_yourWidget/YourWidgetWidget.php** + :::php public function Title() { return "Hello World!"; } @@ -220,6 +190,7 @@ A more common reason for overriding Title() is to allow the title to be set in t widget called WidgetTitle, that you wish to use as your title. If nothing is set, then you'll use your default title. This is similar to the RSS Widget in the blog module. + :::php public function Title() { return $this->WidgetTitle ? $this->WidgetTitle : self::$title; } @@ -235,6 +206,7 @@ sure that your controller follows the usual naming conventions, and it will be a **mysite/code/MyWidget.php** + :::php class MyWidget extends Widget { static $db = array( 'TestValue' => 'Text' @@ -265,6 +237,7 @@ To output this form, modify your widget template. **mysite/templates/MyWidget.ss** + :::ss $Content $MyFormName @@ -280,8 +253,8 @@ Page class). One way to fix this is to comment out line 30 in BlogHolder.php and **blog/code/BlogHolder.php** + :::php - - -**Example Widget Structure** - -![](_images/widget_demo.gif) - - -#### How to make the Package - -* Make a tar.gz file called widgets_YourName-0.1.tar.gz (where 0.1 is the version number). - * Ensure when you "unzip" the compressed file it has everything the "widgets_YourName" folder with everything inside -it. -* If made official, it will be given these locations at silverstripe.com: - * SVN location: http://svn.silverstripe.com/open/modules/widgets/flickr/trunk - * Official download: http://www.silverstripe.com/assets/downloads/widgets/widgets_flickr-0.1.1.tar.gz +Then you can use the Widget area you defined on Page.php \ No newline at end of file