OSS-905 Moved docs to docs/en/
This commit is contained in:
Shoaib Ali
parent
eee39bca4e
commit
4e5f1bf3e2
167
README.md
167
README.md
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
[](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
|
||||
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
|
||||
|
||||
|
||||
### Installation
|
||||
|
||||
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.
|
||||
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`:
|
||||
You'll also need to run `dev/build`.
|
||||
|
||||
:::yml
|
||||
Page:
|
||||
extensions:
|
||||
- WidgetPageExtension
|
||||
## Documentation
|
||||
|
||||
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.
|
||||
See the [docs/en](docs/en/introduction.md) folder.
|
||||
|
||||
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.
|
||||
## Versioning
|
||||
|
||||
### 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.
|
||||
|
||||
* 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
|
||||
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.
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
### 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 %>
|
||||
Please [create an issue](http://github.com/silverstripe/silverstripe-widgets/issues) for any bugs you've found, or features you're missing.
|
||||
|
||||
|
||||
## Releasing a widget
|
||||
|
|
@ -205,7 +82,7 @@ You need to finish off / change:
|
|||
### 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
|
||||
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.
|
||||
|
||||
|
|
@ -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
|
||||
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
|
||||
<div class="WidgetHolder">
|
||||
|
|
@ -275,21 +152,21 @@ sure that your controller follows the usual naming conventions, and it will be a
|
|||
'TestValue' => 'Text'
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
class MyWidget_Controller extends WidgetController {
|
||||
public function MyFormName() {
|
||||
return new Form(
|
||||
$this,
|
||||
'MyFormName',
|
||||
$this,
|
||||
'MyFormName',
|
||||
new FieldList(
|
||||
new TextField('TestValue')
|
||||
),
|
||||
),
|
||||
new FieldList(
|
||||
new FormAction('doAction')
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
public function doAction($data, $form) {
|
||||
// $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
|
||||
class BlogHolder extends Page {
|
||||
|
||||
|
||||
........
|
||||
static $has_one = array(
|
||||
// "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->removeFieldFromTab("Root.Content","Content");
|
||||
// $fields->addFieldToTab("Root.Widgets", new WidgetAreaEditor("Sidebar")); COMMENT OUT
|
||||
|
||||
|
||||
........
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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 %>
|
||||
|
||||
|
|
@ -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/)
|
||||
[](https://travis-ci.org/silverstripe/silverstripe-widgets)
|
||||
[](https://scrutinizer-ci.com/g/silverstripe/silverstripe-widgets)
|
||||
[](https://packagist.org/packages/silverstripe/silverstripe-widgets)
|
||||
[](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).
|
||||
Loading…
Reference in New Issue