Skip to content

Commit 8f4078f

Browse files
author
irishdan
committed
Update documentation
1 parent b4ee867 commit 8f4078f

File tree

4 files changed

+122
-88
lines changed

4 files changed

+122
-88
lines changed

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
## Overview:
77

88
The ResponsiveImageBundle adds the ability to easily create styled and responsive images (scaled, cropped, greyscale) in Symfony3.
9-
Responsive images are generated as <picture> tags or as <img> tags with sizes and scrset attributes.
9+
Responsive images are generated as &lt;picture> tags or as &lt;mg> tags with sizes and scrset attributes.
1010

1111
A crop and focus area widget is also provided to ensure that cropped images always include the most important part of the image.
1212

@@ -20,7 +20,7 @@ Events are used to drive the system, giving more flexibiltiy and the ability to
2020
- Images styles are defined in configuration.
2121
- Breakpoints and pictures sets are defined in configuration
2222
- Handles creation of styled images on the fly (as they are viewed) if using a local filesystem
23-
- Includes a widget to define an images crop and focus areas giving art direction to styled images.
23+
- Includes a widget to define an image's crop and focus areas giving art direction to styled images
2424

2525
## Quick and basic setup
2626

‎Resources/doc/art-direction.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,27 +3,31 @@
33
Styled images are automatically cropped which can cause important parts of the image to be cut out or partially cut out.
44
This where art direction can help.
55

6-
By defining which area of a source image is the focus area, or the most important,area of the image, we can ensure that
7-
this area is always include in any cropped images.
6+
By defining which area of a source image is the focus area, or the most important area of the image, we can ensure that
7+
this area is always included in any cropped images.
88

99
## CropFocus Widget
1010

11-
This bundle includes a widget for defining two areas on the source image.
11+
This bundle includes a widget for defining two areas on the source image:
12+
- Crop area
13+
- Focus area
14+
15+
These areas are stored together as coordinates, x1,y1,x2,y2:x1,y1,x2,y2. (crop coordinates:focus coordinates)
1216

1317
<img src="images/cropfocuswidgetlabelled.jpg" />
1418

1519
### The crop Area
1620
The crop area is an area of the image that is always removed.
1721

1822
### The focus area
19-
The focus area is an area which is never cropped out. This area is the most important part of the image
23+
The focus area is an area which is never cropped out. This area is the most important part of the image.
2024

2125
### Usage
22-
The CropFocus widget is included in the generated crud. A custom formType is included which creates a 'crop and focus widget'. This widget allows users to select an area which is always cropped out of the image, and a focus area which is always included in the image.
26+
The CropFocus widget is included in the [generated crud](commands.md#generate-image-entity-crud). A custom formType is included which creates a 'crop and focus widget'. This widget allows users to select an area which is always cropped out of the image, and a focus area which is always included in the image.
2327

2428
<img src="images/cropfocuswidget.jpg" />
2529

26-
The black area will always be cropped out for all image styles. The inner rectangle will always be fully included in styled images.
30+
The black area will always be cropped out for all image styles. The inner rectangle will always be included in styled images.
2731
There are some combinations of styles dimensions and focus dimensions where its just not possible include the whole focus rectangle.
2832
In this case the largest possible portion of the focus rectangle is included.
2933

‎Resources/doc/configuration.md

Lines changed: 91 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,101 @@
11
# Configuration
22

3-
All of the available configuration:
3+
The bundle includes default configuration for basic usage and getting started.
4+
The system needs two filesystems configured to function, see [generated crud](filesystems.md) for details.
5+
6+
A sample File system configuration:
7+
8+
```yml
9+
oneup_flysystem:
10+
adapters:
11+
images.local:
12+
local:
13+
directory: '%kernel.root_dir%/../web/%responsive_image.image_directory%' # %kernel.root_dir%/cache/
14+
images.temp:
15+
local:
16+
directory: '%kernel.root_dir%/../var/cache/resp_img'
17+
images.aws:
18+
awss3v3:
19+
client: images.s3_client
20+
bucket: 'your_bucket'
21+
prefix: 'oneup'
22+
options: { visibility: 'public-read', protocol: 'https' }
23+
filesystems:
24+
images.local:
25+
adapter: images.local
26+
alias: responsive_image_filesystem
27+
images.temp:
28+
adapter: images.temp
29+
alias: responsive_image_temp
30+
images.aws:
31+
adapter: images.aws
32+
33+
```
34+
Sample configuration for the bundle:
435

536
```
37+
#
38+
# This is the default configuration for this bundle.
39+
#
640
responsive_image:
7-
debug: FALSE # If true debug info is printed on generated images
8-
image_compression: 80 # The compression quality of the generated images
9-
image_directory: 'uploads/images' # '%uploads_directory%' # The directory where uploaded images are saved
10-
image_styles_directory: 'styles' # The directory within the uploads directory where generated images are saved
11-
image_entity_class: 'ResponsiveImageBundle\Entity\ResponsiveImage' # The image entity
12-
image_driver: gd # The php image library
13-
breakpoints: # Breakpoint definitions
14-
base: 'min-width: 0px'
15-
mobile: 'min-width: 300px'
16-
tablet: 'min-width: 480px'
17-
phablet: 'min-width: 768px'
18-
desktop: 'min-width: 1100px'
19-
tv: 'min-width: 1800px'
20-
image_styles: # Image style definitions
21-
full: # Style name
22-
effect: scale # Style effect (scale or crop)
23-
height: 200
41+
cache_bust: true
42+
image_compression: 90
43+
# image_entity_class: 'AppBundle\Entity\ResponsiveImage'
44+
image_directory: 'test/images'
45+
image_driver: 'gd'
46+
image_styles_directory: 'styles'
47+
crop_focus_widget:
48+
include_js_css: TRUE
49+
display_coordinates: TRUE
50+
# Breakpoints
51+
breakpoints:
52+
base:
53+
media_query: 'min-width: 0px'
54+
desktop:
55+
media_query: 'min-width: 1100px'
56+
tv:
57+
media_query: 'min-width: 1800px'
58+
size_mq:
59+
media_query: 'min-width: 36em'
60+
# Image styles
61+
image_styles:
2462
thumb:
25-
effect: crop
63+
effect: 'crop'
2664
width: 180
2765
height: 180
28-
project_full:
29-
effect: scale
30-
width: 940
31-
project_thumb:
32-
effect: crop
33-
width: 540
34-
height: 400
35-
picture_sets: # Picture set definitions
66+
thumb_2x:
67+
effect: 'crop'
68+
width: 360
69+
height: 360
70+
picture_thumb_base:
71+
effect: 'crop'
72+
width: 300
73+
height: 600
74+
picture_thumb_tv:
75+
effect: 'scale'
76+
width: 800
77+
height: 600
78+
greyscale: true
79+
# Sizesets
80+
size_sets:
81+
blog_sizes:
82+
fallback: 'thumb'
83+
sizes:
84+
10vw:
85+
breakpoint: 'size_mq'
86+
srcsets: [ 'thumb', 'picture_thumb_base', 'picture_thumb_tv' ]
87+
# Picture sets
88+
picture_sets:
3689
thumb_picture:
37-
base: # Breakpoint name
38-
effect: crop # Style effect
39-
width: 300
40-
height: 600
41-
mobile:
42-
effect: crop
43-
width: 480
44-
height: 300
45-
tablet:
46-
effect: crop
47-
width: 400
48-
height: 700
49-
phablet:
50-
effect: crop
51-
width: 180
52-
height: 380
53-
desktop: thumb # To use a pre-defined style just use its name
54-
tv:
55-
effect: crop
56-
width: 300
57-
height: 500
58-
crop_focus_widget: # Crop focus widget settings
59-
include_js_css: TRUE # If true widget js css is included in the field html. Otherwise add it manually.
60-
display_coordinates: TRUE # Toggles between a text field or hidden field.
61-
aws_s3:
62-
enabled: FALSE
63-
remote_file_policy: STYLED_ONLY # STYLED_ONLY, ALL
64-
temp_directory: 'tmp/' # will be created within the symfony directory
65-
protocol: 'http'
66-
bucket: 'bucket_name'
67-
region: 'eu-west-1'
68-
version: 'latest'
69-
directory: 'directory_name'
70-
access_key_id: KEY_ID
71-
secret_access_key: ACCESS_SECRET
90+
fallback: 'thumb'
91+
sources:
92+
base: 'picture_thumb_base'
93+
desktop: 'thumb'
94+
tv: 'picture_thumb_tv'
95+
blog_picture:
96+
fallback: 'thumb'
97+
sources:
98+
base: 'picture_thumb_base'
99+
desktop: 'thumb'
100+
tv: 'picture_thumb_tv'
72101
```

‎Resources/doc/filesystems.md

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,46 @@
11
# Filesystems
22

3-
This bundle reuires the [OneUpFlysystem bundle]() which uses [flysystem]() library under the hood.
3+
This bundle requires the [OneUpFlysystem bundle](https://github.com/1up-lab/OneupFlysystemBundle) which uses [FlySystem](http://flysystem.thephpleague.com/) library under the hood.
44

5-
This allows images to be stored on muliplte filesystems which can be local or remote eg on amazons S3
5+
This allows images to be stored on multiple filesystems which can be local or remote eg on amazons S3
66

77
## What is a filesystem?
88

99
A filesystem is simply a place to store files. The place could be Local (on the same server as your symfony project)
1010
or remote, perhaps on an amazon S3 bucket.
1111

12-
Flysystem lets us define multiple filesystems with handy methods for access files on that filesystem.
12+
[FlySystem](http://flysystem.thephpleague.com/) lets us define multiple filesystems with handy methods for access files on that filesystem.
13+
Each Filesystem needs an adapter.
14+
[FlySystem](http://flysystem.thephpleague.com/) Includes adapters for most of the common storage solutions.
1315

1416
## Configuration
1517

16-
Basically a filesystem needs an adapter.
17-
18-
For more
18+
Currently the system requires a temporary local filesystem and a default filesystem to be configured.
1919

2020
```yml
2121
oneup_flysystem:
2222
adapters:
23-
image.local:
23+
images.local:
2424
local:
2525
directory: '%kernel.root_dir%/../web/%responsive_image.image_directory%' # %kernel.root_dir%/cache/
26-
image.temp:
26+
images.temp:
2727
local:
2828
directory: '%kernel.root_dir%/../var/cache/resp_img'
29-
image.aws:
29+
images.aws:
3030
awss3v3:
31-
client: nomad.s3_client
32-
bucket: 'danbyrnebucket'
31+
client: images.s3_client
32+
bucket: 'your_bucket'
3333
prefix: 'oneup'
3434
options: { visibility: 'public-read', protocol: 'https' }
3535
filesystems:
36-
nomad.local:
37-
adapter: image.local
36+
images.local:
37+
adapter: images.local
3838
alias: responsive_image_filesystem
39-
nomad.temp:
40-
adapter: image.temp
39+
images.temp:
40+
adapter: images.temp
4141
alias: responsive_image_temp
42-
nomad.aws:
43-
adapter: image.aws
44-
# alias: responsive_image_filesystem
42+
images.aws:
43+
adapter: images.aws
4544
```
45+
46+
### Switching Filesystems at run time

0 commit comments

Comments
 (0)