# cnBolt-Extensions-ImageService Use image services as replacement for Bolt's image fields. The service uses different connectors to local or cloud services. The service contains connectors for - **Cloudinary** stores images and their attributes on http://cloudinary.com - **Content** stores images and their attributes inside a configurable contentype in Bolt - **Shrimp** strores images inside a S3 bucket and uses Condé-Nast Germany's Shrimp service for cropping. *This service does currently not support tags and will omit them!* ## Installation 1.) Install via composer or bolt's marketplace. ``` php app/nut extensions:install ``` If the nut command is not located in the app folder, you could also find it in vendor/bin/nut. Installing or updating via the Bolt admin interface is also possible but would require the web-server's user to have proper access to the GitHup repository. This is usually not the case. ## Configuration A new field type `imageservicelist` is available and takes the following configuration parameters: - **attributes** contains an array of fields similar to Bolt's own fields. Each image will have these fields. (These fields try to mimic the basic bolt fields, but they are custom for this extension!). Availble types are `text`, `textarea`, `checkbox`, `select`. - **globals** contains an array of fields for the imageservicelist itself. If you use the field as a gallery, this property could store the galleries title or layout. Add the following field to your content type, where you want to add the extension. E.g. in pages: ``` pages: name: Pages singular_name: Page fields: # Standalone ImageService field imageservice: type: imageservicelist label: CouldImage globals: &ImageServiceGlobals title: type: text label: Gallery Title layout: type: select label: Gallery Layout options: sm: Small lg: Large attributes: &ImageServiceAttributes title: type: text label: Image Title alt: type: text label: Alternative Text caption: # Type textarea includes a simple HTML edit prugin called Scribe type: textarea label: Caption chgeckbox: type: checkbox label: checkbox value: 1 ``` Another example on how to configure the imageservicelist as a section inside the structured-content field. (See that extension) ``` pages: name: Pages singular_name: Page fields: # Image Service as a part of Bolt-Structured-Content (SirTrevor) structuredcontent: type: structuredcontentfield height: 400px blocks: [Imageservice, Heading, Text, List, Video, Quote] extend: #block_config imageService: maxFiles: 1 maxFileSize: 20000 globals: *ImageServiceGlobals attributes: *ImageServiceAttributes ``` Change the configuration file for this extension according to your needs (created after instalation and first call to bolt) in app/config/extensions/imageservice.cnd.yml ``` # A list of all active image services with their class names and config variables connectors: # A sample config for a local content connector that stores images in a bolt contenttype content: contentype: images cache: 60 # number of seconds or false for never cached delete: true # if true, content object of the image will be deleted. If not, status will only be changed to "held" path: "imageservice/%year%/%month%" # Taregt folder for uploaded files. Defaults to "%year%/%month%". Allowed placeholders are %year%, %month% security: allowed-extensions: [jpeg, jpg, JPG, png, gif] max-size: 5000000 tagtype: tags # tags on an image will be stored in this taxonomy of bolt # a sample config for cloudinary that stores all images in cloudinary cloudinary: cloud-name: my-cloud api-key: 12345678901234567890 api-secret: myapisecretinmyfabulouscloud api-base-url: https://api.cloudinary.com/v1_1/my-cloud base-delivery-url: https://res.cloudinary.com/my-cloud secure-delivery-url: https://res.cloudinary.com/my-cloud security: allowed-extensions: [jpeg, jpg, JPG, png, gif] max-size: 5000000 upload-defaults: unique_filename: true overwrite: false folder: false type: upload image_metadata: false colors: false invalidate: true # A sample configuration for the Cond�-Nast Shrimp service shrimp: class: Bolt\Extension\CND\ImageService\Connector\ShrimpConnector endpoint: https://shrimp.condenast.de/glamour key: 1234567890 bucket: my-bucket-shrimp security: allowed-extensions: [jpeg, jpg, JPG, png, gif] max-size: 5000000 AWS: region: "eu-west-1" key: 1234567890 secret: 1234567890 defaults: connector: content image: mode: limit format: jpg quality: 80 options: [] permissions: roles: edit: [editor, chief-editor, developer] view: [everyone] ``` ## Usage Within your twig template, you may access the imageservice field which comes as an array of image objects. You can then render ech image of this array either via the `imageservice` filter or with bolt's own `thumbnail` filter (which is overridden by this extension). ``` {# take the first image from the field (you could also loop through all of them if you want a gallery #} {% set image = record.teaserimage.items|first %} ``` ## Filters The extension provides a imageservice filter. You can also simply keep using the `thumbnail` filter, which is overridden by this extension. Normal images of Bolt's native image field will still be redirected to the original `thumbnail` filter. **imageservice** The filter supports these parameters: - $width - Desired widths of the image in pixel - $height - Desired height of the image in pixel - $mode - Desired cropping mode of the image. Available: scale, fill, pad, limit, fit - $format - Desired image format. Default: jpg - $quality - Desired image quality - $options - array of additional options as supported by your used connector ``` ``` ## Crop modes The connectors should support these crop modes: - scale - Resize exactly to the given width and height without retaining aspect ratio. - limit - Resize inside given width and height and retain aspect ratio. Only if original is larger than target! - fill - Resize exactly to the given width and height and retain aspect ratio, cropping the image if necessary. - fit - Resize inside given width and height and retain aspect ratio. - pad - Resize exactly to the given width and height and retain aspect ratio, padding the image if necessary. # Vendor libraries The folder vendor contains libraries from various image services like Cloudinary. These folders are not managed by any automatism like composer and need to be updated manually. # Tech Notes The extension makes a copy of the save button, in order to make sure that, that images will be saved as a first thing on saving. If the event needs to be cancelled, e.g. by problem on saving, the saving of the article must be abandoned as well. No better way found to deal with the events. If the field is needed as a single file upload, one should set the maxFiles property on 1. The forntend does not allow the creation on new Images of different service types. That is why the images of different services can only be managed in separate fields. The ImageServiceField type is surrently untested and possibly unmaintained. We suggest to use the ImageServiceListField with maxFiles set to 1.