From 295bb32fa1fda277e3a3023f236d33b2803a162d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 24 Nov 2015 11:45:18 +0100 Subject: [PATCH] Misc. fixes and improvements to the docs --- Resources/doc/basic-usage.rst | 26 ++++---- Resources/doc/filters.rst | 108 ++++++++++++++++++++++------------ 2 files changed, 84 insertions(+), 50 deletions(-) diff --git a/Resources/doc/basic-usage.rst b/Resources/doc/basic-usage.rst index e25596102..66e08c6ee 100644 --- a/Resources/doc/basic-usage.rst +++ b/Resources/doc/basic-usage.rst @@ -21,11 +21,11 @@ you want to thumbnail an image to a size of 120x90 pixels: filters: thumbnail: { size: [120, 90], mode: outbound } -You've now defined a filter set called `my_thumb` that performs a thumbnail -transformation. We'll learn more about available transformations later, but +You've now defined a filter set called ``my_thumb`` that performs a thumbnail +transformation. We'll learn more about available transformations later, but for now, this new filter can be used immediately in a template: -.. configuration-block: +.. configuration-block:: .. code-block:: html+jinja @@ -35,17 +35,17 @@ for now, this new filter can be used immediately in a template: -Behind the scenes, the bundles applies the filter(s) to the image on the +Behind the scenes, the bundles applies the filter(s) to the image on the first request and then caches the image to a similar path. On the next request, the cached image would be served directly from the file system. In this example, the final rendered path would be something like -`/media/cache/my_thumb/relative/path/to/image.jpg`. This is where Imagine +``/media/cache/my_thumb/relative/path/to/image.jpg``. This is where Imagine would save the filtered image file. You can also pass some options at runtime: -.. configuration-block: +.. configuration-block:: .. code-block:: html+jinja @@ -76,21 +76,21 @@ omit filters option will be applied all available filters. If you need to access filtered image URL in your controller: .. code-block:: php - + $this->get('liip_imagine.cache.manager')->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb', true), -In this case, the final rendered path would contain some random data in the -path ``/media/cache/my_thumb/S8rrlhhQ/relative/path/to/image.jpg``. This is where +In this case, the final rendered path would contain some random data in the +path ``/media/cache/my_thumb/S8rrlhhQ/relative/path/to/image.jpg``. This is where Imagine would save the filtered image file. .. note:: - Using the ``dev`` environment you might find that the images are not properly - rendered when using the template helper. This is likely caused by having - ``intercept_redirect`` enabled in your application configuration. To ensure + Using the ``dev`` environment you might find that the images are not properly + rendered when using the template helper. This is likely caused by having + ``intercept_redirect`` enabled in your application configuration. To ensure that the images are rendered disable this option: .. code-block:: yaml - + web_profiler: intercept_redirects: false diff --git a/Resources/doc/filters.rst b/Resources/doc/filters.rst index d0d9891f9..60a516614 100644 --- a/Resources/doc/filters.rst +++ b/Resources/doc/filters.rst @@ -5,7 +5,7 @@ Built-in Filters ---------------- The ``thumbnail`` filter -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ The thumbnail filter, as the name implies, performs a thumbnail transformation on your image. @@ -24,10 +24,12 @@ annotated configuration examples: filter_sets: my_thumb_out: filters: - thumbnail: { size: [32, 32], mode: outbound } # Transforms 50x40 to 32x32, while cropping the width + # Transforms 50x40 to 32x32, while cropping the width + thumbnail: { size: [32, 32], mode: outbound } my_thumb_in: filters: - thumbnail: { size: [32, 32], mode: inset } # Transforms 50x40 to 32x26, no cropping + # Transforms 50x40 to 32x26, no cropping + thumbnail: { size: [32, 32], mode: inset } There is also an option ``allow_upscale`` (default: ``false``). By setting @@ -67,8 +69,8 @@ annotated configuration examples: The ``upscale`` filter ~~~~~~~~~~~~~~~~~~~~~~ -The upscale filter, as the name implies, performs a upscale transformation -on your image. Configuration looks like this: +It performs an upscale transformation on your image to increase its size to the +given dimensions: .. code-block:: yaml @@ -79,10 +81,10 @@ on your image. Configuration looks like this: upscale: { min: [800, 600] } The ``downscale`` filter -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ -The downscale filter, as the name implies, performs a downscale transformation -on your image. Configuration looks like this: +It performs a downscale transformation on your image to reduce its size to the +given dimensions: .. code-block:: yaml @@ -95,8 +97,11 @@ on your image. Configuration looks like this: The ``crop`` filter ~~~~~~~~~~~~~~~~~~~ -The crop filter, as the name implies, performs a crop transformation on your -image. Configuration looks like this: +It performs a crop transformation on your image. The ``start`` option defines +the coordinates of the left-top pixel where the crop begins (the ``[0, 0]`` +coordinates correspond to the top leftmost pixel of the original image). The +``size`` option defines in pixels the width and height (in this order) of the +area cropped: .. code-block:: yaml @@ -109,8 +114,9 @@ image. Configuration looks like this: The ``strip`` filter ~~~~~~~~~~~~~~~~~~~~ -The strip filter removes all profiles and comments from your image. -Configuration looks like this: +It removes all profiles and comments from your image to reduce its file size +without degrading its quality. This filter provides no configuration options, +so you just need to enable it as follows: .. code-block:: yaml @@ -123,8 +129,7 @@ Configuration looks like this: The ``background`` filter ~~~~~~~~~~~~~~~~~~~~~~~~~ -The background filter sets a background color for your image, default is white -(#FFF). Configuration looks like this: +It sets a background color for the image. The default color is white (``#FFF``): .. code-block:: yaml @@ -134,8 +139,9 @@ The background filter sets a background color for your image, default is white filters: background: { color: '#00FFFF' } -If you provide a ``size`` it will create a new image (this size and given -color), and apply the original image on top: +By default, the background color is only visible through the transparent sections +of the image (if any). However, if you provide a ``size`` option, a new image is +created (with the given size and color) and the original image is placed on top: .. code-block:: yaml @@ -174,8 +180,10 @@ ratio. Configuration looks like this: The ``auto_rotate`` filter ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The auto_rotate filter rotates the image based on its EXIF data. **(this filter -should be called as early as possible)** Configuration looks like this: +It rotates the image automatically to display it as correctly as possible. The +rotation to apply is obtained through the metadata stored in the EXIF data of +the original image. This filter provides no configuration options, so you just +need to enable it as follows: .. code-block:: yaml @@ -185,11 +193,15 @@ should be called as early as possible)** Configuration looks like this: filters: auto_rotate: ~ +.. note:: + + This filter should be called as early as possible to get better results. + The ``rotate`` filter ~~~~~~~~~~~~~~~~~~~~~ -The rotate filter rotates the image based on specified angle (in degrees). -Configuration looks like this: +It rotates the image based on specified angle (in degrees). The value of the +``angle`` configuration option must be a positive integer or float number: .. code-block:: yaml @@ -202,7 +214,7 @@ Configuration looks like this: The ``interlace`` filter ~~~~~~~~~~~~~~~~~~~~~~~~ -Set progressive loading on the image. Configuration looks like this: +It modifies the way the image is loaded progressively: .. code-block:: yaml @@ -211,25 +223,36 @@ Set progressive loading on the image. Configuration looks like this: my_thumb: filters: interlace: - # mode can be one of none,line,plane,partition + # mode can be one of: 'none', 'line', 'plane' and 'partition' mode: line Load your Custom Filters ------------------------ The ImagineBundle allows you to load your own custom filter classes. The only -requirement is that each filter loader implement the following interface: +requirement is that each filter loader implements the following interface: ``Liip\ImagineBundle\Imagine\Filter\Loader\LoaderInterface``. To tell the bundle about your new filter loader, register it in the service container and apply the ``liip_imagine.filter.loader`` tag to it (example here in XML): -.. code-block:: xml +.. contiguration-block:: - - - + .. code-block:: yaml + + # app/config/services.yml + app.filter.my_custom_filter: + class: AppBundle\Imagine\Filter\Loader\MyCustomFilterLoader + tags: + - { name: 'liip_imagine.filter.loader', loader: 'my_custom_filter' } + + .. code-block:: xml + + + + + For more information on the service container, see the `Symfony Service Container`_ documentation. @@ -282,13 +305,14 @@ A simple example showing how to change the filter configuration dynamically. .. note:: - The constant ``Response::HTTP_MOVED_PERMANENTLY`` was introduced in version 2.4. Developers using older versions of Symfony, please replace the constant by ``301``. + The constant ``Response::HTTP_MOVED_PERMANENTLY`` was introduced in Symfony 2.4. + Developers using older versions of Symfony, please replace the constant by ``301``. Post-Processors --------------- Filters allow modifying the image, but in order to modify the resulting binary -file created by filters, you can use post-processors Post-processors should +file created by filters, you can use post-processors. Post-processors must implement ``Liip\ImagineBundle\Imagine\Filter\PostProcessor\PostProcessorInterface``. ``PostProcessorInterface::process`` method receives ``BinaryInterface`` - @@ -296,14 +320,24 @@ basically, the file containing an image after all filters have been applied. It should return the ``BinaryInterface`` as well. To tell the bundle about your post-processor, register it in the service -container and apply the ``liip_imagine.filter.post_processor`` tag to it -(example here in XML): +container and apply the ``liip_imagine.filter.post_processor`` tag to it: + +.. contiguration-block:: + + .. code-block:: yaml + + # app/config/services.yml + app.post_processor.my_custom_post_processor: + class: AppBundle\Imagine\Filter\PostProcessor\MyCustomPostProcessor + tags: + - { name: 'liip_imagine.filter.post_processor', post_processor: 'my_custom_post_processor' } -.. code-block:: xml + .. code-block:: xml - - - + + + + For more information on the service container, see the `Symfony Service Container`_ documentation. @@ -322,9 +356,9 @@ like to apply in your configuration: For an example of a post processor implementation, refer to ``Liip\ImagineBundle\Imagine\Filter\PostProcessor\JpegOptimPostProcessor``. -The ``JpegOptimPostProcessor`` can be used to provide lossless jpeg +The ``JpegOptimPostProcessor`` can be used to provide lossless JPEG optimization, which is good for you website loading speed. In order to add -lossless jpeg optimization to your filters, use the following configuration: +lossless JPEG optimization to your filters, use the following configuration: .. code-block:: yaml