Merge pull request #441 from creative-commoners/pulls/5/file-manipula…

…tion-docs DOC Document making variants with different file extensions
silverstripe · Jan 28, 2024 · 3e68745 · 3e68745
2 parents af1a7a2 + 0443770
commit 3e68745
Show file tree

Hide file tree

Showing 5 changed files with 405 additions and 96 deletions.
diff --git a/en/02_Developer_Guides/14_Files/01_File_Management.md b/en/02_Developer_Guides/14_Files/01_File_Management.md
@@ -1,11 +1,13 @@
 ---
 title: File management
-summary: Learn how to work with File and Image records
+summary: Learn how to manage File and Image records
 icon: file-signature
 ---
 
 # File management
 
+See [file manipulation](./file_manipulation/) for information about how to manipulate the contents of files.
+
 ## Asset admin
 
 Management of files within the CMS is provided via the [silverstripe/asset-admin](https://github.com/silverstripe/silverstripe-asset-admin)
@@ -127,99 +129,6 @@ Within the CMS shortcodes can be added via either the "Insert Media" modal, or t
 buttons provided via the [silverstripe/asset-admin](https://github.com/silverstripe/silverstripe-asset-admin)
 module.
 
-## Creating files in PHP
-
-When working with files in PHP you can upload a file into a [`File`](api:SilverStripe\Assets\File) dataobject
-using one of the below methods:
-
-| Method                     | Description                             |
-| -------------------------- | --------------------------------------- |
-| `File::setFromLocalFile`   | Load a local file into the asset store  |
-| `File::setFromStream`      | Will store content from a stream        |
-| `File::setFromString`      | Will store content from a binary string |
-
-### Upload conflict resolution
-
-When storing files, it's possible to determine the mechanism the backend should use when it encounters
-an existing file pattern. The conflict resolution to use can be passed into the third parameter of the
-above methods (after content and filename). The available constants are:
-
-| Constant                            | If an existing file is found then:  |
-| ----------------------------------- | ----------------------------------- |
-| `AssetStore::CONFLICT_EXCEPTION`    | An exception will be thrown         |
-| `AssetStore::CONFLICT_OVERWRITE`    | The existing file will be replaced  |
-| `AssetStore::CONFLICT_RENAME`       | The backend will choose a new name. |
-| `AssetStore::CONFLICT_USE_EXISTING` | The existing file will be used      |
-
-If no conflict resolution scheme is chosen, or an unsupported one is requested, then the backend will choose one.
-The default asset store supports each of these.
-
-## Accessing files via PHP
-
-As with storage, there are also different ways of loading the content (or properties) of the file:
-
-| Method                   | Description                                                |
-| ------------------------ | ---------------------------------------------------------- |
-| `File::getStream`        | Will get an output stream of the file content              |
-| `File::getString`        | Gets the binary content                                    |
-| `File::getURL`           | Gets the URL for this resource. May or may not be absolute |
-| `File::getAbsoluteURL`   | Gets the absolute URL to this resource                     |
-| `File::getMimeType`      | Get the mime type of this file                             |
-| `File::getMetaData`      | Gets other metadata from the file as an array              |
-| `File::getFileType`      | Return the type of file for the given extension            |
-
-### Additional file types
-
-Silverstripe CMS has a pre-defined list of common file types. `File::getFileType` will return "unknown" for files outside that list.
-
-You can add your own file extensions and its description with the following configuration.
-
-```yml
-SilverStripe\Assets\File:
-  file_types:
-    ai: 'Adobe Illustrator'
-    psd: 'Adobe Photoshop File'
-```
-
-## Renaming and moving files
-
-In order to move or rename a file you can simply update the `Name` property, or assign the `ParentID` to a new
-folder. Please note that these modifications are made simply on the draft stage, and will not be copied
-to live until a publish is made via the CMS (either on this object, or cascading from a parent).
-
-When files are renamed using the ORM, all file variants are automatically renamed at the same time.
-
-```php
-use SilverStripe\Assets\File;
-
-$file = File::get()->filter('Name', 'oldname.jpg')->first();
-if ($file) {
-  // The below will move 'oldname.jpg' and 'oldname__variant.jpg'
-  // to 'newname.jpg' and 'newname__variant.jpg' respectively
-    $file->Name = 'newname.jpg';
-    $file->write();
-}
-```
-
-Note that you can cause the file to be moved immediately by [setting the Versioned reading mode](api:SilverStripe\Versioned\Versioned::set_reading_mode()) to draft temporarily.
-
-```php
-use SilverStripe\Assets\File;
-use SilverStripe\Versioned\Versioned;
-
-$file = File::get()->filter('Name', 'oldname.jpg')->first();
-if ($file) {
-  // The below will immediately move 'oldname.jpg' and 'oldname__variant.jpg'
-  // to 'newname.jpg' and 'newname__variant.jpg' respectively
-    $file->Name = 'newname.jpg';
-    Versioned::withVersionedMode(function () use ($file) {
-        Versioned::set_reading_mode('Stage.' . Versioned::DRAFT);
-        $file->write();
-        $file->publishSingle();
-    });
-}
-```
-
 ## Adding custom fields to files and images
 
 As with any customisation of a core class, adding fields to the `File` and `Image` classes

diff --git a/en/02_Developer_Guides/14_Files/02_Images.md b/en/02_Developer_Guides/14_Files/02_Images.md
@@ -101,6 +101,8 @@ Some of the MetaData functions need to be prefixed with 'get', example `getHeigh
 
 Please refer to the [`ImageManipulation`](api:SilverStripe\Assets\ImageManipulation) API documentation for specific functions.
 
+See [file manipulation](./file_manipulation/) for more general ways that all files can be manipulated.
+
 ### Creating custom image functions
 
 You can also create your own functions by decorating the `Image` class.

diff --git a/en/02_Developer_Guides/14_Files/04_File_Storage.md b/en/02_Developer_Guides/14_Files/04_File_Storage.md
@@ -69,9 +69,12 @@ assets/
 The URL for this file will match the physical location on disk:
 `https://www.example.com/assets/my-public-folder/my-public-file.jpg`.
 
-## Variant file paths (e.G. Resized images) {#variant-file-paths}
+## Variant file paths {#variant-file-paths}
+
+Each file can have variants.
+
+A variant is a manipulated version of the original file - for example if you resize an image or convert a file to another format, this will generate a variant (leaving the original file intact).
 
-Each file can have variants, most commonly resized versions of an image.
 These can be generated by resizing an image in the CMS rich text editor,
 through template logic, or programmatically with PHP.
 They are stored in the same folder alongside the original file,