directResize
- Features
- How it works
- Installation
- Plugin configuration
- Standard configuration
- Quick start
- Parameters
- Placeholders
- Labels
- Known Issues
- Special Thanks
DirectResize is a fully customizable plugin with a number of functions like: automatic thumbnails creation, watermarking (text or transparent PNG), using config files to set plugin parameters, big images openning with AJAX (lightbox, slimbox, highslide…), fully templateable output, thumbnails for WYSIWYG-editor etc…
Features
-
Possible to integrate any javascript display mode: Slidebox, Lightbox v2.0, Slimbox, Highslide etc
-
Watermarking (text or transparent PNG)
-
Plugin settings in the config file with a big number of plugin parameters
-
Fully templateable output
-
Using plugin to show a remote images
-
Special preview for WYSIWYG-editor (tested with TinyMCE)
-
Creation of thumbnails with cropping
-
New images will be generated if it is needed, in other cases they will be taken from the cache
-
Support for JPG and PNG files (GIF is not currently supported)
How it works
First of all this plugin is intended for using with the WYSIWYG-editor and the target audience of plugin users is the clients who doesn't have any knowledges in web-development and HTML and who needs to use images in the text with thumbnails. It would be rather uneasy to explain such man that firstly it is necessary to create the reduced copy of the image, then to insert it into the document through the WYSIWYG-editor and after it to make a hyperlink to the big image.
So the actions have been simpified to the minimum - when the big image is inserted to the text and the sizes of the thumbnail are established the plugin will create automatically the thumbnail with needed hyperlinks.
Also while the opening of a document that has such images the thumbnails will be displayed with a special watermark in the WYSIWYG-editor instead of the big images. This watermark speaks conditionally that the given image is not small image only but it is a hyperlink to the big image and it allows to tell the difference between such images and the really small images that can be in the document.
If the sizes of the thumbnails is changed then in the next using of the plugin will be created new thumbnails in compliance with new sizes.
Of course you can use the plugin without the WYSIWYG-editor simply when you insert the image as HTML-code and point the attributes "width" and "height" that are smaller than the real sizes.
Installation
-
Extract the contents of the zip file to your computer
-
FTP to your server an go to the Evo installation folder
-
Put the extracted assets folder to the site root and the files will go to correct place
-
Make the assets/drgalleries/ folder writable (CHMOD 777 unless you are in phpSuExec environment, in that case CHMOD 755)
-
Close your FTP program and go to the Evo admin interface
-
Create new plugin called DirecrResize and paste the contents of directResize.plugin.txt to it
-
Copy and Paste the following into "Plugin configuration" on the Configuration tab
&config=Configuration;string;highslide &clearCache=Cache clear mode;list;0,1,2;0
- On the "System event" tab check OnWebPagePrerender, OnCacheUpdate, OnBeforeDocFormSave, OnDocFormPrerender
- Save
Plugin configuration
There are two parameters on the tab "Configuration" of the plugin settings page. The parameter "Configuration" is the name of used configuration. The file with the same name and the suffix ".config.php" should be placed in the plugin folder "configs". This parameter and the related file are mandatory.
"Cache clear mode" option. Plugin cache is cleared when the system cache is cleared.
- 0 - clearing is off
- 1- clear cache only for edited document when saving
- 2- clear cache for all documents
Updating the cache is required in rare cases. For example, when needed to delete image files referred to in the documents no longer exist. Or when changing watermark. New images are generated only if changes in their size. Therefore, new watermarks are not marked because the size of the images have not changed. In this case, the cache is required to update to remove images and generate them again.
In other cases, the plugin generates new images without the need to update the cache. So, in most cases, better to set Cache clear mode = 0
Standard configuration
Plugin already has a set of several standard configurations that allow used the effects slimbox, slidebox, lightbox, highslide on the site without any configuration. To connect one of the configurations, it is necessary to set the configuration name in the field Configuration on the configuration tab of the plugin. Possible values:
- slimbox
- slidebox
- lightboxv2
- highslide
Additional configuration is in the config files in "assets/plugins/directresize/configs" folder. Look for highslide.config.php as example. Be sure to customize the list of folders in which images are allowed to proccesed by the plugin. Default folder for images is assets/images.
Plugin uses the same js-libraries as Maxigallery, but from own folder, so if you use Maxigallery on your site with the same effect of opening images as DirectResize, use parameter $maxigallery_jscss_packs to avoid re-connect libraries.
Quick start
-
Install the plugin (see installation and plugin configuration above), make sure that there is drgalleries subfolder in assets folder with write permissions.
-
Set one of the standart configuration in plugin configuration tab - slimbox, slidebox, lightboxv2, highslide
-
Make sure that the source image files are located in a folder assets/images or its subfolders
-
To force the plug to create thumbs and open images with selected effect, it's mandatory to set width and/or height for img tags equal width and height of thumbnail. I.e. for image
<img src="assets/images/image.jpg" width="120" height="60" />
will be genereated thumbnail with sizes 120х60. Naturally, the original image.jpg must exceed 120х60 size (otherwise there is no point in creating preview).
Parameters
Parameters to used in the config file. The file must be placed in the "/assets/plugins/directresize/configs" folder with name "ConfigName.config.php", where ConfigName is a string from "Configuration" field on the configuration tab of the plugin.
Parameter | Possible values | Default value | Description, example |
---|---|---|---|
$lightbox_mode |
|
1 | Mode of creation of big images and lightbox-links
|
$allow_from | "assets/images" | A comma-separated list of folders where it is allowed to use the plugin. It is possible to specify a remote resources. All paths that is not specified in this parameter prohibited. Only relative path from site root or remote path with http:// allowed. This parameter is not considered if $lightbox_mode = 1 |
|
$deny_from | A comma-separated list of folders where it is not allowed to use the plugin. It is possible to specify a remote resources. All paths that is not specified in this parameter allowed. Only relative path from site root or remote path with http:// allowed. It is ignored if there is the parameter $allow_from. This parameter is not considered if $lightbox_mode = 1 |
||
$allow_from_allremote |
|
0 | This parameter allowed to use plugin on all images from remote sources w/o needed to list them all in $allow_from |
$resize_method |
|
3 | Method of image resizing. It is used while generating thumbnails. In all cases proportions of the image will be saved. imgWidth and imgHeight are parameters of the original image.
|
$big_quality | integer 1-100 | 80 | JPG-quality of big image |
$thumb_quality | integer 1-100 | 80 | JPG-quality of thumbnails |
$wysiwyg_quality | integer 1-100 | 40 | JPG-quality of thumbnails in the WYSIWYG editor |
$big_width | integer | 800 | If the size of original image exceeds given sizes $big_width or $big_height it will generate image that is proportionally reduced from the original image ("big image" in the plugin terminology) with width and height that are not exceeded $big_width and $big_height. |
$big_height | integer | 600 | |
$thumb_default_width | integer | Default width of thumbnail | |
$thumb_default_height | integer | Default height of thumbnail | |
$thumb_default_sizemode |
|
1 | The rule for using width and height of thumbnails by default.
Notice: despite of the parameters $thumb_default_width, $thumb_default_height and $thumb_default_sizemodethe final sizes of generated thumbnail will calculate depending on $resize_method If you are using force mode (4) together with TinyMCE, width and height of source images in content will be replaced with $thumb_default_width and $thumb_default_height, original with and heigh will be lost after saving document. Its needed for correct displaying of thumbnails in visual mode. |
$remote_refresh_time | integer | 60 | Time in minutes. This is a frequency of image checking on the remote servers. If image is changed (it checks height and width only) then it will create a new local copy of image and regenerate thumbnails. |
$tpl |
|
assets/plugins/ directresize/templates/ lightboxv2.html | Output template |
$language |
|
english | It sets the plugin language. The corresponding language file should be placed in the folder "lang" of plugin. |
$header | HTML-code | HTML-code that will be placed in the <head> section. It includes necessary css and js files. It uses only on the web pages that have at least one plugin-processed image. | |
$maxigallery_jscss_packs |
|
It includes necessary css and js files to the web page for corresponding script from the folder of MaxiGallery snippet (it is not necessarily to install this snippet but it's files should be placed in the folder assets/snippets/maxigallery). It is useful if you are using this plugin with Maxigallery in the same project. If any js or css files are attached already by MG, DirectResize won't include these files again in the <head> section. |
Here are the parameters taken from Maxigallery having the same meaning and processed in the same way.
Parameter | Possible values | Default value | Description |
---|---|---|---|
$use_ftp_commands |
|
0 | If enabled, DirectResize uses PHP FTP commands to create filesystem folders for the gallery pictures. This is needed in certain server environments. |
$ftp_server | FTP address | FTP address to the server running Evo. | |
$ftp_user | username | FTP account username | |
$ftp_pass | password | FTP account password | |
$ftp_base_dir | path | Path to go from FTP root to Evo installation root. Eg. if your FTP root directory is /home/username/ and Evo is installed in /home/username/public_html/Evo/ you would use /public_html/Evo/ as ftp_base_dir. | |
$ftp_port | number | 21 | Port number for the FTP service. |
$thumb_use_watermark |
|
0 |
Watermark the thumbnail images. |
$thumb_watermark_font |
|
1 | Font size of the watermark text |
$thumb_watermark_halign |
|
right | Horizontal alignment of the watermark. |
$thumb_watermark_img | path | assets/plugins/ directresize/ images/watermark.png | Path to a watermark image. Use a png image with a transparent background alpha layer. |
$thumb_watermark_txt | text | Copyright <YEAR> | Text that will be applied to the images as a watermark. |
$thumb_watermark_txt_color | RGB Hexadecimal | FFFFFF | Color of the watermark text. |
$thumb_watermark_txt_hmargin | Number (px) | 2 | Horizontal margin of the watermark text. |
$thumb_watermark_txt_vmargin | Number (px) | 2 | Vertical margin of the watermark text. |
$big_use_watermark |
|
0 |
Watermark big images. |
$big_watermark_font |
|
1 | Font size of the watermark text |
$big_watermark_halign |
|
right | Horizontal alignment of the watermark. |
$big_watermark_img | path | assets/plugins/directresize/ images/watermark.png | Path to a watermark image. Use a png image with a transparent background alpha layer. |
$big_watermark_txt | text | Copyright <YEAR> | Text that will be applied to the images as a watermark. |
$big_watermark_txt_color | RGB Hexadecimal | FFFFFF | Color of the watermark text. |
$big_watermark_txt_hmargin | Number (px) | 2 | Horizontal margin of the watermark text. |
$big_watermark_txt_vmargin | Number (px) | 2 | Vertical margin of the watermark text. |
Placeholders
Placeholders for use in $tpl template.
Placeholder | Description |
---|---|
[+dr.id+] | the numeric identifier of the image, unique within the current document |
[+dr.alt+] [+dr.title+] [+dr.class+] [+dr.style+] [+dr.align+] [+dr.valign+] |
attributes alt, title, class, style, align, valign of the original image |
[+dr.thumbWidth+] | width of the generated thumbnail |
[+dr.thumbHeight+] | height of the generated thumbnail |
[+dr.thumbPath+] | path to the generated thumbnail file |
[+dr.thumbFilesize+] | formatted size of the generated thumbnail file |
[+dr.bigWidth+] | width of the generated big image (if big image is not generated - width of the original image) |
[+dr.bigHeight+] | height of the generated big image (if big image is not generated - height of the original image) |
[+dr.bigPath+] | path to the generated big image file (if big image is not generated - path to the original image file ) |
[+dr.bigFilesize+] | formatted size of the generated big image file (if big image is not generated - formatted size of the original image file) |
[+dr.originalWidth+] | width of the original image |
[+dr.originalHeight+] | height of the original image |
[+dr.originalPath+] | path to the original image |
[+dr.originalFilesize+] | formatted size of the original image file |
[+dr.originalFilename+] | filename of the original image |
Labels
Label - in terminology of this plugin it is a special word (or part of word) that may use within the img tag at any place - within attributes class, alt, title and so on and it manages some actions with given image (and with it only).
For example, if the value of parameter $lightbox_mode = 1 then the thumbnail with lightbox-link generates only for image with drlightbox label.
Examples of images with drlightbox label:
<img src="image.jpg" alt="drlightbox" />
<img src="image.jpg" class = "drlightbox_align_left" />
<img src="image.jpg" title = "drlightbox picture" />
<img src="image.jpg" style = "background: url(drlightbox_bg.gif);" />
<img src="assets/images/mydrlightboxpicture.jpg" />
- and even
<img src="image.jpg" drlightbox />
Don't worry about validation errors in html code if you are used labels in unallowed places. All labels will be removed from output html. So avoid to name the image files with label names - filename or part of the filename can be replaced. Warning:don't use labels outside the attributes (as in last example) if you are using WYSIWYG-editor, because labels will be removed by an editor as incorrect html-code.
Label drthumbonly. It makes sense if only parameter $lightbox_mode = 2 and it shows that plugin should not generate big image and lightbox-link for the given image but thumbnail only.
If the value of parameter $lightbox_mode = 1 plugin generates the thumbnails without lightbox-link for all images, so using of drthumbonly is redundant in that case.
Label drskip. Plugin is skip processing of the image. Thumbs and lightbox link is not created.
Known issues
I don't know simple way in PHP < 5.0 to check is the file is exist on the remote host, so if you are useing plugin with remote images and remote image with current path is no exist on remote server - there will be a php error.
Special thanks
This version of the plugin is based on idea and developments of Arnaud, the author of previous versions of the DirectResize.
Plugin is using parts of code from Maxigallery snippet by doze. This document is using part of the documentation from Maxigallery.
Plugin is using Chunkie class and PHx parser by bS
Plugin is using Thumbnail and Watermark Class by Emilio Rodriguez
As example is used Highslide JS script by Torstein Honsi
The biggest part of this document was translated in to english by Igor from the Russian Evo Community
Thanks, guys!
Metaller (metaller.ru@gmail.com)
Suggest an edit to this page.