DOCS: Add some documentation to ModelAdmin for common use-cases. Fixes #6530

This commit is contained in:
Matt Peel 2017-01-20 10:52:49 +13:00
parent f15f87b851
commit cbf64d93c2
No known key found for this signature in database
GPG Key ID: 37216222E10987D1
2 changed files with 51 additions and 14 deletions

View File

@ -89,7 +89,7 @@ class LeftAndMain extends Controller implements PermissionProvider
/** /**
* @config * @config
* @var string * @var string Used by {@link AdminRootController} to augment Director route rules for sub-classes of LeftAndMain
*/ */
private static $url_rule = '/$Action/$ID/$OtherID'; private static $url_rule = '/$Action/$ID/$OtherID';
@ -1605,9 +1605,9 @@ class LeftAndMain extends Controller implements PermissionProvider
} }
/** /**
* Calls {@link SiteTree->getCMSFields()} * Calls {@link SiteTree->getCMSFields()} by default to determine the form fields to display.
* *
* @param Int $id * @param int $id
* @param FieldList $fields * @param FieldList $fields
* @return Form * @return Form
*/ */

View File

@ -47,7 +47,9 @@ use SilverStripe\View\SSViewer;
*/ */
abstract class ModelAdmin extends LeftAndMain abstract class ModelAdmin extends LeftAndMain
{ {
/**
* @inheritdoc
*/
private static $url_rule = '/$ModelClass/$Action'; private static $url_rule = '/$ModelClass/$Action';
/** /**
@ -92,7 +94,7 @@ abstract class ModelAdmin extends LeftAndMain
); );
/** /**
* @var String * @var string The {@link \SilverStripe\ORM\DataObject} sub-class being managed during this object's lifetime.
*/ */
protected $modelClass; protected $modelClass;
@ -124,15 +126,17 @@ abstract class ModelAdmin extends LeftAndMain
private static $model_importers = null; private static $model_importers = null;
/** /**
* Amount of results showing on a single page.
*
* @config * @config
* @var int * @var int Amount of results to show per page
*/ */
private static $page_length = 30; private static $page_length = 30;
/** /**
* Initialize the model admin interface. Sets up embedded jquery libraries and requisite plugins. * Initialize the model admin interface. Sets up embedded jquery libraries and requisite plugins.
*
* Sets the `modelClass` field which determines which of the {@link DataObject} objects will have visible data. This
* is determined by the URL (with the first slug being the name of the DataObject class to represent. If this class
* is loaded without any URL, we pick the first DataObject from the list of {@link self::$managed_models}.
*/ */
protected function init() protected function init()
{ {
@ -153,6 +157,12 @@ abstract class ModelAdmin extends LeftAndMain
} }
} }
/**
* Overrides {@link \SilverStripe\Admin\LeftAndMain} to ensure the active model class (the DataObject we are
* currently viewing) is included in the URL.
*
* @inheritdoc
*/
public function Link($action = null) public function Link($action = null)
{ {
if (!$action) { if (!$action) {
@ -161,6 +171,15 @@ abstract class ModelAdmin extends LeftAndMain
return parent::Link($action); return parent::Link($action);
} }
/**
* Produces an edit form that includes a default {@link \SilverStripe\Forms\GridField\GridField} for the currently
* active {@link \SilverStripe\ORM\DataObject}. The GridField will show data from the currently active `modelClass`
* only (see {@link self::init()}).
*
* @param int|null $id
* @param \SilverStripe\Forms\FieldList $fields
* @return \SilverStripe\Forms\Form A Form object with one tab per {@link \SilverStripe\Forms\GridField\GridField}
*/
public function getEditForm($id = null, $fields = null) public function getEditForm($id = null, $fields = null)
{ {
$list = $this->getList(); $list = $this->getList();
@ -221,7 +240,7 @@ abstract class ModelAdmin extends LeftAndMain
} }
/** /**
* @return SearchContext * @return \SilverStripe\ORM\Search\SearchContext
*/ */
public function getSearchContext() public function getSearchContext()
{ {
@ -241,7 +260,7 @@ abstract class ModelAdmin extends LeftAndMain
} }
/** /**
* @return Form|bool * @return \SilverStripe\Forms\Form|bool
*/ */
public function SearchForm() public function SearchForm()
{ {
@ -275,6 +294,26 @@ abstract class ModelAdmin extends LeftAndMain
return $form; return $form;
} }
/**
* You can override how ModelAdmin returns DataObjects by either overloading this method, or defining an extension
* to ModelAdmin that implements the `updateList` method (and takes a {@link \SilverStripe\ORM\DataList} as the
* first argument).
*
* For example, you might want to do this if this particular ModelAdmin should only ever show objects where an
* Archived flag is set to false. That would be best done as an extension, for example:
*
* <code>
* public function updateList(\SilverStripe\ORM\DataList $list)
* {
* return $list->filter('Archived', false);
* }
* </code>
*
* If you want to use the built-in search form that ModelAdmin provides, you should also make amends to the DataList
* returned by this method, rather than creating a new DataList.
*
* @return \SilverStripe\ORM\DataList
*/
public function getList() public function getList()
{ {
$context = $this->getSearchContext(); $context = $this->getSearchContext();
@ -300,10 +339,8 @@ abstract class ModelAdmin extends LeftAndMain
/** /**
* Returns managed models' create, search, and import forms
* @uses SearchContext * @return \SilverStripe\ORM\ArrayList An ArrayList of all managed models to build the tabs for this ModelAdmin
* @uses SearchFilter
* @return SS_List of forms
*/ */
protected function getManagedModelTabs() protected function getManagedModelTabs()
{ {