DOCS Update docs examples to be 3.1+ relevant (#111)
This commit is contained in:
Daniel Hensby
Ed Chipman
parent
6dc9493e0a
commit
8200c934a0
111
README.md
111
README.md
|
|
@ -1,27 +1,44 @@
|
|||
SortableGridField
|
||||
=================
|
||||
|
||||
[](https://travis-ci.org/UndefinedOffset/SortableGridField) 
|
||||
|
||||
Adds drag and drop functionality to SilverStripe 3's GridField
|
||||
|
||||
## Requirements
|
||||
|
||||
* SilverStripe 3.x
|
||||
|
||||
## Installation
|
||||
|
||||
__Composer (recommended):__
|
||||
|
||||
```
|
||||
composer require undefinedoffset/sortablegridfield
|
||||
```
|
||||
|
||||
If you prefer you may also install manually:
|
||||
* Download the module from here https://github.com/UndefinedOffset/SortableGridField/archive/master.zip
|
||||
* Extract the downloaded archive into your site root so that the destination folder is called SortableGridField, opening the extracted folder should contain _config.php in the root along with other files/folders
|
||||
* Run dev/build?flush=all to regenerate the manifest
|
||||
* Upon entering the cms and using GridFieldSortableRows component for the first time you make need to add ?flush=all to the end of the address to force the templates to regenerate
|
||||
|
||||
* Download the latest release from https://github.com/UndefinedOffset/SortableGridField/releases
|
||||
* Extract the downloaded archive into your site root so that the destination folder is called `SortableGridField`,
|
||||
opening the extracted folder should contain `_config.php` in the root along with other files/folders
|
||||
* Run `dev/build?flush=all` to regenerate the manifest
|
||||
* Upon entering the cms and using `GridFieldSortableRows` component for the first time you make need to add `?flush=all`
|
||||
to the end of the address to force the templates to regenerate
|
||||
|
||||
|
||||
## Usage
|
||||
To enable sorting on a has_many relationship set up an integer field on your data object. Also for has_many relationships make sure to set the $default_sort on the dataobject to this new integer field to ensure that the sort order is applied when the relationship is requested. For many_many relationships you must add a $many_many_extraFields static to the data object defining the relationship, see the SilverStripe documentation for more information on this. If you are using a many_many relationship you will need to do a custom getter to set the sort order of this relationship for use on the front end see below for an example. As well for many_many relationships the name of the GridField *must* be the same as the relationship name other wise error's will occur. For new DataObjects you do not need to increment the Sort order yourself in your DataObject GridFieldSortableRows will automatically do this the next time the grid is displayed.
|
||||
|
||||
To enable sorting on a `has_many` relationship set up an integer field on your data object. Also for `has_many`
|
||||
relationships make sure to set the `$default_sort` on the `DataObject` to this new integer field to ensure that the sort
|
||||
order is applied when the relationship is requested. For `many_many` relationships you must add a
|
||||
`$many_many_extraFields` static to the `DataObject` defining the relationship, see the
|
||||
[SilverStripe documentation](https://docs.silverstripe.org/en/3/developer_guides/model/relations/#many-many)
|
||||
for more information on this. If you are using a `many_many` relationship you will need to do a custom getter to set the
|
||||
sort order of this relationship for use on the front end see below for an example. As well for `many_many` relationships
|
||||
the name of the GridField *must* be the same as the relationship name other wise error's will occur. For new
|
||||
`DataObject`s you do not need to increment the sort order yourself in your `DataObject`, `GridFieldSortableRows` will
|
||||
automatically do this the next time the grid is displayed.
|
||||
|
||||
```php
|
||||
public function getMyManyManyRelationship() {
|
||||
|
|
@ -29,7 +46,6 @@ public function getMyManyManyRelationship() {
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
To enable drag and drop sorting on the grid field add the following to your grid field's config
|
||||
*Grid Field Config*
|
||||
|
||||
|
|
@ -37,60 +53,97 @@ To enable drag and drop sorting on the grid field add the following to your grid
|
|||
$myGridConfig->addComponent(new GridFieldSortableRows('{Column to store sort}'));
|
||||
```
|
||||
|
||||
To move an item to another page drag the row over the respective move to page button which appear on the left and right of the GridField and release.
|
||||
To move an item to another page drag the row over the respective move to page button which appear on the left and right
|
||||
of the GridField and release.
|
||||
|
||||
#### Full code Examples
|
||||
* [has_many relationship] (https://github.com/UndefinedOffset/SortableGridField/blob/master/docs/HasManyExample.md)
|
||||
* [many_many relationship] (https://github.com/UndefinedOffset/SortableGridField/blob/master/docs/ManyManyExample.md)
|
||||
* [ModelAdmin implementation] (https://github.com/UndefinedOffset/SortableGridField/blob/master/docs/ModelAdminExample.md)
|
||||
|
||||
* [has_many relationship](https://github.com/UndefinedOffset/SortableGridField/blob/master/docs/HasManyExample.md)
|
||||
* [many_many relationship](https://github.com/UndefinedOffset/SortableGridField/blob/master/docs/ManyManyExample.md)
|
||||
* [ModelAdmin implementation](https://github.com/UndefinedOffset/SortableGridField/blob/master/docs/ModelAdminExample.md)
|
||||
|
||||
#### Events
|
||||
GridFieldSortableRows provides 4 "events" onBeforeGridFieldRowSort(), onAfterGridFieldRowSort(), onBeforeGridFieldPageSort() and onAfterGridFieldPageSort(). These "events" are passed a clone of the DataList used in GridFieldSortableRows, in the case of page sorting this list has a limit that shows you the current page plus/minus one object. For GridFieldSortableRows that are on ModelAdmin decendents these events are called on the ModelAdmin if they do not have a owner DataObject, if you are using GridFieldSortableRows on a GridField for a DataObject's relationship the events are called on that DataObject.
|
||||
|
||||
`GridFieldSortableRows` provides 4 "events" `onBeforeGridFieldRowSort()`, `onAfterGridFieldRowSort()`,
|
||||
`onBeforeGridFieldPageSort()` and `onAfterGridFieldPageSort()`. These "events" are passed a clone of the `DataList`
|
||||
used in `GridFieldSortableRows`, in the case of page sorting this list has a limit that shows you the current page
|
||||
plus/minus one object. For `GridFieldSortableRows` that are on `ModelAdmin` descendants these events are called on the
|
||||
`ModelAdmin` if they do not have an owner `DataObject`, if you are using `GridFieldSortableRows` on a `GridField` for a
|
||||
`DataObject`'s relationship the events are called on that `DataObject`.
|
||||
|
||||
#### Appending to the top instead of the bottom
|
||||
By default GridFieldSortableRows appends to the bottom of the list for performance on large data sets, however you can set new records to append new records to the top by calling setAppendToTop(true) on your GridFieldSortableRows instance.
|
||||
|
||||
By default `GridFieldSortableRows` appends to the bottom of the list for performance on large data sets, however you can
|
||||
set new records to append new records to the top by calling `setAppendToTop(true)` on your `GridFieldSortableRows`
|
||||
instance.
|
||||
|
||||
```php
|
||||
$myGridConfig->addComponent($sortable=new GridFieldSortableRows('SortOrder'));
|
||||
$myGridConfig->addComponent($sortable = new GridFieldSortableRows('SortOrder'));
|
||||
$sortable->setAppendToTop(true);
|
||||
```
|
||||
|
||||
#### Working with versioned records
|
||||
By default GridFieldSortableRows does not update any other stage for versioned than the base stage. However you can enable this by calling setUpdateVersionedStage() and passing in the name of the stage you want to update along with the base stage. For example passing in "Live" will also update the "Live" stage when any sort happens.
|
||||
|
||||
By default `GridFieldSortableRows` does not update any other stage for versioned than the base stage. However you can
|
||||
enable this by calling `setUpdateVersionedStage()` and passing in the name of the stage you want to update along with
|
||||
the base stage. For example passing in "Live" will also update the "Live" stage when any sort happens.
|
||||
|
||||
```php
|
||||
$myGridConfig->addComponent($sortable=new GridFieldSortableRows('SortOrder'));
|
||||
$myGridConfig->addComponent($sortable = new GridFieldSortableRows('SortOrder'));
|
||||
$sortable->setUpdateVersionedStage('Live');
|
||||
```
|
||||
|
||||
#### Overriding the default relationship name
|
||||
By default the relationship name comes from the name of the GridField, however you can override this lookup by calling setCustomRelationName() and passing in the name of the relationship. This allows for you to have multiple GridFields on the same form interacting with the same many_many list maybe filtered slightly differently.
|
||||
```php
|
||||
$myGridConfig->addComponent($sortable=new GridFieldSortableRows('SortOrder'));
|
||||
$sortable->setCustomRelationName('MyRelationship');
|
||||
|
||||
By default the relationship name comes from the name of the `GridField`, however you can override this lookup by
|
||||
calling `setCustomRelationName()` and passing in the name of the relationship. This allows for you to have multiple
|
||||
`GridFields` on the same form interacting with the same `many_many` list maybe filtered slightly differently.
|
||||
|
||||
```php
|
||||
$myGridConfig->addComponent($sortable = new GridFieldSortableRows('SortOrder'));
|
||||
$sortable->setCustomRelationName('MyRelationship');
|
||||
```
|
||||
|
||||
## Migrating from SilverStripe 2.4 and `DataObjectManager`'s `SortableDataObject`
|
||||
|
||||
## Migrating from SilverStripe 2.4 and Data Object Manager's SortableDataObject
|
||||
SortableGridField is not the same as SortableDataObject, since it is only a component of GridField it does not have the ability to catch the object when it is saved for the first time. So SortableGridField uses 1 as the first sort index because 0 is the default for an integer field/column in the database. For migrations from 2.4 with SortableDataObject you need to setup your DataObject based on the instructions above however you must name your sort column "SortOrder" to maintain your sort indexes defined by SortableDataObject. Then you need to run the following query on the table containing your sort field, for many_many relationships this will be something like {RelationshipClass}_{RelationshipName}. This query will maintain your sort order from SortableDataObject but increment the index by 1 giving it a starting number of 1.
|
||||
`SortableGridField` is not the same as `SortableDataObject`, since it is only a component of `GridField` it does not
|
||||
have the ability to catch the object when it is saved for the first time. So `SortableGridField` uses 1 as the first
|
||||
sort index because 0 is the default for an integer field/column in the database. For migrations from 2.4 with
|
||||
`SortableDataObject` you need to setup your `DataObject` based on the instructions above however you must name your sort
|
||||
column "SortOrder" to maintain your sort indexes defined by `SortableDataObject`. Then you need to run the following
|
||||
query on the table containing your sort field, for `many_many` relationships this will be something like
|
||||
`{RelationshipClass}_{RelationshipName}`. This query will maintain your sort order from `SortableDataObject` but
|
||||
increment the index by 1 giving it a starting number of 1.
|
||||
|
||||
```sql
|
||||
UPDATE YourTable SET SortOrder=SortOrder+1;
|
||||
UPDATE "YourTable" SET "SortOrder" = "SortOrder" + 1;
|
||||
```
|
||||
|
||||
## Reporting an issue
|
||||
When you're reporting an issue please ensure you specify what version of SilverStripe you are using i.e. 3.0.5, 3.1beta3, 3.0-master etc. Also be sure to include any JavaScript or PHP errors you receive, for PHP errors please ensure you include the full stack trace. Also please include your implementation code (where your setting up your grid field) as well as how you produced the issue. You may also be asked to provide some of the classes to aid in re-producing the issue. Stick with the issue, remember that you seen the issue not the maintainer of the module so it may take allot of questions to arrive at a fix or answer.
|
||||
|
||||
When you're reporting an issue please ensure you specify what version of SilverStripe you are using i.e. 3.0.5,
|
||||
3.1beta3, 3.0-master etc. Also be sure to include any JavaScript or PHP errors you receive, for PHP errors please ensure
|
||||
you include the full stack trace. Also please include your implementation code (where your setting up your grid field)
|
||||
as well as how you produced the issue. You may also be asked to provide some of the classes to aid in re-producing the
|
||||
issue. Stick with the issue, remember that you seen the issue not the maintainer of the module so it may take a lot of
|
||||
questions to arrive at a fix or answer.
|
||||
|
||||
### Notes
|
||||
* When using with GridFieldManyRelationHandler make sure that you add GridFieldSortableRows to your config before for example GridFieldManyRelationHandler:
|
||||
|
||||
```php
|
||||
$config->addComponent(new GridFieldSortableRows('SortOrder'), 'GridFieldManyRelationHandler');
|
||||
```
|
||||
* When using with `GridFieldManyRelationHandler` make sure that you add `GridFieldSortableRows` to your config before
|
||||
for example `GridFieldManyRelationHandler`:
|
||||
|
||||
```php
|
||||
$config->addComponent(new GridFieldSortableRows('SortOrder'), 'GridFieldManyRelationHandler');
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
### Translations
|
||||
|
||||
Translations of the natural language strings are managed through a third party translation interface, transifex.com. Newly added strings will be periodically uploaded there for translation, and any new translations will be merged back to the project source code.
|
||||
Translations of the natural language strings are managed through a third party translation interface, transifex.com.
|
||||
Newly added strings will be periodically uploaded there for translation, and any new translations will be merged back to
|
||||
the project source code.
|
||||
|
||||
Please use [https://www.transifex.com/projects/p/silverstripe-sortablegridfield](https://www.transifex.com/projects/p/silverstripe-sortablegridfield) to contribute translations, rather than sending pull requests with YAML files.
|
||||
Please use [https://www.transifex.com/projects/p/silverstripe-sortablegridfield](https://www.transifex.com/projects/p/silverstripe-sortablegridfield)
|
||||
to contribute translations, rather than sending pull requests with YAML files.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,17 @@
|
|||
has_many Example
|
||||
=================
|
||||
Please note this example is written with 3.0.x in mind, if you are using 3.1.x make sure you scope all static properties to private not public.
|
||||
|
||||
```php
|
||||
/*** TestPage.php ***/
|
||||
class TestPage extends Page {
|
||||
public static $has_many=array(
|
||||
'TestObjects'=>'TestObject'
|
||||
private static $has_many = array(
|
||||
'TestObjects' => 'TestObject',
|
||||
);
|
||||
|
||||
public function getCMSFields() {
|
||||
$fields=parent::getCMSFields();
|
||||
$fields = parent::getCMSFields();
|
||||
|
||||
$conf=GridFieldConfig_RelationEditor::create(10);
|
||||
$conf = GridFieldConfig_RelationEditor::create(10);
|
||||
$conf->addComponent(new GridFieldSortableRows('SortOrder'));
|
||||
|
||||
$fields->addFieldToTab('Root.TestObjects', new GridField('TestObjects', 'TestObjects', $this->TestObjects(), $conf));
|
||||
|
|
@ -23,15 +23,15 @@ class TestPage extends Page {
|
|||
|
||||
/*** TestObject.php ***/
|
||||
class TestObject extends DataObject {
|
||||
public static $db=array(
|
||||
'Title'=>'Text',
|
||||
'SortOrder'=>'Int'
|
||||
private static $db = array(
|
||||
'Title' => 'Text',
|
||||
'SortOrder' => 'Int',
|
||||
);
|
||||
|
||||
public static $has_one=array(
|
||||
'Parent'=>'TestPage'
|
||||
private static $has_one = array(
|
||||
'Parent' => 'TestPage',
|
||||
);
|
||||
|
||||
public static $default_sort='SortOrder';
|
||||
private static $default_sort = 'SortOrder';
|
||||
}
|
||||
```
|
||||
|
|
@ -1,24 +1,24 @@
|
|||
many_many Example
|
||||
=================
|
||||
Please note this example is written with 3.0.x in mind, if you are using 3.1.x make sure you scope all static properties to private not public.
|
||||
|
||||
```php
|
||||
/*** TestPage.php ***/
|
||||
class TestPage extends Page {
|
||||
public static $many_many=array(
|
||||
'TestObjects'=>'TestObject'
|
||||
private static $many_many = array(
|
||||
'TestObjects' => 'TestObject',
|
||||
);
|
||||
|
||||
public static $many_many_extraFields=array(
|
||||
'TestObjects'=>array(
|
||||
'SortOrder'=>'Int'
|
||||
private static $many_many_extraFields = array(
|
||||
'TestObjects' => array(
|
||||
'SortOrder' => 'Int',
|
||||
)
|
||||
);
|
||||
|
||||
|
||||
public function getCMSFields() {
|
||||
$fields=parent::getCMSFields();
|
||||
$fields = parent::getCMSFields();
|
||||
|
||||
$conf=GridFieldConfig_RelationEditor::create(10);
|
||||
$conf = GridFieldConfig_RelationEditor::create(10);
|
||||
$conf->addComponent(new GridFieldSortableRows('SortOrder'));
|
||||
|
||||
$fields->addFieldToTab('Root.TestObjects', new GridField('TestObjects', 'TestObjects', $this->TestObjects(), $conf));
|
||||
|
|
@ -34,12 +34,12 @@ class TestPage extends Page {
|
|||
|
||||
/*** TestObject.php ***/
|
||||
class TestObject extends DataObject {
|
||||
public static $db=array(
|
||||
'Title'=>'Text'
|
||||
private static $db = array(
|
||||
'Title' => 'Text',
|
||||
);
|
||||
|
||||
public static $belongs_many_many=array(
|
||||
'TestPages'=>'TestPage'
|
||||
private static $belongs_many_many = array(
|
||||
'TestPages' => 'TestPage',
|
||||
);
|
||||
}
|
||||
```
|
||||
|
|
@ -1,21 +1,22 @@
|
|||
ModelAdmin implementation Example
|
||||
=================
|
||||
Please note this example is written with 3.0.x in mind, if you are using 3.1.x make sure you scope all static properties to private not public.
|
||||
|
||||
```php
|
||||
/**** MyModelAdmin.php ****/
|
||||
class MyModelAdmin extends ModelAdmin {
|
||||
public static $menu_title='My Model Admin';
|
||||
public static $url_segment='my-model-admin';
|
||||
private static $menu_title = 'My Model Admin';
|
||||
|
||||
public static $managed_models=array(
|
||||
'MATestObject'
|
||||
);
|
||||
private static $url_segment = 'my-model-admin';
|
||||
|
||||
private static $managed_models = array(
|
||||
'MATestObject',
|
||||
);
|
||||
|
||||
public function getEditForm($id = null, $fields = null) {
|
||||
$form=parent::getEditForm($id, $fields);
|
||||
$form = parent::getEditForm($id, $fields);
|
||||
|
||||
//This check is simply to ensure you are on the managed model you want adjust accordingly
|
||||
if($this->modelClass=='MATestObject' && $gridField=$form->Fields()->dataFieldByName($this->sanitiseClassName($this->modelClass))) {
|
||||
if($this->modelClass == 'MATestObject' && $gridField=$form->Fields()->dataFieldByName($this->sanitiseClassName($this->modelClass))) {
|
||||
//This is just a precaution to ensure we got a GridField from dataFieldByName() which you should have
|
||||
if($gridField instanceof GridField) {
|
||||
$gridField->getConfig()->addComponent(new GridFieldSortableRows('SortOrder'));
|
||||
|
|
@ -28,11 +29,11 @@ class MyModelAdmin extends ModelAdmin {
|
|||
|
||||
/**** MATestObject.php ****/
|
||||
class MATestObject extends DataObject {
|
||||
public static $db=array(
|
||||
'Title'=>'Varchar',
|
||||
'SortOrder'=>'Int'
|
||||
);
|
||||
private static $db = array(
|
||||
'Title' => 'Varchar',
|
||||
'SortOrder' => 'Int',
|
||||
);
|
||||
|
||||
public static $default_sort='SortOrder';
|
||||
private static $default_sort = 'SortOrder';
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue