From cab20871c53fd191ca5e4c55525a18a4fd8219a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Randy=20=C4=8Cupi=C4=87?= Date: Mon, 11 Oct 2021 12:28:03 +0200 Subject: [PATCH] Update the documentation to prepare for 2.0 tag --- README.md | 17 ++++-- docs/CHANGELOG.md | 13 +++++ docs/FRONTEND.md | 1 - docs/INSTALL.md | 114 +++++++++++++++++++++++++-------------- docs/UPGRADE.md | 38 +++++++++++++ docs/USAGE.md | 133 +++++++++++++++++++++++++++++++++++++++++----- 6 files changed, 258 insertions(+), 58 deletions(-) create mode 100644 docs/UPGRADE.md diff --git a/README.md b/README.md index fa3da4b9..b3d9d315 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,16 @@ Netgen Remote Media Bundle is an eZ Publish bundle providing field type which supports remote resource providers, primarily [Cloudinary](http://cloudinary.com/). -This repository contains field type (and legacy data type) implementation and provides the interface for the legacy administration. +This repository contains field type (and legacy data type) implementation and provides the interface for the legacy administration. It also contains integration for eZ XML and Richtext fields (as a custom tag). ## Features - field type support for remote resources (only Cloudinary supported at the moment) -- support for images, videos, and documents upload +- eZ XML field custom tag +- eZ Richtext field custom tag +- support for images, videos, audio files, documents and raw files upload - images cropping editor +- support for both legacy and new stack administrations ## Licence and installation instructions @@ -26,11 +29,17 @@ This repository contains field type (and legacy data type) implementation and pr For usage documentation see [USAGE.md](docs/USAGE.md) +For transformations usage see [TRANSFORMATIONS.md](docs/TRANSFORMATIONS.md) + +## Changelog + +For changes in specific versions see [CHANGELOG.md](docs/CHANGELOG.md) + ## Contributing For frontend development see [FRONTEND.md][docs/frontend.md] ## Copyright -- Copyright (C) 2016 Keyteq. All rights reserved. -- Copyright (C) 2016 Netgen. All rights reserved. +- Copyright (C) 2021 Keyteq. All rights reserved. +- Copyright (C) 2021 Netgen. All rights reserved. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index fd30b717..ae381666 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,18 @@ # Netgen Remote Media Bundle changelog +## 2.0 + +* now all resource types are fully supported +* filtering and search options have been improved +* re-implemented integration for eZ XML text field +* added implementation for eZ Richtext field +* added support for multi-level folder structure +* re-implemented frontend in Vue.js +* added support for waveform image for audio files +* updated PHP CS fixer configuration for coding standards +* added configuration for GitHub CI (coding standards and tests) +* improved coverage with tests + ## 1.1.11 ### Fixed diff --git a/docs/FRONTEND.md b/docs/FRONTEND.md index b0a9d6eb..defc46a2 100644 --- a/docs/FRONTEND.md +++ b/docs/FRONTEND.md @@ -89,7 +89,6 @@ $ node copyFilesDev.js This script fakes additional files (normally created with production build). - ## Project structure ```bash diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 0be30e5d..ad163177 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,54 +1,88 @@ -# Installation instructions for Netgen Remote Media Bundle +# Installation instructions ## Requirements * eZ Platform **Suggested** -* this package works best with NetgenAdminUI. + +* this package works best with [Netgen Admin UI](https://github.com/netgen/NetgenAdminUIBundle) ## Installation steps -* Configure the bundle: - * in `config.yml` add basic configuration: - ``` - netgen_remote_media: - provider: cloudinary - account_name: [your_cloud_name] - account_key: [your_key] - account_secret: [your_secret] - ``` - -* Run the following from your website root folder: - `$ composer require netgen/remote-media-bundle:^2.0` - -* Activate legacy extension - -* Activate the bundle: - ``` - public function registerBundles() - { - ... +### Configure the bundle + +In `config.yml` add basic configuration: + +```yaml +netgen_remote_media: + provider: cloudinary + account_name: [your_cloud_name] + account_key: [your_key] + account_secret: [your_secret] +``` + +### Install the bundle via Composer + +Run the following from your website root folder: + +``` +composer require netgen/remote-media-bundle:^2.0 +``` - $bundles[] = new Netgen\Bundle\RemoteMediaBundle\NetgenRemoteMediaBundle(); +### Activate legacy extension + +Add the following in your central `site.ini.append.php` file (usually `ezpublish_legacy/settings/override/site.ini.append.php`): + +``` +[ExtensionSettings] +ActiveExtensions[]=ngremotemedia +``` - return $bundles; - } - ``` +### Activate the bundle + +Add the following in your `app/AppKernel.php` file: + +```php +public function registerBundles() +{ + ... + + $bundles[] = new Netgen\Bundle\RemoteMediaBundle\NetgenRemoteMediaBundle(); + + return $bundles; +} +``` -* Add the following entry to your main `routing.yaml` file: +### Add routing configuration + +Add the following entry to your main `routing.yaml` file: - ``` - netgen_remote_media: - resource: "@NetgenRemoteMediaBundle/Resources/config/routing.yml" - ``` +```yaml +netgen_remote_media: + resource: "@NetgenRemoteMediaBundle/Resources/config/routing.yml" +``` -* Update the database with a custom table: - * `$ mysql -u -p -h < vendor/netgen/remote-media-bundle/bundle/Resources/sql/schema.sql` - * **OR** run `php app/console doctrine:schema:update --force` (or run with `--dump-sql` to get the sql needed for creating the table) - -* Clear the caches - * run the following command: - ``` - $ php bin/console cache:clear - ``` +### Update the database + +This bundle has a custom table in the database which needs to be created: + +``` +mysql -u -p -h < vendor/netgen/remote-media-bundle/bundle/Resources/sql/schema.sql` +``` + +Or you can also do it via Doctrine: + +``` +php app/console doctrine:schema:update --force +``` + +(or run with `--dump-sql` to get the sql needed for creating the table). + +### Clear caches + +Run the following command: + +``` +php bin/console cache:clear +``` diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md new file mode 100644 index 00000000..7acd2fff --- /dev/null +++ b/docs/UPGRADE.md @@ -0,0 +1,38 @@ +Netgen Remote Media Bundle upgrade instructions +=============================================== + +Upgrade from 1.0 to 2.0 +----------------------- + +Version 2.0 is a major release which brings many improvements and new features, as well as code cleanup but it contains some breaking changes as well as removed supports. + +### Changed requiremets +* This bundle now supports only Symfony v3, the support for Symfony v2.8 (or lower) has been dropped +* This bundle now supports only PHP 7.2 - 7.4 versions +* This bundle now supports only eZ Platform v2 (from 2.4, or kernel 7.4) + +### Data structure changes + +The data structure for eZ field value as well as for eZ XML field custom tag, which is being stored in the database, has been changed. There's a migration command which will iterate through all fields (both NGRM and eZ XML fields) in the database and fix their data to support the new version. + +**WARNING:** the command works directly with the database, bypassing eZ's API. This means that it will fix all the data (including previous versions, drafts etc.) but it also means that **database backup is mandatory** prior to executing the command. + +#### Command + +```console +php bin/console netgen:ngremotemedia:refresh:ez_fields +``` + +#### Options + +* `--dry-run` - this will only display the actions that will be performed +* `--force` - this will use the first found resource and empty fields with non-existing resources +* `--content-ids` - list of content IDs to process (default: all) +* `--chunk-size` - the size of the chunk of attributes to fetch (and size of chunk of resource to get from remote media in one API request) +* `--rate-limit-treshold` - Percentage of remaining API rate limit below which the command will exit to prevent crashing the media on frontend (default 50 (%)). + +#### Possible rate-limit issues + +As you may know, cloud providers (eg. Cloudinary) mostly have the limit of requests that can be executed towards their API in specific period (one hour for Cloudinary). Since the command iterates through all fields and asks the API for each of these resources, it might break the rate limit which will make remote media resources on the live site unavailable. + +In order to prevent this, the command will perform API fetches in chunks: it will first generate the list of all resources that need to be fetched and then fetch them in one request. You can control the size of the chunk with `--chunk-size` parameter. You can also set the `--rate-limit-treshold` which will stop the execution if the command consumes more than a set percentage of the rate limit. diff --git a/docs/USAGE.md b/docs/USAGE.md index 6ed1613a..69dec130 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,24 +1,69 @@ -# Usage instructions for Netgen Remote Media Bundle # +# Usage instructions -## Content type definition ## -You can add the remote media content field to your content type. There is no additional configuration needed. +## Content type definition + +You can add the remote media content field to your content type. There is no additional configuration needed. You can add it either through eZ admin interface (both legacy (eg. [Netgen Admin UI](https://github.com/netgen/NetgenAdminUIBundle)) and new stack admin are supported), or via available console command: + +``` +php bin/console netgen:ngremotemedia:add:field +``` + +Needed arguments: + +* `content_type_identifier` - the identifier of the content type where you want to add the field (eg. `article`) +* `field_identifier` - the identifier of the field that will be created (eg. `remote_image`) +* `field_name` - the name of the field that will be created (eg. `Remote image`) + +Options: + +* `--field_position` - the position of the field that will be created (default: 0) + +## Managing your media -## Managing your media ## You can do simple management of your media files while editing the content, directly from the administration interface, both on the legacy administration and Netgen Admin UI. -### Uploading ### -With a simple press of a button, you can either browse the existing media (separated into images and videos) or upload the media from your own computer. -When uploading, you can select which folder to upload to*, and when browsing and searching, you can also limit your view per folder. +### Uploading + +With a simple press of a button, you can either browse the existing media (separated into images (which include some documents like PDF) video and audio or RAW files) or upload the media from your own computer. + +When uploading, you can select which folder to upload to*, and when browsing and searching, you can also limit your view per folder. This bundle supports multi-level folder structure. (*) **Note**: for automatic creating of folders when uploading, please remember to activate "Auto-create folders" option on your Cloudinary account. -### Cropping the images ### +#### Uploading via console command + +You can also upload and add a resource to a specific content using the available console command: + +``` +php bin/console netgen:ngremotemedia:add:data +``` + +Required arguments: + +* `content_id` - the ID of the content on which you want to add the resource +* `field_identifier` - the identifier of the NGRM field where you want to add the resource +* `image_path` - the path to the resource on the filesystem, which you want to upload + +Additional options: + +* `alt_text` - alternative text for the resource +* `caption` - caption for the resource +* `language` - if this is a multi-language site, you can select for which language you want to add the image (it accepts the locale value eg. `en_EN`), otherwise it will use the main language by default + +### Cropping the images + The editors have the ability to crop the images immediately when editing the content object. As long as the variations in the `crop` transformation are defined, editors are able to choose which part of the image they want to show for each use case. + One example of this would be if one would use the `` tag with different formats for desktop and mobile. In this case, editors can upload a single image and choose different cropping for each resolution. -## Image variation definitions ## -Image variations are defined through the yaml configuration in the similar way as they are defined in eZ Platform. The configuration is siteaccess aware. Furthermore, you can define variations per content type, meaning you can have two variations that are named the same but use different transformations depending on the content type where they are used. +**Note:** the interface won't let you define the cropping if the used image is smaller than the defined variation. + +## Image variation definitions + +Image variations are defined through the YAML configuration in the similar way as they are defined in eZ Platform. The configuration is siteaccess aware. Furthermore, you can define variations per content type, meaning you can have two variations that are named the same but use different transformations depending on the content type where they are used. + Example: + ```yaml netgen_remote_media: system: @@ -45,8 +90,28 @@ netgen_remote_media: ``` You can check the list of the available tranformations [here](Resources/docs/Transfromations.md). Further details on what each transformation does is available on [Cloudinary web](http://cloudinary.com/documentation/image_transformations). -## In templates ## -If you have added the field to your content class, you can now use it with the normal `ez_render_field` function: +### WYSIWYG editor variations + +When inserting an image or video into eZ XML or Richtext WYSIWYG editor fields, it is possible to select a variation that will be inserted instead of original image (with cropping editor also available). The list of variations that will be available there is defined under `embed` group: + +```yaml +netgen_remote_media: + system: + default: + image_variations: + embed: + full: + transformations: + - { name: crop, params: [1600, 800] } + - { name: fill, params: [1600, 800] } +``` + +## Usage in templates + +### Rendering the eZ field + +If you have added the field to your content class, you can now use it with the normal `ez_render_field` function, and you can define the variation with the `format` parameter: + ```php {{ ez_render_field( content, @@ -59,7 +124,11 @@ If you have added the field to your content class, you can now use it with the n } ) }} ``` + +In the above example, `remote_image` is the name of the field and `large` is the name of the variation. + In case you want to manually define which transformations to use from the Twig template, you can do that as well. Instead of the name of the format, pass an array with the manually defined options: + ```php {{ ez_render_field( content, @@ -74,6 +143,7 @@ In case you want to manually define which transformations to use from the Twig t } ) }} ``` + This example will produce an image which will have a defined dimensions of `240x240` and will be delivered in a `png` format. The other parameters you can pass to the function are: @@ -83,7 +153,44 @@ The other parameters you can pass to the function are: Note that not all parameters will always be applicable; it depends on the type of the resource you are rendering. -If you just need to get the URL of the image, you can get the `Variation` object by using the Twig function `netgen_remote_variation`: +### Manual rendering + +If you just need to get the URL of the image, you can get it from the field value as a `url` (http) or `secure_url` (https) property: + +```php +{% set image_url = ez_field_value(content, 'image').secure_url %} +``` + +Or, if you need a variation, you can get the `Variation` object by using the Twig function `netgen_remote_variation` which accepts eZ content, field name and variation name: + ```php {% set variation = netgen_remote_variation(content, 'image', 'full') %} ``` + +The variation object then contains the `url` property. + +```php +{% set image_url = variation.url %} +``` + +## Usage in PHP + +If you need to get a resource value, variation or simply an URL for the resource somewhere in a service, or controller, you can use the service `@netgen_remote_media.provider` which will automatically provide the corresponding provider based on configuration (currently only `cloudinary`). You can see available methods in the abstract provider class: `Netgen\Bundle\RemoteMediaBundle\RemoteMedia\RemoteMediaProvider`. + +### Fetching a resource + +In order to fetch a single resource, you need the `resourceId` and `resourceType`: + +```php +$resource = $this->remoteMediaProvider->getRemoteResource('my_folder/my_image.jpg', 'image'); +$url = $resource->secure_url; +``` + +### Fetching a variation + +You can also build a variation for a resource from eZ content using the following function: + +```php +$variation = $this->remoteMediaProvider->buildVariation($resource, 'my_content_type', 'my_variation'); +$url = $variation->url; +```