.. You may want to use the usual include line. Uncomment and adjust the path. 
.. include:: ../Includes.txt


===========
RandomImage
===========

:Author:
      Kasper Skårhøj

:Created:
      2002-11-01T00:32:00

:Changed:
      2004-12-30T11:24:54

:Email:
      r.fritz@colorcube.de

:Info 2:


:Info 3:


:Info 4:


.. _RandomImage:

RandomImage
===========

Extension Key:  **cc\_random\_image**

Copyright 2000-2002, , <r.fritz@colorcube.de>

**Thanks to Nigel Jackson <nigelj@pobox.com> for proof reading
(V.1).**

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

\- a GNU/GPL CMS/Framework available from www.typo3.com

.. _Table-of-Contents:

Table of Contents
-----------------

**RandomImage 1**

**Introduction 2**

**Adminstration 2**

**Configuration 3**

Reference 4

**Tutorial 5**

Example 1 5

Example 2 6

Example 3 7

Example 4 9

**Known problems 9**

**Changelog 9**


.. _Introduction:

Introduction
------------

The RandomImageextension provides the functionality to display one or
more images, selected at random, from a collection of image files. The
script selects each image only once per page, even if several
RandomImage objects are on the page.

RandomImage is not designed as an out-of-the-box content element,
because it is mainly used within TypoScript templates. In this case
the developer will write his own TypoScript to display the images.

|img-1|

The example above is a page from `http://www.up-and-coming.de
<http://www.up-and-coming.de/>`_ , which shows a randomly selected
images in the top of the page.


.. _Adminstration:

Adminstration
-------------

There is an install option in the extension manager to enable a plugin
content element  *RandomImage* .

|img-2| By default this option is not enabled. If you do, you can
insert the plugin as content element:

|img-3| This Plugin content element doesn't make much sense because
it's very rarely used. But for demonstration purposes it's included.


.. _Configuration:

Configuration
-------------

You can use the plugin in two ways:

- the plugin is embedded in your TypoScript template
  (plugin.tx\_ccrandomimage\_pi1)

- if enabled, the Plugin content element (plugin.tx\_ccrandomimage\_pi2)

For both there are predefined TypoScript setups which have to be
modified to fit to your needs. These can be activated by adding the
static templates to your template:

|img-4|

Anyway, it is possible to use the setup as it is (without
customization), but you have to set a path to your image files. This
can be done with the Template Constant Editor:

|img-5|


.. _generated:

((generated))
^^^^^^^^^^^^^

.. _generated:

((generated))
"""""""""""""

.. _generated:

((generated))
~~~~~~~~~~~~~

.. _plugin-tx-ccrandomimage-pi1:

plugin.tx\_ccrandomimage\_pi1
'''''''''''''''''''''''''''''

The following TypoScript code is included in the extension as example.

::

   includeLibs.tx_ccrandomimage = EXT:cc_random_image/pi1/class.tx_ccrandomimage_pi1.php
   
     // USER_INT means 'no caching'
   
   plugin.tx_ccrandomimage_pi1 = USER_INT
   plugin.tx_ccrandomimage_pi1 {
   
     path = {$plugin.tx_ccrandomimage_pi1.path}
     fileExt = jpg,jpeg,gif,png
   
     renderObj = COA
     renderObj {
       wrap = {$content.wrap.bodytext}
   
       10 = IMAGE
       10.file = ###FILE_1###
       10.wrap = |<br><br>
   
       20 = IMAGE
       20.file = ###FILE_2###
     }
   }

You can set the TS constant  *plugin.tx\_ccrandomimage\_pi1.path* with
the Template Constant Editor to configure the image path.


.. _plugin-tx-ccrandomimage-pi2:

plugin.tx\_ccrandomimage\_pi2
'''''''''''''''''''''''''''''

The TS setup for the Plugin content element (pi2) is the same as for
the pi1 plugin, except the additional line

::

     overrideSetup.field = bodytext

This makes it possible to override the setup from a content element
*plugin* , by putting TS code in the  *TypoScript Setup* field.


.. _Caching:

Caching
'''''''

Both plugins are configured as non-cached objects. This means with
every page reload the script will be called and displays newly
selected images by random. You can change this behavior to cached
object by putting the following in your TS setup:

::

   plugin.tx_ccrandomimage_pi1 = USER
   plugin.tx_ccrandomimage_pi2 = USER

With this configuration you'll get random images on new page rendering
only. With TYPO3's default setup this will be once per day.


.. _Reference:

Reference
^^^^^^^^^


.. _generated:

((generated))
"""""""""""""

.. _generated:

((generated))
~~~~~~~~~~~~~

.. _Marker:

Marker
''''''

The marker you can use are:

###FILE\_PATH### - the base path to the files

###FILE\_x### - file name with path

###FILE\_x\_NAME### - file name without path

The numbering of the marker have to begin with 1. The script stops to
substitute marker if it does not find one. This means, using the
marker ###FILE\_1### and ###FILE\_3### the later will not be
substituted.

**Hint:**

The RandomImage script do nothing else than substituting the
###FILE\_x### and ###FILE\_x\_NAME### (file name without path) markers
with randomly selected file names. Thereafter the renderObj will be
rendered. The renderObj don't have to be of the type COA and there
don't have to be IMAGE objects in it.

Try this:

::

   renderObj = TEXT
   renderObj {
     wrap = {$content.wrap.bodytext}
     value = ###FILE_1###
   }


.. _TS-Properties:

TS Properties
'''''''''''''

.. ### BEGIN~OF~TABLE ###


.. _path:

path
####

.. container:: table-row

   Property
         path
   
   Data type
         string/stdWrap
   
   Description
         Path to the folder containing the image files.
         
         Example:
         
         fileadmin/rndImg/
   
   Default



.. _fileExt:

fileExt
#######

.. container:: table-row

   Property
         fileExt
   
   Data type
         string/stdWrap
   
   Description
         Comma separatedlist of file extensions that should be looked for:
         
         jpg,jpeg,gif,png
   
   Default



.. _renderObj:

renderObj
#########

.. container:: table-row

   Property
         renderObj
   
   Data type
         cObject
   
   Description
         Could be any content object. For example six IMAGE objects inside a
         COA object.
         
         The plugin substitutes the ###FILE\_x### and ###FILE\_x\_NAME### (file
         name without path) markers with randomly selected image files names
         before rendering inside the TypoScript setup.
         
         ###FILE\_PATH### contain the path to the files (see above).
         
         Example:
         
         ::
         
            renderObj = COA
            renderObj {
            
                10 = IMAGE
                10.file = ###FILE_1###
                    10.wrap = |<br><br>
            
                20 = IMAGE
                20.file = ###FILE_2###
            }
   
   Default



.. _overrideSetup:

overrideSetup
#############

.. container:: table-row

   Property
         overrideSetup
   
   Data type
         string/stdWrap
   
   Description
         This can be used to override the plugins TS setup. In the standard
         code it is defined as
         
         ::
         
            overrideParms.field = bodytext
         
         which makes it possible to override the setup from a content element
         *plugin* or  *script* , by putting TS code in the  *TypoScript Setup*
         or  *Parameters* field.
   
   Default


.. ###### END~OF~TABLE ######

[tsref:plugin.tx\_ccrandomimage\_pi1]


.. _Tutorial:

Tutorial
--------

The first example shows the pre-configured usage with a Plugin content
element. Later, in the Tutorial section, you'll see other usages of
RandomImage inside of templates. In fact the usage as Plugin content
element isn't really needed. Just use it as an example.


.. _Example-1:

Example 1
^^^^^^^^^

The extension provides example code which will show output on the page
without much configuration and work as Plugin content element. To make
this example work you have to enable the extensions option  *Ctype
Plugin* in the extension manager.

1. First of all you need a collection of images that you want to
display (in jpg, pngor gifformats). Place them in a folder somewhere
inside of fileadmin/. Note that the images should be pre-sized to the
right dimensions because the default TypoScript setup don't have any
image resizing configured (look at example 3).

2. Add the pi2 static template to your TS template.

3. Set the path to your image collection with the Template Constant
Editor or insert a line in your the constants field of your template
by hand.

Example:

::

   plugin.tx_ccrandomimage_pi2.path = fileadmin/demo_img_x220/

4. Add a new Plugin content element to your page, and select the
plugin RandomImage.

Now the images should appear on the web page....

If not, check if the path is set correctly and if other content
element render properly.

You can use a custom TypoScript setup by putting TS code in the
*TypoScript Setup* field. Try this:

::

   path = fileadmin/demo_img_x220/
   fileExt = jpg,jpeg,gif,png
   
   renderObj = IMAGE
   renderObj.wrap = <div style="margin: 5px; border: green 2px solid"> | </div>
   renderObj.file = GIFBUILDER
   renderObj.file {
     format = jpg
     XY = [10.w], [10.h]
    
     10 = IMAGE
     10.file = ###FILE_1###
    
     20 = TEXT
     20.text = ###FILE_1_NAME###
     20.offset = 3,21
     20.fontSize= 12
     20.fontColor = black
   
     25 < .20
     25.offset = 2,20
     25.fontColor = yellow
   }

The output will look like this:

|img-6| As you see the surrounding plugin.tx\_ccrandomimage\_pi2 {}was
not used here. If you want to try this setup with the pi1 plugin put
plugin.tx\_ccrandomimage\_pi2 {}around it.


.. _Example-2:

Example 2
^^^^^^^^^

This example shows how to use RandomImage inside of a template. That's
what this extension is designed for.

We assume you have following simple TS setup:

::

   # Default PAGE object:
   page = PAGE
   page.typeNum = 0
   page.10 = TEXT
   page.10.value = HELLO WORLD!

1. Add the pi1 static template to your TS template.

2. Set the path to your image collection with the Template Constant
Editor or insert a line in your the constants field of your template
by hand.

Example:

plugin.tx\_ccrandomimage\_pi1.path **=** fileadmin/cc\_random\_image/

3. Add following lines to your template:

::

     // insert a random image setup into the current page rendering
   page.20 < plugin.tx_ccrandomimage_pi1
   page.20.renderObj.wrap = <div style="margin: 5px; border: red 2px solid"> | </div>

The output will look like this:

|img-7| If you want the output of the plugin to be cached with the
cached page content you can change the plugin from USER\_INT to USER:

::

   page.20 < plugin.tx_ccrandomimage_pi1
   page.20 = USER

Images will change than on new page rendering only .


.. _Example-3:

Example 3
^^^^^^^^^

*Note: you should have knowledge about using html templates before
reading this.*

Here's a real life example of how to use RandomImage. The image below
shows the head of a web page. It's part of the standard template of
that website.

|img-8|

Above the navigation bar you see five images. These images change
randomly with every page load.

The head consists of “image parts” glued together within an html
table. The random images should appear in one of the table cells (red
square below).

|img-9|

The html template has the marker ###RNDIMG### inside the table cell:

::

     ...<img src="fileadmin/layout/bilder/head_09.jpg" width="74" height="18" alt="" /></td>
     <td rowspan="2" valign="top" height="1" nowrap>###RNDIMG###</td>
   </tr>

Because the table cell (red square) has should have fixed dimensions
of 375 x 50 pixels, and five images should be shown in a row, every
image must be 75 x 50 pixels in size. If one image is higher than 75
pixels the surrounded html table will be stretched, and that will
destroy the nice header layout.

TYPO3 can resize images to fit into maximum dimensions (using the
IMAGE object), but you can resize the images to exactly 75 x 50 pixels
with ImageMagick.

Resize a bunch of images with the shell command  *mogrify*
(ImageMagick):

::

   mogrify -format jpg -size 75x50 -resize 75x50! +profile "*" *

Here's the TypoScript setup...

First, create a USER\_INT object: this tells TYPO3 not to cache the
output, which will result in different images displaying on every page
load. The option is to use an INT object which will show changed
images only if the whole page is re-rendered...

::

   includeLibs.tx_ccrandomimage = EXT:cc_random_image/pi1/class.tx_ccrandomimage_pi1.php
   
     // USER_INT means 'no caching'
   temp.rndImageTop = USER_INT
   temp.rndImageTop {
     userFunc = tx_ccrandomimage_pi1->main
   

Then, define the path where the images reside...

::

     path = fileadmin/randomImage-75x50/
     fileExt = jpg,jpeg,gif,png
   

The rendering object is really simple. It's a content object array
(COA) with five IMAGE objects in it. Before rendering, the
###FILE\_x### marker's will be substituted by RandomImage, with image
files selected from the folder defined above...

::

     renderObj = COA
     renderObj {
       10 = IMAGE
       10.file = ###FILE_1###
       20 = IMAGE
       20.file = ###FILE_2###
       30 = IMAGE
       30.file = ###FILE_3###
       40 = IMAGE
       40.file = ###FILE_4###
       50 = IMAGE
       50.file = ###FILE_5###
     }
   }
   
   

Here's the normal html template processing with TEMPLATE (look in the
Golive Tutorial for description)...

::

   page.20 = TEMPLATE
   page.20.template = FILE
   page.20.template.file = fileadmin/layout/template.html
   page.20.workOnSubpart = DOCUMENT_BODY
   page.20.marks {
     MAINNAV < temp.tl_menu
   
   

The above defined object is applied to the marker RNDIMG used in the
HTML template...

::

     RNDIMG < temp.rndImageTop
     HEADER < lib.header.gfx1
     LEFTCOL < styles.content.getLeft
     CONTENT  = COA
     CONTENT {
       30 < styles.content.get
       60  < styles.content.lastUpdate
     }
     RIGHTCOL < styles.content.getRight
   }
   
   

Finished.


.. _Example-4:

Example 4
^^^^^^^^^

What do you think will it do?

::

   temp.rndImageSized = USER_INT
   temp.rndImageSized {
     userFunc = tx_ccrandomimage_pi1->main
   
     path = fileadmin/myimages/
     fileExt = jpg,jpeg,gif,png
   
     renderObj = COA
     renderObj {
       10 = IMAGE
       10.file = ###FILE_1###
       10.file.width = 30
       10.wrap = |<br>
   
       20 = IMAGE
       20.file = ###FILE_2###
       20.file.height = 30
       20.wrap = |<br>
   
       30 = IMAGE
       30.file = ###FILE_3###
       30.file.height = 30
       30.file.width = 30
       30.wrap = |<br>
     }
   }
   
   page.100 < temp.rndImageSized


.. _Known-problems:

Known problems
--------------

In TYPO3 version prior 3.6 the TypoScript object IMAGE can't handle
filenames properly that are not URL compliant.


.. _Changelog:

Changelog
---------

V 2

Default TS setup is now in plugin.tx\_ccrandomimage\_pi1.

Removed excludePath property. You can use ###FILE\_x\_NAME### marker
instead.

Removed overrideParms. Use overrideSetup instead.

V. 1.1.0

Bugfix: the script stayed in an endless loop with only one image file.

Added excludePath property.

|img-10| RandomImage -  **9**


.. ######CUTTER_MARK_IMAGES######

.. |img-1| image:: img-1.png
.. :align: left
.. :border: 0
.. :height: 209
.. :id: Grafik3
.. :name: Grafik3
.. :vspace: 15
.. :width: 460

.. |img-2| image:: img-2.png
.. :align: left
.. :border: 0
.. :height: 207
.. :id: Grafik5
.. :name: Grafik5
.. :vspace: 15
.. :width: 483

.. |img-3| image:: img-3.png
.. :align: left
.. :border: 0
.. :height: 183
.. :id: Grafik6
.. :name: Grafik6
.. :vspace: 15
.. :width: 351

.. |img-4| image:: img-4.png
.. :align: left
.. :border: 0
.. :height: 123
.. :id: Grafik8
.. :name: Grafik8
.. :vspace: 15
.. :width: 516

.. |img-5| image:: img-5.png
.. :align: left
.. :border: 0
.. :height: 282
.. :id: Grafik7
.. :name: Grafik7
.. :vspace: 15
.. :width: 418

.. |img-6| image:: img-6.png
.. :align: left
.. :border: 0
.. :height: 144
.. :id: Grafik4
.. :name: Grafik4
.. :vspace: 15
.. :width: 395

.. |img-7| image:: img-7.png
.. :align: left
.. :border: 0
.. :height: 192
.. :id: Grafik9
.. :name: Grafik9
.. :vspace: 15
.. :width: 347

.. |img-8| image:: img-8.jpeg
.. :align: left
.. :border: 0
.. :height: 98
.. :id: Grafik1
.. :name: Grafik1
.. :vspace: 15
.. :width: 570

.. |img-9| image:: img-9.jpeg
.. :align: left
.. :border: 0
.. :height: 78
.. :id: Grafik2
.. :name: Grafik2
.. :vspace: 15
.. :width: 499

.. |img-10| image:: img-10.png
.. :align: left
.. :border: 0
.. :height: 32
.. :id: Graphic1
.. :name: Graphic1
.. :vspace: 15
.. :width: 102