OSS-905 Moved docs to docs/en/

This commit is contained in:
Shoaib Ali 2015-11-07 12:45:35 +13:00
parent eee39bca4e
commit 4e5f1bf3e2
4 changed files with 209 additions and 145 deletions

167
README.md
View File

@ -2,7 +2,7 @@
[![Build Status](https://secure.travis-ci.org/silverstripe/silverstripe-widgets.png?branch=1.1)](http://travis-ci.org/silverstripe/silverstripe-widgets) [![Build Status](https://secure.travis-ci.org/silverstripe/silverstripe-widgets.png?branch=1.1)](http://travis-ci.org/silverstripe/silverstripe-widgets)
## Introduction ## Overview
[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 the sidebar of your website. To check out a what a [Widget](http://silverstripe.org/widgets) can do watch the
@ -13,153 +13,30 @@ the sidebar of your website. To check out a what a [Widget](http://silverstripe.
* SilverStripe 3.2 * SilverStripe 3.2
### Installation ### Installation
Install the module through [composer](http://getcomposer.org): Install the module through [composer](http://getcomposer.org):
composer require silverstripe/widgets ```
$ composer require silverstripe/widgets
```
Widgets are essentially database relations to other models, mostly page types. You'll also need to run `dev/build`.
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`:
:::yml ## Documentation
Page:
extensions:
- WidgetPageExtension
Run a `dev/build`, and adjust your templates to include the resulting sidebar view. See the [docs/en](docs/en/introduction.md) folder.
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. ## Versioning
Here's an example on how to just add widgets to a `MyPage` type, and call it
`MyWidgetArea` instead.
### Installing a widget This library follows [Semver](http://semver.org). According to Semver, you will be able to upgrade to any minor or patch version of this library without any breaking changes to the public API. Semver also requires that we clearly define the public API for this library.
By following the "Packaging" rules below, widgets are easily installed. This example uses the Blog module which by default has widgets already enabled. All methods, with `public` visibility, are part of the public API. All other methods are not part of the public API. Where possible, we'll try to keep `protected` methods backwards-compatible in minor/patch versions, but if you're overriding methods then please test your work before upgrading.
* 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_<widget-name>/`. 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
## Reporting Issues
### Adding widgets to other pages Please [create an issue](http://github.com/silverstripe/silverstripe-widgets/issues) for any bugs you've found, or features you're missing.
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 {
...
private static $has_one = array(
"MyWidgetArea" => "WidgetArea",
);
public function getCMSFields() {
$fields = parent::getCMSFields();
$fields->addFieldToTab("Root.Widgets", new WidgetAreaEditor("MyWidgetArea"));
return $fields;
}
}
In this case, you need to alter your templates to include the `$MyWidgetArea` placeholder.
## Writing your own widgets
To create a Widget you need at least three files - a php file containing the class, a template file of the same name and
a config file called *_config.php* (if you dont need any config options for the widget to work then you can make it
blank). Each widget should be in its own folder like widgets_widgetName/
After installing or creating a new widget, **make sure to run db/build?flush=1** at the end of the URL, *before*
attempting to use it.
The class should extend the Widget class, and must specify three config variables:
* `title`: The title that will appear in the rendered widget (eg Photos). This can be customised by the CMS admin
* `cmsTitle`: a more descriptive title that will appear in the cms editor (eg Flickr Photos)
* `description`: a short description that will appear in the cms editor (eg This widget shows photos from
Flickr). The class may also specify functions to be used in the template like a page type can.
If a Widget has configurable options, then it can specify a number of database fields to store these options in via the
static $db array, and also specify a getCMSFields function that returns a !FieldList, much the same way as a page type
does.
An example widget is below:
**FlickrWidget.php**
:::php
<?php
class FlickrWidget extends Widget {
private static $db = array(
"User" => "Varchar",
"Photoset" => "Varchar",
"Tags" => "Varchar",
"NumberToShow" => "Int"
);
private static $defaults = array(
"NumberToShow" => 8
);
private static $title = "Photos";
private static $cmsTitle = "Flickr Photos";
private static $description = "Shows flickr photos.";
public function Photos() {
Requirements::javascript(THIRDPARTY_DIR . "/prototype/prototype.js");
Requirements::javascript(THIRDPARTY_DIR . "/scriptaculous/effects.js");
Requirements::javascript("mashups/javascript/lightbox.js");
Requirements::css("mashups/css/lightbox.css");
$flickr = new FlickrService();
if($this->Photoset == "") {
$photos = $flickr->getPhotos($this->Tags, $this->User, $this->NumberToShow, 1);
} else {
$photos = $flickr->getPhotoSet($this->Photoset, $this->User, $this->NumberToShow, 1);
}
$output = new ArrayList();
foreach($photos->PhotoItems as $photo) {
$output->push(new ArrayData(array(
"Title" => $photo->title,
"Link" => "http://farm1.static.flickr.com/" . $photo->image_path .".jpg",
"Image" => "http://farm1.static.flickr.com/" .$photo->image_path. "_s.jpg"
)));
}
return $output;
}
public function getCMSFields() {
return new FieldList(
new TextField("User", "User"),
new TextField("PhotoSet", "Photo Set"),
new TextField("Tags", "Tags"),
new NumericField("NumberToShow", "Number to Show")
);
}
}
**FlickrWidget.ss**
:::ss
<% control Photos %>
<a href="$Link" rel="lightbox" title="$Title"><img src="$Image" alt="$Title" /></a>
<% end_control %>
## Releasing a widget ## Releasing a widget
@ -205,7 +82,7 @@ You need to finish off / change:
### Rendering a $Widget Individually ### Rendering a $Widget Individually
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 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
define a merge variable in the Page Controller and include it in the Page Template. define a merge variable in the Page Controller and include it in the Page Template.
This example creates an RSSWidget with the SilverStripe blog feed. This example creates an RSSWidget with the SilverStripe blog feed.
@ -222,7 +99,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 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: is pre-defined at `framework/templates/WidgetHolder.ss` and simply consists of:
:::ss :::ss
<div class="WidgetHolder"> <div class="WidgetHolder">
@ -275,21 +152,21 @@ sure that your controller follows the usual naming conventions, and it will be a
'TestValue' => 'Text' 'TestValue' => 'Text'
); );
} }
class MyWidget_Controller extends WidgetController { class MyWidget_Controller extends WidgetController {
public function MyFormName() { public function MyFormName() {
return new Form( return new Form(
$this, $this,
'MyFormName', 'MyFormName',
new FieldList( new FieldList(
new TextField('TestValue') new TextField('TestValue')
), ),
new FieldList( new FieldList(
new FormAction('doAction') new FormAction('doAction')
) )
); );
} }
public function doAction($data, $form) { public function doAction($data, $form) {
// $this->widget points to the widget // $this->widget points to the widget
} }
@ -319,7 +196,7 @@ Page class). One way to fix this is to comment out line 30 in BlogHolder.php and
:::php :::php
<?php <?php
class BlogHolder extends Page { class BlogHolder extends Page {
........ ........
static $has_one = array( static $has_one = array(
// "Sidebar" => "WidgetArea", COMMENT OUT // "Sidebar" => "WidgetArea", COMMENT OUT
@ -329,7 +206,7 @@ Page class). One way to fix this is to comment out line 30 in BlogHolder.php and
$fields = parent::getCMSFields(); $fields = parent::getCMSFields();
$fields->removeFieldFromTab("Root.Content","Content"); $fields->removeFieldFromTab("Root.Content","Content");
// $fields->addFieldToTab("Root.Widgets", new WidgetAreaEditor("Sidebar")); COMMENT OUT // $fields->addFieldToTab("Root.Widgets", new WidgetAreaEditor("Sidebar")); COMMENT OUT
........ ........

View File

@ -0,0 +1,5 @@
# Developer Tools
Get the dependencies by running `npm install`.
After making changes to SCSS files, run the build script `npm run build`. This will compile everything for you and output minified CSS files to the `css` directory.

158
docs/en/getting-started.md Normal file
View File

@ -0,0 +1,158 @@
# Getting Started
The easiest way to install is by using [Composer](https://getcomposer.org):
```sh
$ composer require silverstripe/widgets
```
You'll also need to run `dev/build`.
### Installation
Install the module through [composer](http://getcomposer.org):
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`:
:::yml
Page:
extensions:
- WidgetPageExtension
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_<widget-name>/`. 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 {
...
private static $has_one = array(
"MyWidgetArea" => "WidgetArea",
);
public function getCMSFields() {
$fields = parent::getCMSFields();
$fields->addFieldToTab("Root.Widgets", new WidgetAreaEditor("MyWidgetArea"));
return $fields;
}
}
In this case, you need to alter your templates to include the `$MyWidgetArea` placeholder.
## Writing your own widgets
To create a Widget you need at least three files - a php file containing the class, a template file of the same name and
a config file called *_config.php* (if you dont need any config options for the widget to work then you can make it
blank). Each widget should be in its own folder like widgets_widgetName/
After installing or creating a new widget, **make sure to run db/build?flush=1** at the end of the URL, *before*
attempting to use it.
The class should extend the Widget class, and must specify three config variables:
* `title`: The title that will appear in the rendered widget (eg Photos). This can be customised by the CMS admin
* `cmsTitle`: a more descriptive title that will appear in the cms editor (eg Flickr Photos)
* `description`: a short description that will appear in the cms editor (eg This widget shows photos from
Flickr). The class may also specify functions to be used in the template like a page type can.
If a Widget has configurable options, then it can specify a number of database fields to store these options in via the
static $db array, and also specify a getCMSFields function that returns a !FieldList, much the same way as a page type
does.
An example widget is below:
**FlickrWidget.php**
:::php
<?php
class FlickrWidget extends Widget {
private static $db = array(
"User" => "Varchar",
"Photoset" => "Varchar",
"Tags" => "Varchar",
"NumberToShow" => "Int"
);
private static $defaults = array(
"NumberToShow" => 8
);
private static $title = "Photos";
private static $cmsTitle = "Flickr Photos";
private static $description = "Shows flickr photos.";
public function Photos() {
Requirements::javascript(THIRDPARTY_DIR . "/prototype/prototype.js");
Requirements::javascript(THIRDPARTY_DIR . "/scriptaculous/effects.js");
Requirements::javascript("mashups/javascript/lightbox.js");
Requirements::css("mashups/css/lightbox.css");
$flickr = new FlickrService();
if($this->Photoset == "") {
$photos = $flickr->getPhotos($this->Tags, $this->User, $this->NumberToShow, 1);
} else {
$photos = $flickr->getPhotoSet($this->Photoset, $this->User, $this->NumberToShow, 1);
}
$output = new ArrayList();
foreach($photos->PhotoItems as $photo) {
$output->push(new ArrayData(array(
"Title" => $photo->title,
"Link" => "http://farm1.static.flickr.com/" . $photo->image_path .".jpg",
"Image" => "http://farm1.static.flickr.com/" .$photo->image_path. "_s.jpg"
)));
}
return $output;
}
public function getCMSFields() {
return new FieldList(
new TextField("User", "User"),
new TextField("PhotoSet", "Photo Set"),
new TextField("Tags", "Tags"),
new NumericField("NumberToShow", "Number to Show")
);
}
}
**FlickrWidget.ss**
:::ss
<% control Photos %>
<a href="$Link" rel="lightbox" title="$Title"><img src="$Image" alt="$Title" /></a>
<% end_control %>

24
docs/en/introduction.md Normal file
View File

@ -0,0 +1,24 @@
# Introduction
[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/)
[![Build Status](http://img.shields.io/travis/silverstripe/silverstripe-widgets.svg?style=flat-square)](https://travis-ci.org/silverstripe/silverstripe-widgets)
[![Code Quality](http://img.shields.io/scrutinizer/g/silverstripe/silverstripe-widgets.svg?style=flat-square)](https://scrutinizer-ci.com/g/silverstripe/silverstripe-widgets)
[![Version](http://img.shields.io/packagist/v/silverstripe/silverstripe-widgets.svg?style=flat-square)](https://packagist.org/packages/silverstripe/silverstripe-widgets)
[![License](http://img.shields.io/packagist/l/silverstripe/silverstripe-widgets.svg?style=flat-square)](LICENSE.md)
## Share Links
The generated share links have a public key and hash. There can be any number of share links per-page, but all share links are unique, and cannot be used to gain access to pages other than the one each link was created for.
## Sections
- [Getting Started](getting-started.md)
- [Developer Tools](developer-tools.md)
## Questions
This module was created by [SilverStripe](https://twitter.com/silverstripe). You can ask questions on Twitter.
You can report bugs or request features on [GitHub](https://github.com/silverstripe/silverstripe-widgets/issues).