flownative / neos-pixxio
Neos integration for pixx.io
Installs: 51 546
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 4
Forks: 11
Open Issues: 1
Type:neos-package
Requires
- behat/transliterator: ~1.0
- guzzlehttp/guzzle: ^6.0 || ^7.0
- neos/flow: ^6.3 || ^7.0 || ^8.0 || dev-master
- neos/media: ^5.3 || ^7.0 || ^8.0 || dev-master
README
pixx.io adaptor for Neos
This Flow package allows you to use assets (ie. pictures and other documents) stored in pixx.io in your Neos website as if these assets were native Neos assets.
About pixx.io
pixx.io offers an intelligent solution for digital asset management. The software makes working with pictures, graphics and video files easier. pixx.io is safe, efficient and easy to understand and handle.
Key Features
- authentication setup via own backend module
- seamless integration into the Neos media browser
- automatic import and clean up of media assets from pixx.io
Installation
The pixx.io connector is installed as a regular Flow package via Composer. For your existing
project, simply include flownative/neos-pixxio
into the dependencies of your Flow or Neos distribution:
composer require flownative/neos-pixxio
After installation you need to run database migrations:
./flow doctrine:migrate
Enabling pixx.io API access
The API access is configured by three components:
- a setting which contains the customer-specific service endpoint URL
- a setting providing the pixx.io API key
- a setting providing the pixx.io user refresh token
To get the needed values for API endpoint and API key, please contact your pixx.io support contact.
First define the customer-specific service endpoint by adding the URL to your settings:
Neos: Media: assetSources: 'flownative-pixxio': assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource' assetSourceOptions: apiEndpointUri: 'https://flownative.pixxio.media/cgi-bin/api/pixxio-api.pl'
You will likely just replace "flownative" by our own subdomain.
Next, add the pixx.io API key and the refresh token of the pixx.io user you want to connect with Neos:
Neos: Media: assetSources: 'flownative-pixxio': assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource' assetSourceOptions: apiEndpointUri: 'https://flownative.pixxio.media/cgi-bin/api/pixxio-api.pl' apiKey: 'abcdef123456789' sharedRefreshToken: 'A3ZezMq6Q24X314xbaiq5ewNE5q4Gt'
When you committed and deployed these changes, you can log in to the Neos backend and navigate to the pixx.io backend module to verify your settings.
If you would like a separate pixx.io user for the logged in Neos user, you can copy and paste your own "refresh token" into the form found in the backend module and store it along with your Neos user.
When everything works out fine, Neos will report that the connection was successful (and if not, you'll see an error message with further details).
Additional configuration options
During import, Neos tries to use a medium-sized version of the original instead of the high resolution file uploaded to pixx.io. This greatly improves import speed and produces good results in most cases. Furthermore, this way some formats, like Adobe Photoshop, can be used seamlessly in Neos without the need to prior converting them into a web-compatible image format.
It is possible though, to configure this plugin to always use the high-res original for import. By default, formats like SVG or PDF are imported this way. You can add more types through the similar entries like in the following settings:
Neos: Media: assetSources: 'flownative-pixxio': assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource' assetSourceOptions: mediaTypes: 'image/svg+xml': usePixxioThumbnailAsOriginal: true 'application/pdf': usePixxioThumbnailAsOriginal: true
Sometimes the API Client needs additional configuration for the tls connection like custom timeouts or certificates. See: http://docs.guzzlephp.org/en/6.5/request-options.html
Neos: Media: assetSources: 'flownative-pixxio': assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource' assetSourceOptions: apiClientOptions: 'verify': '/path/to/cert.pem'
Using ImageOptions parameters for files
Via configuration, you can set what dimensions the returned images must have. The sizes are defined by the following keys:
thumbnailUri
used in the media browser listpreviewUri
used in the detail page of a assetoriginalUri
used for downloading the asset
The configuration is by default
Neos: Media: assetSources: 'flownative-pixxio': assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource' assetSourceOptions: imageOptions: thumbnailUri: width: 400 height: 400 quality: 90 crop: false previewUri: width: 1500 height: 1500 quality: 90 originalUri: sizeMax: 1920 quality: 90
Each imageOptions can be overridden from your own packages configuration, by addressing the specific preset key.
By default, the assets from Pixx.io is returned in a cropped format. When this is the case, a editor can't see if a asset is horizontal or vertical, when looking in the Media Browser list.
By setting crop: false
the image will be returned in a not-cropped version, and it's visible for the editor, to see the assets orientation
Cleaning up unused assets
Whenever a pixx.io asset is used in Neos, the media file will be copied automatically to the internal Neos asset storage. As long as this media is used somewhere on the website, Neos will flag this asset as being in use. When an asset is not used anymore, the binary data and the corresponding metadata can be removed from the internal storage. While this does not happen automatically, it can be easily automated by a recurring task, such as a cron-job.
In order to clean up unused assets, simply run the following command as often as you like:
./flow media:removeunused --asset-source flownative-pixxio
If you'd rather like to invoke this command through a cron-job, you can add two additional flags which make this command non-interactive:
./flow media:removeunused --quiet --assume-yes --asset-source flownative-pixxio
Auto-Tagging
This plugin also offers an auto-tagging feature. When auto-tagging is enabled, Neos will automatically flag assets which are currently used with a user-defined keyword. When as the asset is not used in Neos anymore, this keyword is removed. This keyword is applied to the actual file / asset in the pixx.io media library and helps editors to keep an overview of which assets are currently used by Neos.
Auto-tagging is configured as follows:
Neos: Media: assetSources: 'flownative-pixxio': assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource' assetSourceOptions: autoTagging: enable: true inUseTag: 'your-custom-tag'
Since Neos currently cannot handle auto-tagging reliably during runtime, the job must be done through a command line command. Simply run the following command for tagging new assets and removing tags from assets which are not in use anymore:
./flow pixxio:tagusedassets
Tagging used assets of asset source "flownative-pixxio" via Pixxio API:
(tagged) dana-devolk-1348553-unsplash 358 (1)
tagged azamat-zhanisov-1348039-unsplash 354 (1)
(tagged) tim-foster-1345174-unsplash 373 (1)
removed some-coffee 28 (0)
(tagged) nikhita-s-615116-unsplash 368 (1)
It is recommended to run this command through a cron-job, ideally in combination with the media:removeunused
command. It's important to run the removeunused
-command after the tagging command, because otherwise removed
images will not be untagged in the pixx.io media library.
NOTE
At this point, the auto-tagging feature is not really optimized for performance. The command merely
iterates over all assets which were imported from pixx.io and checks if tags need to be updated.
Category mapping from pixx.io to Neos
pixx.io offers categories to organize assets in a folder-like structure. Those can be mapped to asset collections and tags in Neos, to make them visible for the users.
NOTE
The pixx.io asset source declares itself read-only. Neos does not show asset
collections in the UI for read-only asset sources. This has been changed for
Neos 7.3.0 and up with neos/neos-development-collection#3481
If you want to use this feature with older Neos versions, you can use the PR with
cweagans/composer-patches
or copy the adjusted template into your project and use Views.yaml
to activate it.
The configuration for the category import looks like this:
Flownative: Pixxio: mapping: # map "categories" from pixx.io to Neos categoriesMaximumDepth: 2 # only include the first two levels of categories categories: 'People/Employees': asAssetCollection: false # ignore this category, put more specific patterns first 'People*': # the category "path" in pixx.io, shell-style globbing is supported asAssetCollection: true # map to an asset collection named after the category
- The key used is the category identifier from pixx.io as used in the API, without leading slash
asAssetCollection
set totrue
exposes the category as an asset collection named like the category.
Afterwards, run the following command to update the asset collections, ideally in a cronjob to keep things up-to-date:
./flow pixxio:importcategoriesascollections
To check what a given category would import, you can use a verbose dry-run:
$ ./flow pixxio:importcategoriesascollections --quiet 0 --dry-run 1 Importing categories as asset collections via pixx.io API o Dokumentation = Kunde A = Kunde A/Projekt 1 o Kunde A/Projekt 1/Copy o Kunde A/Projekt 1/Design + Kunde A/Projekt 2 o Kunde A/Projekt 2/Copy o Kunde A/Projekt 2/Design o Marketing o home o home/Doe_John Import done.
The above would have added "Kunde A/Projekt 2", the items marked "=" exist already, and everything else is ignored.
Background and Demo
Credits and license
The first version of this plugin was sponsored by pixx.io and its initial version was developed by Robert Lemke of Flownative.
See LICENSE for license details.