diff --git a/.travis.yml b/.travis.yml index e95ff3d..0428353 100644 --- a/.travis.yml +++ b/.travis.yml @@ -19,4 +19,4 @@ before_script: - cd ~/builds/ss script: - - phpunit widgets/tests/ \ No newline at end of file + - phpunit widgets/tests/ diff --git a/README.md b/README.md index dd21c8c..78e4f17 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,20 +13,30 @@ the sidebar of your website. To check out a what a [Widget](http://silverstripe. * SilverStripe 3.1 -## 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 @@ -57,28 +67,14 @@ e.g. "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 +98,8 @@ An example widget is below: **FlickrWidget.php** + :::php "Varchar", @@ -116,7 +112,6 @@ An example widget is below: private static $defaults = array( "NumberToShow" => 8 ); - private static $title = "Photos"; private static $cmsTitle = "Flickr Photos"; @@ -135,7 +130,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 +138,6 @@ An example widget is below: "Image" => "http://farm1.static.flickr.com/" .$photo->image_path. "_s.jpg" ))); } - return $output; } @@ -156,12 +150,11 @@ An example widget is below: ); } } - - ?> **FlickrWidget.ss** + :::ss <% control Photos %> <% end_control %> @@ -176,14 +169,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 +184,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