diff --git a/admin/templates/Includes/ModelAdmin_Results.ss b/admin/templates/Includes/ModelAdmin_Results.ss
deleted file mode 100644
index a1882ae64..000000000
--- a/admin/templates/Includes/ModelAdmin_Results.ss
+++ /dev/null
@@ -1,5 +0,0 @@
-<% if Results %>
- $Form
-<% else %>
-
-<% end_if %>
\ No newline at end of file
diff --git a/admin/templates/Includes/ModelAdmin_Tools.ss b/admin/templates/Includes/ModelAdmin_Tools.ss
index a374438c8..3ea0341a3 100644
--- a/admin/templates/Includes/ModelAdmin_Tools.ss
+++ b/admin/templates/Includes/ModelAdmin_Tools.ss
@@ -1,33 +1,12 @@
-
+
\ No newline at end of file
diff --git a/docs/en/changelogs/3.0.0.md b/docs/en/changelogs/3.0.0.md
index 7c5f15155..31aa52cd9 100644
--- a/docs/en/changelogs/3.0.0.md
+++ b/docs/en/changelogs/3.0.0.md
@@ -37,7 +37,8 @@ unfortunately there is no clear upgrade path for every interface detail.
As a starting point, have a look at the new templates in `cms/templates`
and `sapphire/admin/templates`, as well as the new [jQuery.entwine](https://github.com/hafriedlander/jquery.entwine)
based JavaScript logic. Have a look at the new ["Extending the CMS" guide](../howto/extending-the-cms),
-["CSS" guide](../topics/css) and ["JavaScript" guide](../topics/javascript) to get you started.
+["CSS" guide](../topics/css), ["JavaScript" guide](../topics/javascript) and
+["CMS Architecture" guide](/reference/cms-architecture) to get you started.
### New tree library ###
@@ -60,6 +61,17 @@ which will help users understand the new "Add page" dialog.
For example, a `TeamPage` type could be described as "Lists all team members, linking to their profiles".
Note: This property is optional (defaults to an empty string), but its usage is highly encouraged.
+### New ModelAdmin interface, removed sub-controllers
+
+ModelAdmin has been substanially rewritten to natively support the `[api:GridField]` API
+for more flexible data presentation (replacing `[api:ComplexTableField]`),
+and the `[api:DataList]` API for more expressive querying.
+
+If you have overwritten any methods in the class, customized templates,
+or implemented your own `$collection_controller_class`/`$record_controller_class` controllers,
+please refer to the new [ModelAdmin documentation](/reference/modeladmin)
+on details for how to achieve the same goals in the new class.
+
### Stylesheet preprocessing via SCSS and the "compass" module ###
CSS files in the `cms` and `sapphire/admin` modules are now generated through
diff --git a/docs/en/reference/modeladmin.md b/docs/en/reference/modeladmin.md
index 4e81868fc..62ce13aab 100644
--- a/docs/en/reference/modeladmin.md
+++ b/docs/en/reference/modeladmin.md
@@ -2,111 +2,221 @@
## Introduction
-*Replaces GenericDataAdmin in Silverstripe 2.3*
+Provides a simple way to utilize the SilverStripe CMS UI with your own data models,
+and create searchable list and edit views of them, and even providing import and export of your data.
-The ModelAdmin provides a simple way to utilize the SilverStripe CMS UI with your own custom data models. The
-ModelAdmin uses the `[api:DataObject]`'s Scaffolding to create the search fields, forms, and displayed data within the
-CMS.
+It uses the framework's knowledge about the model to provide sensible defaults,
+allowing you to get started in a couple of lines of code,
+while still providing a solid base for customization.
-In order to customize the ModelAdmin CMS interface you will need to understand how `[api:DataObject]` works.
+The interface is mainly powered by the `[GridField](/topics/grid-field)` class,
+which can also be used in other CMS areas (e.g. to manage a relation on a `SiteTree`
+record in the standard CMS interface).
-## Requirements
+## Setup
-*Requires Silverstripe 2.3*
-
-## Usage
-
-### Step 1
-Extend ModelAdmin with a custom class for your admin area, and edit the `$managed_models` property with the list of
-data objects you want to scaffold an interface for:
-
- :::php
- class MyCatalogAdmin extends ModelAdmin {
-
- public static $managed_models = array( //since 2.3.2
- 'Product',
- 'Category'
- );
-
- static $url_segment = 'products'; // will be linked as /admin/products
- static $menu_title = 'My Product Admin';
-
- }
-
-
-To add the ModelAdmin to your CMS menu, you simply need to define a couple of statics on your ModelAdmin subclass. See
-`[api:LeftAndMain]` on how to make your menu title translatable.
-
-
-### Step 2
-Add a `$searchable_fields` (See `[api:ModelAdmin::$searchable_fields]`) property to your data
-models, to define the fields and filters for the search interface:
-
-Datamodel `Product`:
+Let's assume we want to manage a simple product listing as a sample data model:
+A product can have a name, price, and a category.
:::php
class Product extends DataObject {
-
- static $db = array(
- 'Name' => 'Varchar',
- 'ProductCode' => 'Varchar',
- 'Description' => 'Text',
- 'Price' => 'Currency'
- );
-
- static $has_one = array(
- 'Category' => 'Category'
- );
-
- static $searchable_fields = array(
- 'Name',
- 'ProductCode'
- );
-
+ static $db = array('Name' => 'Varchar', 'ProductCode' => 'Varchar', 'Price' => 'Currency');
+ static $has_one = array('Category' => 'Category');
+ }
+ class Category extends DataObject {
+ static $db = array('Title' => 'Text');
+ static $has_many = array('Products' => 'Product');
}
-
-Datamodel `Category`:
+To create your own `ModelAdmin`, simply extend the base class,
+and edit the `$managed_models` property with the list of
+data objects you want to scaffold an interface for.
+The class can manage multiple models in parallel, if required.
+We'll name it `MyAdmin`, but the class name can be anything you want.
:::php
- 'Text'
+ class MyAdmin extends ModelAdmin {
+ public static $managed_models = array('Product','Category'); // Can manage multiple models
+ static $url_segment = 'products'; // Linked as /admin/products/
+ static $menu_title = 'My Product Admin';
+ }
+
+This will automatically add a new menu entry to the CMS, and you're ready to go!
+Try opening http://localhost/admin/products/?flush=all.
+
+## Search Fields
+
+ModelAdmin uses the `[SearchContext](/reference/searchcontext)` class to provide
+a search form, as well as get the searched results. Every DataObject can have its own context,
+based on the fields which should be searchable. The class makes a guess at how those fields
+should be searched, e.g. showing a checkbox for any boolean fields in your `$db` definition.
+
+To remove, add or modify searchable fields, define a new `[$searchable_fields](api:DataObject::$searchable_fields)`
+static on your model class (see `[SearchContext](/reference/searchcontext)` docs for details).
+
+ :::php
+ class Product extends DataObject {
+ // ...
+ static $searchable_fields = array(
+ 'Name',
+ 'ProductCode'
+ // leaves out the 'Price' field, removing it from the search
);
}
- ?>
+For a more sophisticated customization, for example configuring the form fields
+for the search form, override `[api:DataObject->getCustomSearchContext()]` on your model class.
-### Step 3
-You can now log in to the main CMS admin and manage your data objects, with no extra implementation required.
+## Result Columns
-
+The results are shown in a tabular listing, powered by the `[GridField](/topics/grid-field)`,
+more specifically the `[api:GridFieldDataColumns]` component.
+It looks for a `[api:DataObject::$summary_fields]` static on your model class,
+where you can add or remove columns, or change their title.
-
+ :::php
+ class Product extends DataObject {
+ // ...
+ static $summary_fields = array(
+ 'Name' => 'Name',
+ 'Price' => 'Cost', // renames the column to "Cost"
+ // leaves out the 'ProductCode' field, removing the column
+ );
+ }
-### Note about has_one
+## Results Customization
-Scaffolding **has_one** relationships in your ModelAdmin relies on a column in the related model to be named **Title**
-or **Name** of a string type (varchar, char, etc). These will be pulled in to the dropdown when creating a new object.
+The results are retrieved from `[api:SearchContext->getResults()]`,
+based on the parameters passed through the search form.
+If no search parameters are given, the results will show every record.
+Results are a `[api:DataList]` instance, so can be customized by additional
+SQL filters, joins, etc (see [datamodel](/topics/datamodel) for more info).
-If you are seeing a list of ID#s when creating new objects, ensure you have one of those two in the related model.
+For example, we might want to exclude all products without prices in our sample `MyAdmin` implementation.
-## Searchable Fields
+ :::php
+ class MyAdmin extends ModelAdmin {
+ // ...
+ function getList() {
+ $list = parent::getList();
+ // Always limit by model class, in case you're managing multiple
+ if($this->modelClass == 'Product') {
+ $list->exclude('Price', '0');
+ }
+ return $list;
+ }
+ }
-You can customize the fields which are searchable for each managed DataObject class, as well as the ways in which the
-fields are searched (e.g. "partial match", "fulltext", etc.) using `$searchable_fields`.
+You can also customize the search behaviour directly on your `ModelAdmin` instance.
+For example, we might want to have a checkbox which limits search results to expensive products (over $100).
- * See `[api:DataObject]`
+ :::php
+ class MyAdmin extends ModelAdmin {
+ // ...
+ function getSearchContext() {
+ $context = parent::getSearchContext();
+ if($this->modelClass == 'Product') {
+ $context->getFields()->push(new CheckboxField('q[ExpensiveOnly]', 'Only expensive stuff'));
+ }
+ return $context;
+ }
+ function getList() {
+ $list = parent::getList();
+ $params = $this->request->requestVar('q'); // use this to access search parameters
+ if($this->modelClass == 'Product' && isset($params['ExpensiveOnly']) && $params['ExpensiveOnly']) {
+ $list->exclude('Price:LessThan', '100');
+ }
+ return $list;
+ }
+ }
-
+## Managing Relationships
-## Summary Fields
+Has-one relationships are simply implemented as a `[api:DropdownField]` by default.
+Consider replacing it with a more powerful interface in case you have many records
+(through customizing `[api:DataObject->getCMSFields]`).
-Summary Fields are the columns which are shown in the `[api:TableListField]` when viewing DataObjects. These can be
-customized for each `[api:DataObject]`'s search results using `$summary_fields`.
+Has-many and many-many relationships are usually handled via the `[GridField](/topics/grid-field)` class,
+more specifically the `[api:GridFieldAddExistingAutocompleter]` and `[api:GridFieldRelationDelete]` components.
+They provide a list/detail interface within a single record edited in your ModelAdmin.
- * See `[api:DataObject]`
+## Permissions
+
+`ModelAdmin` respects the permissions set on the model, through methods on your `DataObject` implementations:
+`canView()`, `canEdit()`, `canDelete()`, and `canCreate`.
+
+In terms of access control to the interface itself, every `ModelAdmin` subclass
+creates its own "[permission code](/reference/permissions)", which can be assigned
+to groups through the `admin/security` management interface. To further limit
+permission, either override checks in `ModelAdmin->init()`, or define
+more permission codes through the `ModelAdmin::$required_permission_codes` static.
+
+## Data Import
+
+The `ModelAdmin` class provides import of CSV files through the `[api:CsvBulkLoader]` API.
+which has support for column mapping, updating existing records,
+and identifying relationships - so its a powerful tool to get your data into a SilverStripe database.
+
+By default, each model management interface allows uploading a CSV file
+with all columns autodetected. To override with a more specific importer implementation,
+use the `[api:ModelAdmin::$model_importers] static.
+
+## Data Export
+
+Export is also available, although at the moment only to the CSV format,
+through a button at the end of a results list. You can also export search results.
+It is handled through the `[api:GridFieldExportButton]` component.
+
+To customize the exported columns, override the edit form implementation in your `ModelAdmin`:
+
+ :::php
+ class MyAdmin extends ModelAdmin {
+ // ...
+ function getEditForm($id = null) {
+ $form = parent::getEditForm($id);
+ if($this->modelClass == 'Product') {
+ $grid = $form->Fields()->fieldByName('Product');
+ $grid->getConfig()->getComponentByType('GridFieldExporter')
+ ->setExportColumns(array(
+ // Excludes 'ProductCode' from the export
+ 'Name' => 'Name',
+ 'Price' => 'Price'
+ ));
+ }
+ return $form;
+ }
+ }
+
+## Extending existing ModelAdmins
+
+Sometimes you'll work with ModelAdmins from other modules, e.g. the product management
+of an ecommerce module. To customize this, you can always subclass. But there's
+also another tool at your disposal: The `[api:Extension]` API.
+
+ :::php
+ class MyAdminExtension extends Extension {
+ function updateEditForm(&$form) {
+ $form->Fields()->push(/* ... */)
+ }
+ }
+
+ // mysite/_config.php
+ Object::add_extension('MyAdmin', 'MyAdminExtension');
+
+The following extension points are available: `updateEditForm()`, `updateSearchContext()`,
+`updateSearchForm()`, `updateList()`, `updateImportForm`.
+
+## Customizing the interface
+
+Interfaces like `ModelAdmin` can be customized in many ways:
+
+ * JavaScript behaviour (e.g. overwritten jQuery.entwine rules)
+ * CSS styles
+ * HTML markup through templates
+
+In general, use your `ModelAdmin->init()` method to add additional requirements
+through the `[Requirements](/reference/requirements)` API.
+For an introduction how to customize the CMS templates, see our [CMS Architecture Guide](/reference/cms-architecture).
## Related
diff --git a/docs/en/reference/searchcontext.md b/docs/en/reference/searchcontext.md
index 53abd480f..afd6212c1 100644
--- a/docs/en/reference/searchcontext.md
+++ b/docs/en/reference/searchcontext.md
@@ -15,10 +15,6 @@ the $fields constructor parameter.
`[api:SearchContext]` is mainly used by `[api:ModelAdmin]`, our generic data administration interface. Another
implementation can be found in generic frontend search forms through the [genericviews](http://silverstripe.org/generic-views-module) module.
-## Requirements
-
-* *SilverStripe 2.3*
-
## Usage
Getting results
diff --git a/forms/FormScaffolder.php b/forms/FormScaffolder.php
index 49b4d7560..7c8424b66 100644
--- a/forms/FormScaffolder.php
+++ b/forms/FormScaffolder.php
@@ -123,22 +123,17 @@ class FormScaffolder extends Object {
$this->obj->fieldLabel($relationship)
);
}
- $relationshipFields = singleton($component)->summaryFields();
-
- $foreignKey = $this->obj->getRemoteJoinField($relationship);
- $fieldClass = (isset($this->fieldClasses[$relationship])) ? $this->fieldClasses[$relationship] : 'ComplexTableField';
- $ctf = new $fieldClass(
- $this,
+ $fieldClass = (isset($this->fieldClasses[$relationship])) ? $this->fieldClasses[$relationship] : 'GridField';
+ $grid = Object::create($fieldClass,
$relationship,
- null,
- $relationshipFields,
- "getCMSFields"
+ $this->obj->fieldLabel($relationship),
+ $this->obj->$relationship(),
+ GridFieldConfig_RelationEditor::create()
);
- $ctf->setPermissions(TableListField::permissions_for_object($component));
if($this->tabbed) {
- $fields->addFieldToTab("Root.$relationship", $ctf);
+ $fields->addFieldToTab("Root.$relationship", $grid);
} else {
- $fields->push($ctf);
+ $fields->push($grid);
}
}
}
@@ -152,22 +147,17 @@ class FormScaffolder extends Object {
);
}
- $relationshipFields = singleton($component)->summaryFields();
- $fieldClass = (isset($this->fieldClasses[$relationship])) ? $this->fieldClasses[$relationship] : 'ComplexTableField';
- $ctf = new $fieldClass(
- $this,
+ $fieldClass = (isset($this->fieldClasses[$relationship])) ? $this->fieldClasses[$relationship] : 'GridField';
+ $grid = Object::create($fieldClass,
$relationship,
+ $this->obj->fieldLabel($relationship),
$this->obj->$relationship(),
- $relationshipFields,
- "getCMSFields"
+ GridFieldConfig_RelationEditor::create()
);
-
- $ctf->setPermissions(TableListField::permissions_for_object($component));
- $ctf->popupClass = "ScaffoldingComplexTableField_Popup";
if($this->tabbed) {
- $fields->addFieldToTab("Root.$relationship", $ctf);
+ $fields->addFieldToTab("Root.$relationship", $grid);
} else {
- $fields->push($ctf);
+ $fields->push($grid);
}
}
}
diff --git a/forms/ScaffoldingComplexTableField.php b/forms/ScaffoldingComplexTableField.php
deleted file mode 100644
index 67aa32318..000000000
--- a/forms/ScaffoldingComplexTableField.php
+++ /dev/null
@@ -1,93 +0,0 @@
-dataObject = $dataObject;
-
- Requirements::clear();
-
- $actions = new FieldList();
- if(!$readonly) {
- $actions->push(
- $saveAction = new FormAction("saveComplexTableField", "Save")
- );
- $saveAction->addExtraClass('save');
- }
-
- $fields->push(new HiddenField("ComplexTableField_Path", Director::absoluteBaseURL()));
-
- parent::__construct($controller, $name, $fields, $validator, $readonly, $dataObject);
- }
-
- /**
- * Handle a generic action passed in by the URL mapping.
- *
- * @param SS_HTTPRequest $request
- */
- public function handleAction($request) {
- $action = str_replace("-","_",$request->param('Action'));
- if(!$this->action) $this->action = 'index';
-
- if($this->checkAccessAction($action)) {
- if($this->hasMethod($action)) {
- $result = $this->$action($request);
-
- // Method returns an array, that is used to customise the object before rendering with a template
- if(is_array($result)) {
- return $this->getViewer($action)->process($this->customise($result));
-
- // Method returns a string / object, in which case we just return that
- } else {
- return $result;
- }
-
- // There is no method, in which case we just render this object using a (possibly alternate) template
- } else {
- return $this->getViewer($action)->process($this);
- }
- } else {
- return $this->httpError(403, "Action '$action' isn't allowed on class $this->class");
- }
- }
-
- /**
- * Action to render results for an autocomplete filter.
- *
- * @param SS_HTTPRequest $request
- * @return void
- */
- function filter($request) {
- //$model = singleton($this->modelClass);
- $context = $this->dataObject->getDefaultSearchContext();
- $value = $request->getVar('q');
- $results = $context->getResults(array("Name"=>$value));
- header("Content-Type: text/plain");
- foreach($results as $result) {
- echo $result->Name . "\n";
- }
- }
-
- /**
- * Action to populate edit box with a single data object via Ajax query
- */
- function record($request) {
- $type = $request->getVar('type');
- $value = $request->getVar('value');
- if ($type && $value) {
- $record = DataObject::get_one($this->dataObject->class, "\"$type\" = '$value'");
- header("Content-Type: text/plain");
- echo json_encode(array("record"=>$record->toMap()));
- }
- }
-
-}
diff --git a/javascript/ScaffoldComplexTableField.js b/javascript/ScaffoldComplexTableField.js
deleted file mode 100644
index 81ba45bf7..000000000
--- a/javascript/ScaffoldComplexTableField.js
+++ /dev/null
@@ -1,24 +0,0 @@
-window.onload = function() {
-
- resourcePath = jQuery('form').attr('action');
-
- jQuery("fieldset input:first").attr('autocomplete', 'off').autocomplete({list: ["mark rickerby", "maxwell sparks"]});
-
- jQuery("fieldset input:first").bind('activate.autocomplete', function(e){
-
- type = jQuery("fieldset input:first").attr('name');
- value = jQuery("fieldset input:first").val();
-
- jQuery.getJSON(resourcePath + '/record', {'type':type, 'value':value}, function(data) {
- jQuery('form input').each(function(i, elm){
- if(elm.name in data.record) {
- val = data.record[elm.name];
- if (val != null) elm.setAttribute('value', val);
- }
- });
- });
-
- });
-
-
-};
\ No newline at end of file
diff --git a/model/fieldtypes/ForeignKey.php b/model/fieldtypes/ForeignKey.php
index e298242e3..611464ca0 100644
--- a/model/fieldtypes/ForeignKey.php
+++ b/model/fieldtypes/ForeignKey.php
@@ -37,8 +37,15 @@ class ForeignKey extends Int {
$field = new UploadField($relationName, $title);
} else {
$titleField = (singleton($hasOneClass)->hasField('Title')) ? "Title" : "Name";
- $map = DataList::create($hasOneClass)->map("ID", $titleField);
- $field = new DropdownField($this->name, $title, $map, null, null, ' ');
+ $list = DataList::create($hasOneClass);
+ // Don't scaffold a dropdown for large tables, as making the list concrete
+ // might exceed the available PHP memory in creating too many DataObject instances
+ if($list->count() < 100) {
+ $field = new DropdownField($this->name, $title, $list->map("ID", $titleField), null, null, ' ');
+ } else {
+ $field = new NumericField($this->name, $title);
+ }
+
}
return $field;