Helpfile for imageTweak

##~~ filter:imageTweak ~~

Attention: imageTweak provide a kitCommand and a kitFilter, this is the helpfile for the kitFilter.

The kitFilter ~~ filter:imageTweak ~~ check all images at the actual shown page of your Content Management System, check the sizes, re-sample them if necessary, reduce the traffic and speed up your Website.

imageTweak does not need any parameters or special handling. Just place the kitFilter

~~ filter:imageTweak ~~

within the index.php file(s) of the template(s) you are using for your Website. The filter can be placed anywhere, we propose to place the kitFilter just before the closing body tag </body> of your template.

That is really all!

imageTweak will still do the rest:

check all images which are placed in the /media directory of your CMS or in the kit2/media directory of the kitFramework
if the width and height attribute of the image tag are smaller than the original size of the image, imageTweak will re-sample this image and create a new optimized one which fit exactly to the specified width and height
save optimized images in the path /kit2/media/tweaked
will only re-sample images if necessary and only if a re-sampled file does not exist or if the original file has changed (imageTweak is checking the modification date/time)

The filtering process is silent, imageTweak will not prompt any messages or dialogs at your website.

If any problem occur, imageTweak will log this at the kitFramework /logfile/kit2.log. By the default configuration of the kitFramework you will receive also an email with all information you need. You will also receive a error message if a image does not exists.

If you want to check whether imageTweak is working just check a image which should be processed by the filter. You can also switch on the DEBUG mode of the kitFramework - in /kit2/config/framework.json set "DEBUG": true,. In DEBUG mode imageTweak will add a log entry if a image will re-sampled and created.

imageTweak will also:

add missing height or width attributes
add missing alt or title attributes
rewrite width and height information specified in a style attribute (like the CKEditor do) to regular height and width attributes.

You can specify the behavior of imageTweak in the configuration file:

/kit2/extension/phpmanufaktur/phpManufaktur/imageTweak/config.imagetweak.json

here you can switch off imageTweak:

"enabled": false,

or adapt the handling for alt and title attributes:

"image": {
    "alt": {
      "default": "- no image description available -",
      "set": true
    },
    "title": {
      "default": "- no image description available -",
      "set": true
    }
},

imageTweak also support jQuery image tools like the Fancybox, Slimbox or Lightbox.

imageTweak expect that you have installed and configured the needed jQuery files. If you are using the LibraryAdmin for WebsiteBaker, LEPTON CMS or BlackCat CMS you can create default Presets for the Fancybox and for the Slimbox2. For these both Presets imageTweak comes with a native support.

How does it works?

In your WYSIWYG editor insert a new image in full size and specify the width and height for the preview
if you are using the Fancybox add the class tweak-fancybox to the image
if you are using the Slimbox2 add the class tweak-slimbox to the image
save the page and open it in your browser.

imageTweak will automatically add a <a href=" ... > ... </a> around this image, link to the image in full size, create an optimized image for the preview and set all needed attributes within the embedding link.

You can adapt the handling for the Fancybox and for the Slimbox in the config.imagetweak.json:

"embed": {
    "fancybox": {
      "image": {
        "class": "tweak-fancybox",
        "remove": true
      },
      "element": "a",
      "attribute": {
        "href": "{src}",
        "title": "{title}",
        "class": "grouped_elements",
        "rel": "fancybox"
      }
    },
    "slimbox2": {
      "image": {
        "class": "tweak-slimbox",
        "remove": true
      },
      "element": "a",
      "attribute": {
        "href": "{src}",
        "title": "{title}",
        "rel": "lightbox"
      }
    }
}

You can add or remove attributes as you need and you can also add further handlings - still use the same scheme.

{src} and {title} are placeholders for the corresponding image tags.

In some situations you may want that an image will not optimized. In this case just add the class tweak-ignore to the image and imageTweak will skip it.

hertsch/kitfilter_imagetweak_en.md