From ac84765dc1f2162c7b82dfe579d66fd762ac9bc8 Mon Sep 17 00:00:00 2001 From: colymba Date: Thu, 5 Dec 2013 19:42:17 +0200 Subject: [PATCH] Update readme --- BULK_IMAGE_UPLOAD.md | 36 ++++++++++++++++++++ BULK_MANAGER.md | 41 +++++++++++++++++++++++ README.md | 78 +++++++++----------------------------------- 3 files changed, 92 insertions(+), 63 deletions(-) create mode 100644 BULK_IMAGE_UPLOAD.md create mode 100644 BULK_MANAGER.md diff --git a/BULK_IMAGE_UPLOAD.md b/BULK_IMAGE_UPLOAD.md new file mode 100644 index 0000000..19d3222 --- /dev/null +++ b/BULK_IMAGE_UPLOAD.md @@ -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 ) \ No newline at end of file diff --git a/BULK_MANAGER.md b/BULK_MANAGER.md new file mode 100644 index 0000000..4afa26d --- /dev/null +++ b/BULK_MANAGER.md @@ -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 \ No newline at end of file diff --git a/README.md b/README.md index 10268e7..832dfbf 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,13 @@ GridField Bulk Editing Tools ============================ -SilverStripe 3 GridField component set to facilitate bulk image upload, bulk record editing, unlinking and deleting. -Included are: -* [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 +Set of SilverStripe 3 GridField components to facilitate bulk image upload & record editing. +![preview](screenshots/preview.png) + +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 * SilverStripe 3.1 (version master / 1.+) @@ -12,80 +16,28 @@ Included are: ## 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. -## Preview -![preview](screenshots/preview.png) -[More screenshots here.](screenshots) - ## Installation * 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=all in CMS to force the templates to regenerate +* run ?flush to regenerate the manifest ## 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 -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()); + $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): 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 ) +See [BULK_IMAGE_UPLOAD.md](BULK_IMAGE_UPLOAD.md) for detailed configuration. ## Bulk Manager -A component for Editing, deleting and unlinking records on the fly +Perform actions on multiple records straight from the GridField -### Usage -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->addComponent(new GridFieldBulkManager()); - $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 +See [BULK_MANAGER.md](BULK_MANAGER.md) for detailed configuration. ## Notes * The Record edit form uses the Model's getCMSFields() ### @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) * Handle and display errors better for: creation, update, cancel * Make it work not only for images but Files too