source: spip-zone/_plugins_/adaptive_images/trunk/lib/AdaptiveImages/README.md @ 115788

Last change on this file since 115788 was 115788, checked in by cedric@…, 8 months ago

Mise a jour de la lib AdaptiveImage? : meilleure optimisation de la vignette (taille plus petite+filtre blur) et markup <picture> au lieu de <span> (sans modif de la technique)

File size: 6.0 KB
Line 
1AdaptiveImages
2==============
3
4## What is it?
5This is the standalone PHP implementation of "3-layer technique" for Adaptive Images generation.
6See <http://openweb.eu.org/277> for technical explanations and justifications (french version available : <openweb.eu.org/280>)
7
8## Requirements
9
10PHP>=5.1 with GD library
11(if PHP<5.3.0 extending `AdaptiveImages` also needs to override method `getInstance()`)
12
13
14## Using
15
16### Simple use-case
17
18Call `adaptHTMLPage` method on your HTML page with optional maximum display width of images in your HTML page.
19
20<pre>
21require_once "AdaptiveImages.php"
22$AdaptiveImages = AdaptiveImages::getInstance();
23$html = $AdaptiveImages->adaptHTMLPage($html,780);
24</pre>
25
26First view of page with adaptive Images can timeout due to all the images to generate. Reload the page to complete image generation.
27
28### Caching
29
30If your CMS/application allow caching of HTML part of pages, apply `adaptHTMLPart` method on this part in order to cache Adaptive Images
31
32<pre>
33require_once "AdaptiveImages.php"
34$AdaptiveImages = AdaptiveImages::getInstance();
35return $AdaptiveImages->adaptHTMLPart($texte, 780);
36</pre>
37
38then recall `adaptHTMLPage` method on full HTML page to finish the job
39
40<pre>
41$AdaptiveImages = AdaptiveImages::getInstance();
42$html = $AdaptiveImages->adaptHTMLPage($html,780);
43</pre>
44
45### URL vs filepath
46
47By default AdaptiveImages considers that relative URLs are also relative file system path.
48If this is not the case in your URL scheme, you can override the 2 methods `URL2filepath` and `filepath2URL` that are used to make transpositions.
49
50In the following example we transpose absolutes URLs to relative file system path and, if defined we add special domain `_ADAPTIVE_IMAGES_DOMAIN` to file path in the final URL (domain sharding)
51
52<pre>
53class MyAdaptiveImages extends AdaptiveImages {
54        protected function URL2filepath($url){
55                $url = parent::URL2filepath($url);
56                // absolute URL to relative file path
57                if (preg_match(",^https?://,",$url)){
58                        $base = url_de_base();
59                        if (strncmp($url,$base,strlen($base))==0)
60                                $url = _DIR_RACINE . substr($url,strlen($base));
61                        elseif (defined('_ADAPTIVE_IMAGES_DOMAIN')
62                          AND strncmp($url,_ADAPTIVE_IMAGES_DOMAIN,strlen(_ADAPTIVE_IMAGES_DOMAIN))==0){
63                                $url = _DIR_RACINE . substr($url,strlen(_ADAPTIVE_IMAGES_DOMAIN));
64                        }
65                }
66                return $url;
67        }
68
69        protected function filepath2URL($filepath){
70                $filepath = parent::filepath2URL($filepath);
71                if (defined('_ADAPTIVE_IMAGES_DOMAIN')){
72                        $filepath = rtrim(_ADAPTIVE_IMAGES_DOMAIN,"/")."/".$filepath;
73                }
74                return $filepath;
75        }
76}
77$AdaptiveImages = MyAdaptiveImages::getInstance();
78</pre>
79
80### Markup Hook
81
82If source `<img/>` has some inline styles, it can be needed to add some wrapper and put the style on it on order to keep initial visual result.
83This can be done in overriding the method `imgMarkupHook(&$markup,$originalClass,$originalStyle)`.
84It is call with following arguments
85- partial adaptive markup (only the `<span>` wrapper with the fallback `<img/>` inside)
86- the original class attribute of `<img/>`
87- the original style attribute of `<img/>`
88
89The method must return the partial markup, with your modifications.
90
91### OnDemand images generation
92
93To avoid timeout on first view of HTML page you can activate OnDemand images generation. In this case, only URL of adapted images will be computed, and you need to use a Rewrite Rules and a router to call `AdaptiveImages::deliverBkptImage`.
94
95For instance with SPIP CMS :
96
97#### Rewrite Rule
98
99<pre>
100###
101# If file or directory exists deliver it and ignore others rewrite rules
102RewriteCond %{REQUEST_FILENAME} -f
103RewriteRule "." - [skip=100]
104RewriteCond %{REQUEST_FILENAME} -d
105RewriteRule "." - [skip=100]
106#
107###
108
109###
110# Adaptive Images : call action_adapt_img_dist() function if image not available
111
112RewriteRule \badapt-img/(\d+/\d\dx/.*)$ spip.php?action=adapt_img&arg=$1 [QSA,L]
113
114# Fin des Adaptive Images
115###
116</pre>
117
118#### Router
119
120<pre>
121function action_adapt_img_dist(){
122
123        $AdaptiveImages = AdaptiveImages::getInstance();
124        try {
125                $AdaptiveImages->deliverBkptImage(_request('arg'));
126        }
127        catch (Exception $e){
128                http_status(404);
129                die('Error : '.$e->getMessage());
130        }
131        exit;
132}
133</pre>
134
135## Advanced Configuration
136
137* Directory for storing adaptive images
138  <pre>$AdaptiveImages->destDirectory = "local/adapt-img/";</pre>
139* Default Maximum display width for images
140  <pre>$AdaptiveImages->maxWidth1x = 640;</pre>
141* Minimum display width for adaptive images (smaller will be unchanged)
142  <pre>$AdaptiveImages->minWidth1x = 320;</pre>
143* Maximum width for delivering mobile version in data-src-mobile=""
144  <pre>$AdaptiveImages->maxWidthMobileVersion = 320;</pre>
145* Activade On-Demand images generation
146  <pre>$AdaptiveImages->onDemandImages = true;</pre>
147* Background color for JPG lowsrc generation (if source has transparency layer)
148  <pre>$AdaptiveImages->lowsrcJpgBgColor = '#eeeeee';</pre>
149* Breakpoints width for image generation
150  <pre>$AdaptiveImages->defaultBkpts = array(160,320,480,640,960,1440);</pre>
151* Allow progressive rendering og PNG and GIF even without JS :
152  <pre>$AdaptiveImages->nojsPngGifProgressiveRendering = true;</pre>
153* Max width for the JPG lowsrc fallback image (thumbnail preview)
154  <pre>$AdaptiveImages->maxWidthFallbackVersion = 160;</pre>
155* JPG compression quality for JPG lowsrc
156  <pre>$AdaptiveImages->lowsrcJpgQuality = 40;</pre>
157* JPG compression quality for 1x JPG images
158  <pre>$AdaptiveImages->x10JpgQuality = 75;</pre>
159* JPG compression quality for 1.5x JPG images
160  <pre>$AdaptiveImages->x15JpgQuality = 65;</pre>
161* JPG compression quality for 2x JPG images
162  <pre>$AdaptiveImages->x15JpgQuality = 45;</pre>
163* GD maximum px size (width x height) of image that can be manipulated without Fatal Memory Error (0=no limit)
164  <pre>$AdaptiveImages->maxImagePxGDMemoryLimit = 2000*2000;</pre>
165
166
167## Real-life use case
168
169This library is already available through plugins in:
170
171* SPIP CMS <http://contrib.spip.net/Adaptive-Images-4458> [See the implementation](http://zone.spip.org/trac/spip-zone/browser/_plugins_/adaptive_images/trunk/adaptive_images_options.php)
172* DotClear blog engine <http://plugins.dotaddict.org/dc2/details/adaptiveImages>
Note: See TracBrowser for help on using the repository browser.