add docs for new file extension process

This commit is contained in:
Aaron Carlino 2018-06-11 15:32:44 +12:00
parent 77a45c0dbc
commit 23bf8d2b3c
2 changed files with 112 additions and 0 deletions

View File

@ -141,6 +141,64 @@ if ($file) {
} }
``` ```
## Adding custom fields to files and images
As with any customisation of a core class, adding fields to the `File` and `Image` classes
is a two-phased approach. First, you have to update the model (i.e. the `$db` array) to include
your new custom field. Second, you need to update the editform to provide a way of editing
that field in the CMS. For most core classes, this can be done in a single extension, with an
update to the `$db` array and definition of an `updateCMSFields` function, but for files
and images, it works a bit differently. The edit form is generated by another class --
`FileFormFactory`. You will therefore need two separate extensions.
In this example, we'll add a `description` field to the `File` object and give it an editable
field in the CMS.
*app/_config/app.yml*
```yml
SilverStripe\Assets\File:
extensions:
- MyProject\MyFileExtension
SilverStripe\AssetAdmin\Forms\FileFormFactory:
extensions:
- MyProject\MyFormFactoryExtension
```
*app/src/MyFileExtension.php*
```php
namespace MyProject;
use SilverStripe\ORM\DataExtension;
class MyFileExtension extends DataExtension
{
private static $db = [
'Description' => 'Text',
];
}
```
*app/src/MyFormFactoryExtension.php*
```php
namespace MyProject;
use SilverStripe\Core\Extension;
use SilverStripe\Forms\FieldList;
use SilverStripe\Forms\TextareaField;
class MyFormFactoryExtension extends Extension
{
public function updateFormFields(FieldList $fields)
{
$fields->insertAfter(
'Title',
TextareaField::create('Description', 'Description')
);
}
}
```
## File versioning ## File versioning
File versioning is extended with the [silverstripe/versioned](https://github.com/silverstripe/silverstripe-versioned/) File versioning is extended with the [silverstripe/versioned](https://github.com/silverstripe/silverstripe-versioned/)

View File

@ -1095,6 +1095,60 @@ There are a few differences in this new API:
A generic `manipulate` method may be used, although the callback for this method both is given, and should return, A generic `manipulate` method may be used, although the callback for this method both is given, and should return,
an `AssetStore` instance and file tuple (Filename, Hash, and Variant) rather than an Image_Backend. an `AssetStore` instance and file tuple (Filename, Hash, and Variant) rather than an Image_Backend.
### Customising file edit form fields {#customising-file-editform}
In 3.x, customisation of the edit form for files and images could be done using the conventional
`updateCMSFields(FieldList $fields)` hook. In 4.x, this method no longer has any influence
on the file edit form that gets rendered in asset-admin. Instead, create an extension for
`FileFormFactory` and use the `updateFormFields(FieldList $fields)` hook.
In this example, we'll add a `description` field to the `File` object and give it an editable
field in the CMS.
*app/_config/app.yml*
```yml
SilverStripe\Assets\File:
extensions:
- MyProject\MyFileExtension
SilverStripe\AssetAdmin\Forms\FileFormFactory:
extensions:
- MyProject\MyFormFactoryExtension
```
*app/src/MyFileExtension.php*
```php
namespace MyProject;
use SilverStripe\ORM\DataExtension;
class MyFileExtension extends DataExtension
{
private static $db = [
'Description' => 'Text',
];
}
```
*app/src/MyFormFactoryExtension.php*
```php
namespace MyProject;
use SilverStripe\Core\Extension;
use SilverStripe\Forms\FieldList;
use SilverStripe\Forms\TextareaField;
class MyFormFactoryExtension extends Extension
{
public function updateFormFields(FieldList $fields)
{
$fields->insertAfter(
'Title',
TextareaField::create('Description', 'Description')
);
}
}
```
### File or Image shortcode handler {#file-shortcode} ### File or Image shortcode handler {#file-shortcode}
The `handle_shortcode` methods have been removed from the core File and Image classes The `handle_shortcode` methods have been removed from the core File and Image classes