Update readme

This commit is contained in:
colymba 2013-12-05 19:42:17 +02:00
parent 06e82405e5
commit ac84765dc1
3 changed files with 92 additions and 63 deletions

36
BULK_IMAGE_UPLOAD.md Normal file
View File

@ -0,0 +1,36 @@
# Bulk Image Upload
A component for uploading images in bulk into the managed Model relation, with option to edit fields on the fly.
## Usage 1
Simplest usage, add the component to your GridField as below. The component will find the first Image has_one relation on the managed Model and the record's editable CMS fields
$config->addComponent(new GridFieldBulkImageUpload());
## Usage 2
You can specify which Image field to use and which fields are editable from the managed Model
$fileRelationName (string, optional): The name of the File/Image field to use (If your relation is set has 'MyImage' => 'Image', the parameter should be 'MyImage')
$editableFields (array, optional): list of db fields name as string that will be editable like: array('myTextField', 'myVarcharField', 'myEnumField')
$config->addComponent(new GridFieldBulkImageUpload( $fileRelationName, $editableFields ));
## Configuration
The component's option can be configurated individually or in bulk through the 'config' functions like this:
$config->getComponentByType('GridFieldBulkImageUpload')->setConfig( $reference, $value );
### $config overview
The available configuration options are:
* 'fileRelationName' : sets the name of the File/Image field of the managed Model (i.e. 'MyImage')
* 'editableFields' : array of string referencing specific CMS fields available for editing
* 'fieldsClassBlacklist' : array of string referencing types (ClassName) of fields that wont be available for editing
* 'fieldsNameBlacklist' : array of string referencing the names of fields that wont be available for editing
* 'folderName' : name of the folder where the images should be uploaded
* 'sequentialUploads' : boolean, if true files will be uploaded one by one
* 'maxFileSize' : integer, maximum upload file size in bytes
Each option can be set through the component's method setConfig( $reference, $value )
In addition, some configuration option can be set more specifically via individual methods:
* addFieldNameToBlacklist( $fieldName )
* addClassToBlacklist( $className )
* removeFieldNameFromBlacklist( $fieldName )
* removeClassFromBlacklist( $className )

41
BULK_MANAGER.md Normal file
View File

@ -0,0 +1,41 @@
# Bulk Manager
Perform actions on multiple records straight from the GridField. Comes with unlink, delete and bulk editing but you can easily create/add your own.
## Usage
Simply add GridFieldBulkManager to your GridFieldConfig
$config->addComponent(new GridFieldBulkManager());
## Configuration
The component's option can be configurated individually or in bulk through the 'config' functions like this:
$config->getComponentByType('GridFieldBulkManager')->setConfig( $reference, $value );
### $config overview
The available configuration options are:
* 'editableFields' : array of string referencing specific CMS fields available for editing
* 'fieldsClassBlacklist' : array of string referencing types (ClassName) of fields that wont be available for editing
* 'fieldsNameBlacklist' : array of string referencing the names of fields that wont be available for editing
## Custom actions
You can remove or add individual action or replace them all via `addBulkAction()` and `removeBulkAction()`
### Adding a custom action
To add a custom bulk action to the list use:
$config->getComponentByType('GridFieldBulkManager')->addBulkAction('actionName', 'Dropdown label', 'ActionHandlerClassName', $frontEndConfig)
You can omit the handler's class name and the front-end config array, those will default to:
* `'GridFieldBulkAction'.ucfirst($name).'Handler'`
* `$config = array( 'isAjax' => true, 'icon' => 'accept', 'isDestructive' => false )`
#### Custom action handler
When creating your awn bulk action RequestHandler, you should extend `GridFieldBulkActionHandler` which will expose 2 usefull functions `getRecordIDList()` and `getRecords()` returning either and array with the selected records IDs or a DataList of the selected records.
Make sue to the define your `$allowed_actions` and `$url_handlers`. See `GridFieldBulkActionEditHandler`, `GridFieldBulkActionDeleteHandler` and `GridFieldBulkActionUnlinkHandler` for examples.
#### Front-end config
The last component's parameter lets you pass an array with configuration options for the UI/UX:
* `isAjax`: if true the action will be called via XHR request otherwise the broser will be redirected to the action's URL
* `icon`: lets you define which icon to use when the action is selected (SilverStripe button icon name only)
* `isDestructive`: if true a confirmation dialog will be shown before the action is processed

View File

@ -1,9 +1,13 @@
GridField Bulk Editing Tools GridField Bulk Editing Tools
============================ ============================
SilverStripe 3 GridField component set to facilitate bulk image upload, bulk record editing, unlinking and deleting. Set of SilverStripe 3 GridField components to facilitate bulk image upload & record editing.
Included are: ![preview](screenshots/preview.png)
* [Bulk Image Upload](#bulk-image-upload): Bulk images upload and on the fly fields editing
* [Bulk Manager](#bulk-manager): Delete and unlink multiple records at once as well as editing records in bulk Components included:
* [Bulk Image Upload](#bulk-image-upload): Upload multiple images at once into DataObjects with on the fly fields editing
* [Bulk Manager](#bulk-manager): Handles actions for multiple records straight from the GridField (comes with unlink, delete and edit)
[More screenshots here.](screenshots)
## Requirements ## Requirements
* SilverStripe 3.1 (version master / 1.+) * SilverStripe 3.1 (version master / 1.+)
@ -12,80 +16,28 @@ Included are:
## Development notes ## Development notes
The master branch will try to be compatible with the latest SilverStripe release/pre-release. Please submit pull request against the master branch. Older branches are kept for compatibility but may not be maintained. The master branch will try to be compatible with the latest SilverStripe release/pre-release. Please submit pull request against the master branch. Older branches are kept for compatibility but may not be maintained.
## Preview
![preview](screenshots/preview.png)
[More screenshots here.](screenshots)
## Installation ## Installation
* Download and copy module in SilverStripe root directory and name it whatever you want * Download and copy module in SilverStripe root directory and name it whatever you want
* Run dev/build?flush=all to regenerate the manifest * run ?flush to regenerate the manifest
* run ?flush=all in CMS to force the templates to regenerate
## Bulk Image Upload ## Bulk Image Upload
A component for uploading images in bulk into the managed Model relation, with option to edit fields on the fly. Upload multiple images at once into DataObjects. Perfect for galleries and the like.
### Usage 1 $config->addComponent(new GridFieldBulkImageUpload());
Simplest usage, add the component to your GridField as below. The component will find the first Image has_one relation on the managed Model and the record's editable CMS fields
$config->addComponent(new GridFieldBulkImageUpload());
### Usage 2 See [BULK_IMAGE_UPLOAD.md](BULK_IMAGE_UPLOAD.md) for detailed configuration.
You can specify which Image field to use and which fields are editable from the managed Model
$fileRelationName (string): The name of the File/Image field to use (If your relation is set has 'MyImage' => 'Image', the parameter should be 'MyImage')
$editableFields (array): list of db fields name as string that will be editable like: array('myTextField', 'myVarcharField', 'myEnumField')
$config->addComponent(new GridFieldBulkImageUpload( $fileRelationName, $editableFields ));
### Configuration
The component's option can be configurated individually or in bulk through the 'config' functions like this:
$config->getComponentByType('GridFieldBulkImageUpload')->setConfig( $reference, $value );
#### $config overview
The available configuration options are:
* 'fileRelationName' : sets the name of the File/Image field of the managed Model (i.e. 'MyImage')
* 'editableFields' : array of string referencing specific CMS fields available for editing
* 'fieldsClassBlacklist' : array of string referencing types (ClassName) of fields that wont be available for editing
* 'fieldsNameBlacklist' : array of string referencing the names of fields that wont be available for editing
* 'folderName' : name of the folder where the images should be uploaded
* 'sequentialUploads' : boolean, if true files will be uploaded one by one
* 'maxFileSize' : integer, maximum upload file size in bytes
Each option can be set through the component's method setConfig( $reference, $value )
In addition, some configuration option can be set more specifically via individual methods:
* addFieldNameToBlacklist( $fieldName )
* addClassToBlacklist( $className )
* removeFieldNameFromBlacklist( $fieldName )
* removeClassFromBlacklist( $className )
## Bulk Manager ## Bulk Manager
A component for Editing, deleting and unlinking records on the fly Perform actions on multiple records straight from the GridField
### Usage $config->addComponent(new GridFieldBulkManager());
Add GridFieldBulkEditingTools component if not done already and simply add GridFieldBulkImageUpload
$config->addComponent(new GridFieldBulkManager());
### Configuration
The component's option can be configurated individually or in bulk through the 'config' functions like this:
$config->getComponentByType('GridFieldBulkManager')->setConfig( $reference, $value ); See [BULK_MANAGER.md](BULK_MANAGER.md) for detailed configuration.
#### $config overview
The available configuration options are:
* 'editableFields' : array of string referencing specific CMS fields available for editing
* 'fieldsClassBlacklist' : array of string referencing types (ClassName) of fields that wont be available for editing
* 'fieldsNameBlacklist' : array of string referencing the names of fields that wont be available for editing
## Notes ## Notes
* The Record edit form uses the Model's getCMSFields() * The Record edit form uses the Model's getCMSFields()
### @TODO ### @TODO
### Known bug
* When editing fields, if the last field of the edit form is a drop down or similar, the drop down menu is cropped off
### Bulk Image Upload
* Add individual actions for each upload (update + cancel) * Add individual actions for each upload (update + cancel)
* Handle and display errors better for: creation, update, cancel * Handle and display errors better for: creation, update, cancel
* Make it work not only for images but Files too * Make it work not only for images but Files too