[!!!][FEATURE] Streamline Fluid Styled Content and CSS Styled Content
[Packages/TYPO3.CMS.git] / typo3 / sysext / css_styled_content / Documentation / Configuration / Objects / Image / Index.rst
1 .. ==================================================
2 .. FOR YOUR INFORMATION
3 .. --------------------------------------------------
4 .. -*- coding: utf-8 -*- with BOM.
5
6 .. include:: ../../../Includes.txt
7
8
9 .. _objects-image:
10
11 Image
12 """""
13
14 Image-type content elements are not rendered using a standard TypoScript
15 content object but instead rely on a :ref:`USER <t3tsref:cobj-user>` object provided by
16 CSS Styled Content, as can be seen in the TypoScript setup::
17
18         tt_content.image = COA
19         tt_content.image.10 = < lib.stdheader
20         tt_content.image.20 = USER
21         tt_content.image.20 {
22                 userFunc = \TYPO3\CMS\CssStyledContent\Controller\CssStyledContentController->render_textpic
23                 ...
24         }
25
26
27 .. figure:: ../../../Images/ImageContentElement.png
28    :alt: Image content element
29
30    Defining the appearance of an image content element in the TYPO3 backend
31
32
33 The :code:`render_textpic` function supports a whole variety of specific
34 properties, which are detailed below.
35
36 .. note::
37
38    All properties of USER objects also apply, in particular :ref:`stdWrap <t3tsref:stdwrap>`.
39
40
41 .. _objects-image-reference:
42
43 Reference
44 ~~~~~~~~~
45
46
47 .. _objects-image-reference-text:
48
49 text
50 ''''
51
52 .. container:: table-row
53
54    Property
55          text
56
57    Data type
58          :ref:`CARRAY <t3tsref:carray>` / :ref:`stdWrap <t3tsref:stdwrap>`
59
60    Description
61          Use this to import / generate the content, that should flow around the
62          imageblock.
63
64
65
66 .. _objects-image-reference-textpos:
67
68 textPos
69 '''''''
70
71 .. container:: table-row
72
73    Property
74          textPos
75
76    Data type
77          int / :ref:`stdWrap <t3tsref:stdwrap>`
78
79    Description
80          Textposition:
81
82          bit[0-2]: 000 = centre, 001 = right, 010 = left
83
84          bit[3-5]: 000 = over, 001 = under, 010 text
85
86          0 - Above: Centre
87
88          1 - Above: Right
89
90          2 - Above: Left
91
92          8 - Below: Centre
93
94          9 - Below: Right
95
96          10 - Below: Left
97
98          17 - In Text: Right
99
100          18 - In Text: Left
101
102          25 - In Text: Right (no wrap)
103
104          26 - In Text: Left (no wrap)
105
106
107
108 .. _objects-image-reference-imglist:
109
110 imgList
111 '''''''
112
113 .. container:: table-row
114
115    Property
116          imgList
117
118    Data type
119          list of imagefiles / :ref:`stdWrap <t3tsref:stdwrap>`
120
121    Description
122          list of images from ".imgPath"
123
124          **Example:**
125
126          This imports the list of images from tt\_content's image-field
127
128          "imgList.field = image"
129
130    Default
131          field = image
132
133
134
135 .. _objects-image-reference-imgpath:
136
137 imgPath
138 '''''''
139
140 .. container:: table-row
141
142    Property
143          imgPath
144
145    Data type
146          path / :ref:`stdWrap <t3tsref:stdwrap>`
147
148    Description
149          Path to the images
150
151          **Example:**
152
153          "uploads/pics/"
154
155    Default
156          uploads/pics/
157
158
159
160 .. _objects-image-reference-imgmax:
161
162 imgMax
163 ''''''
164
165 .. container:: table-row
166
167    Property
168          imgMax
169
170    Data type
171          int / :ref:`stdWrap <t3tsref:stdwrap>`
172
173    Description
174          max number of images
175
176    Default
177          0 [all]
178
179
180
181 .. _objects-image-reference-imgstart:
182
183 imgStart
184 ''''''''
185
186 .. container:: table-row
187
188    Property
189          imgStart
190
191    Data type
192          int / :ref:`stdWrap <t3tsref:stdwrap>`
193
194    Description
195          start with image-number ".imgStart"
196
197    Default
198          0
199
200
201
202 .. _objects-image-reference-imgobjnum:
203
204 imgObjNum
205 '''''''''
206
207 .. container:: table-row
208
209    Property
210          imgObjNum
211
212    Data type
213          *imgObjNum* + :ref:`optionSplit <t3tsref:objects-optionsplit>`
214
215    Description
216          Here you define which :ref:`IMAGE <t3tsref:cobj-image>`-cObjects from the array "1,2,3,4..."
217          should render which image.
218
219          "current" is set to the image-filename.
220
221          **Example:**
222
223          "imgObjNum = 1 \|\*\|\|\*\| 2":
224
225          If your ".imgList" contains 3 images, this would render the first two
226          images with "1. ..." and the last image with "2. ...".
227
228    Default
229          1
230
231
232
233 .. _objects-image-reference-1-2-3-4:
234
235 1,2,3,4,...
236 '''''''''''
237
238 .. container:: table-row
239
240    Property
241          1,2,3,4,...
242
243    Data type
244          :ref:`IMAGE <t3tsref:cobj-image>`
245
246    Description
247          Rendering of the individual images
248
249          The register "IMAGE\_NUM" is set with the number of image being
250          rendered for each rendering of an image-object. Starting with zero.
251
252          The image-object should not be of type GIFBUILDER!
253
254          **Important:**
255
256          "file.import.current = 1" fetches the name of the images!
257
258
259
260 .. _objects-image-reference-caption:
261
262 caption
263 '''''''
264
265 .. container:: table-row
266
267    Property
268          caption
269
270    Data type
271          :ref:`CARRAY <t3tsref:carray>` / :ref:`stdWrap <t3tsref:stdwrap>`
272
273    Description
274          Caption
275
276
277
278 .. _objects-image-reference-imagetextsplit:
279
280 imageTextSplit
281 ''''''''''''''
282
283 .. container:: table-row
284
285    Property
286          imageTextSplit
287
288    Data type
289          boolean
290
291    Description
292          If this is set, the caption/alttext/title/longdescURL text is split by
293          the character (or string) from ".token" , and every item is rendered
294          to the accordant image in the image block.
295
296
297
298 .. _objects-image-reference-border:
299
300 border
301 ''''''
302
303 .. container:: table-row
304
305    Property
306          border
307
308    Data type
309          boolean / :ref:`stdWrap <t3tsref:stdwrap>`
310
311    Description
312          If true, a border is generated around the images.
313
314    Default
315          field = imageborder
316
317
318
319 .. _objects-image-reference-bordercol:
320
321 borderCol
322 '''''''''
323
324 .. container:: table-row
325
326    Property
327          borderCol
328
329    Data type
330          HTML-color / :ref:`stdWrap <t3tsref:stdwrap>`
331
332    Description
333          Color of the border, if ".border" is set.
334
335          This is used just to create the CSS class that will be added to an
336          image block that needs a border. The border itself will have to be
337          specified in CSS. See CSS section later.
338
339    Default
340          black
341
342
343
344 .. _objects-image-reference-borderthick:
345
346 borderThick
347 '''''''''''
348
349 .. container:: table-row
350
351    Property
352          borderThick
353
354    Data type
355          pixels / :ref:`stdWrap <t3tsref:stdwrap>`
356
357    Description
358          Width of the border around the pictures
359
360          This is used just to create the CSS class that will be added to an
361          image block that needs a border. The border itself will have to be
362          specified in CSS. See CSS section later.
363
364    Default
365          2
366
367
368
369 .. _objects-image-reference-cols:
370
371 cols
372 ''''
373
374 .. container:: table-row
375
376    Property
377          cols
378
379    Data type
380          int / :ref:`stdWrap <t3tsref:stdwrap>`
381
382    Description
383          Columns
384
385    Default
386          field = imagecols
387
388
389
390 .. _objects-image-reference-rows:
391
392 rows
393 ''''
394
395 .. container:: table-row
396
397    Property
398          rows
399
400    Data type
401          int / :ref:`stdWrap <t3tsref:stdwrap>`
402
403    Description
404          Rows (higher priority than "cols")
405
406
407
408 .. _objects-image-reference-colspace:
409
410 colSpace
411 ''''''''
412
413 .. container:: table-row
414
415    Property
416          colSpace
417
418    Data type
419          int / :ref:`stdWrap <t3tsref:stdwrap>`
420
421    Description
422          Space between columns. If you use the default CSS this will be added
423          automatically as margin-right to the images.
424
425
426
427 .. _objects-image-reference-maxw:
428
429 maxW
430 ''''
431
432 .. container:: table-row
433
434    Property
435          maxW
436
437    Data type
438          int / :ref:`stdWrap <t3tsref:stdwrap>`
439
440    Description
441          Max width of the image-table.
442
443          This will scale images not in the right size! Takes the number of
444          columns into account!
445
446
447
448 .. _objects-image-reference-maxwintext:
449
450 maxWInText
451 ''''''''''
452
453 .. container:: table-row
454
455    Property
456          maxWInText
457
458    Data type
459          int / :ref:`stdWrap <t3tsref:stdwrap>`
460
461    Description
462          Max width of the image-table, if the text is wrapped around the image-
463          table (on the left or right side).
464
465          This will scale images not in the right size! Takes the number of
466          columns into account!
467
468    Default
469          50% of maxW
470
471
472
473 .. _objects-image-reference-equalh:
474
475 equalH
476 ''''''
477
478 .. container:: table-row
479
480    Property
481          equalH
482
483    Data type
484          int / :ref:`stdWrap <t3tsref:stdwrap>`
485
486    Description
487          If this value is greater than zero, it will secure that images in a
488          row have the same height. The width will be calculated.
489
490          If the total width of the images raises above the "maxW"-value of the
491          table the height for each image will be scaled down equally so that
492          the images still have the same height but are within the limits of the
493          totalWidth.
494
495          Please note that this value will override the properties "width",
496          "maxH", "maxW", "minW", "minH" of the IMAGE-objects generating the
497          images. It will generate a table with no columns.
498
499
500
501 .. _objects-image-reference-colrelations:
502
503 colRelations
504 ''''''''''''
505
506 .. container:: table-row
507
508    Property
509          colRelations
510
511    Data type
512          string / :ref:`stdWrap <t3tsref:stdwrap>`
513
514    Description
515          This value defines the width-relations of the images in the columns of
516          IMGTEXT. The syntax is "[int] : [int] : [int] : ..." for each column.
517          If there are more image columns than figures in this value, it's
518          ignored. If the relation between two of these figures exceeds 10, this
519          function is ignored.
520
521          It works only fully if all images are downscaled by their maxW-
522          definition.
523
524          **Example:**
525
526          If 6 images are placed in three columns and their width's are high
527          enough to be forcibly scaled, this value will scale the images in the
528          to be e.g. 100, 200 and 300 pixels from left to right
529
530          1 : 2 : 3
531
532
533
534 .. _objects-image-reference-image-compression:
535
536 image\_compression
537 ''''''''''''''''''
538
539 .. container:: table-row
540
541    Property
542          image\_compression
543
544    Data type
545          int / :ref:`stdWrap <t3tsref:stdwrap>`
546
547    Description
548          Image Compression:
549
550          0= Default
551
552          1= Don't change! (removes all parameters for the image\_object!!)
553
554          (adds gif-extension and color-reduction command)
555
556          10= GIF/256
557
558          11= GIF/128
559
560          12= GIF/64
561
562          13= GIF/32
563
564          14= GIF/16
565
566          15= GIF/8
567
568          (adds jpg-extension and quality command)
569
570          20= IM: -quality 100
571
572          21= IM: -quality 90 <=> Photoshop 60 (JPG/Very High)
573
574          22= IM: -quality 80 (JPG/High)
575
576          23= IM: -quality 70
577
578          24= IM: -quality 60 <=> Photoshop 30 (JPG/Medium)
579
580          25= IM: -quality 50
581
582          26= IM: -quality 40 (JPG/Low)
583
584          27= IM: -quality 30 <=> Photoshop 10
585
586          28= IM: -quality 20 (JPG/Very Low)
587
588          The default ImageMagick quality seems to be 75. This equals Photoshop
589          quality 45. Images compressed with ImageMagick with the same visual
590          quality as a Photoshop-compressed image seems to be 50% bigger in file
591          size!!
592
593          .. note::
594
595             Works ONLY if IMAGE-obj is NOT GIFBUILDER
596
597
598
599 .. _objects-image-reference-image-effects:
600
601 image\_effects
602 ''''''''''''''
603
604 .. container:: table-row
605
606    Property
607          image\_effects
608
609    Data type
610          int / :ref:`stdWrap <t3tsref:stdwrap>`
611
612    Description
613          Adds these IM/GM commands to the parameters for scaling. This function
614          has no effect if "image\_compression" above is set to 1!!
615
616          1 => "-rotate 90",
617
618          2 => "-rotate 270",
619
620          3 => "-rotate 180",
621
622          10 => "-colorspace GRAY",
623
624          11 => "-sharpen 70",
625
626          20 => "-normalize",
627
628          23 => "-contrast",
629
630          25 => "-gamma 1.3",
631
632          26 => "-gamma 0.8"
633
634          .. note::
635
636             Works ONLY if IMAGE-obj is NOT GIFBUILDER
637
638
639
640 .. _objects-image-reference-image-frames:
641
642 image\_frames
643 '''''''''''''
644
645 .. container:: table-row
646
647    Property
648          image\_frames
649
650    Data type
651          Array
652
653          \+ .key / :ref:`stdWrap <t3tsref:stdwrap>`
654
655    Description
656          **Frames:**
657
658          .key points to the frame used.
659
660          ".image\_frames.x" is imgResource-mask (".m")properties which will
661          override to the [imgResource].m properties of the imageObjects. This
662          is used to mask the images into a frame. See how it's done in the
663          default configuration and IMGTEXT in the static\_template-table.
664
665          **Example:**
666
667          ::
668
669             1 {
670               mask = media/uploads/darkroom1_mask.jpg
671               bgImg = GIFBUILDER
672               bgImg {
673                 XY = 100,100
674                 backColor = {$bgCol}
675               }
676               bottomImg = GIFBUILDER
677               bottomImg {
678                 XY = 100,100
679                 backColor = black
680               }
681               bottomImg_mask = media/uploads/darkroom1_bottom.jpg
682             }
683
684                  .. note::
685
686             This cancels the jpg-quality settings sent as ordinary
687             ".params" to the imgResource. In addition the output of this operation
688             will always be jpg or gif!
689
690          .. note::
691
692             Works ONLY if IMAGE-obj is NOT GIFBUILDER
693
694
695
696 .. _objects-image-reference-editicons:
697
698 editIcons
699 '''''''''
700
701 .. container:: table-row
702
703    Property
704          editIcons
705
706    Data type
707          string
708
709    Description
710          See :ref:`stdWrap.editIcons <t3tsref:stdwrap-editicons>`.
711
712
713
714 .. _objects-image-reference-rendermethod:
715
716 renderMethod
717 ''''''''''''
718
719 .. container:: table-row
720
721    Property
722          renderMethod
723
724    Data type
725          string / :ref:`stdWrap <t3tsref:stdwrap>`
726
727    Description
728          The rendering method to use for this content object. The name of the
729          method must be one of the entries in the  **rendering** setting.
730
731    Default
732          singleNoCaption
733
734
735
736 .. _objects-image-reference-fallbackrendering:
737
738 fallbackRendering
739 '''''''''''''''''
740
741 .. container:: table-row
742
743    Property
744          fallbackRendering
745
746    Data type
747          cObj
748
749    Description
750          If no rendering is specified, this is the fallback that will be used.
751          Can be used to overwrite the rendering method in specific "edge"
752          situations (e.g. when rendering only one image, or when rendering a
753          list of files without captions). This cObject will be called once the
754          major "rendering" type is defined (dl, ul, div) and when the pre-
755          processor already has gathered some information about how many images
756          to render (register:imageCount) and if the current rendering will
757          output a global caption for the whole image block or split captions
758          are needed (register:renderGlobalCaption). Using this information the
759          fallbackRendering can output some string, which will overwrite the
760          default rendering method (e.g. dl, ul, div and newly introduced
761          "simple", which renders least structure, intended for one image only).
762
763          The default css\_styled\_content setup in TYPO3 v4.3 provides these
764          fallbacks:
765
766          - with rendering=dl,ul,div, a single image fallbacks to rendering=simple
767
768          - with rendering=dl, a list of images with no caption fallbacks to
769            rendering=ul
770
771          - with rendering=dl, a list of images with one "global" caption (no
772            splitCaption configured) fallbacks to rendering=ul
773
774    Default
775          dl
776
777
778
779 .. _objects-image-reference-rendering:
780
781 rendering
782 '''''''''
783
784 .. container:: table-row
785
786    Property
787          rendering
788
789    Data type
790          Array of
791
792          :ref:`IMGTEXT <t3tsref:cobj-imgtext>` properties
793
794    Description
795          In this array, a list of renderers can be created from which the user
796          chooses which one will render each "Text with image" content object.
797          The settings in each entry can override settings from this table, and
798          there is also a set of :ref:`stdWrap <t3tsref:stdwrap>`'s that allows you to create the XHTML
799          structure of your choosing for rendering the imageblock.
800
801          In the standard installation the rendering will be loaded from the
802          lib.imgtextrendering TypoScript object, so you might want to
803          change/add stuff here.
804
805          **Example:**
806
807          ::
808
809             tt_content.textpic.20.rendering {
810               dl {
811                   imageRowStdWrap.wrap = <div class="csi-imagerow" style="width:{register:rowwidth}px;"> | </div>
812                   imageRowStdWrap.insertData = 1
813                   oneImageStdWrap.wrap = <dl class="csi-image" style="width:{register:imagewidth}px;"> | </dl>
814                   oneImageStdWrap.insertData = 1
815                   imgTagStdWrap.wrap = <dt> | </dt>
816                   editIconsStdWrap.wrap = <dd> | </dd>
817                   captionStdWrap.wrap = <dd class="csi-caption"> | </dd>
818               }
819               # Now we add another rendering method:
820               dl-nospace < .dl
821               dl-nospace.addClasses = csi-textpic-dl-nospace
822             }
823
824
825
826 .. _objects-image-reference-addclasses:
827
828 addClasses
829 ''''''''''
830
831 .. container:: table-row
832
833    Property
834          addClasses
835
836    Data type
837          string / :ref:`stdWrap <t3tsref:stdwrap>`
838
839    Description
840          Add the specified classes to the csc-textpic <div> (the outer
841          surrounding block). This is useful to override in a specific
842          "rendering" engine, allowing you for example to have different margin
843          styles (one with margin around images, the other without).
844
845
846
847 .. _objects-image-reference-addclassesimage:
848
849 addClassesImage
850 '''''''''''''''
851
852 .. container:: table-row
853
854    Property
855          addClassesImage
856
857    Data type
858          String / :ref:`stdWrap <t3tsref:stdwrap>`
859
860    Description
861          Add the specified classes to the image element
862
863
864
865 .. _objects-image-reference-separaterows:
866
867 separateRows
868 ''''''''''''
869
870 .. container:: table-row
871
872    Property
873          separateRows
874
875    Data type
876          boolean / :ref:`stdWrap <t3tsref:stdwrap>`
877
878    Description
879          Separate the rows of images in different :code:`<div>` tags, so that they can be
880          styled in some other way. See CSS-section for more details.
881
882    Default
883          0
884
885
886
887 .. _objects-image-reference-imgtagstdwrap:
888
889 imgTagStdWrap
890 '''''''''''''
891
892 .. container:: table-row
893
894    Property
895          imgTagStdWrap
896
897    Data type
898          string / :ref:`stdWrap <t3tsref:stdwrap>`
899
900    Description
901          Wrapping around the :code:`<img>` tag.
902
903
904
905 .. _objects-image-reference-editiconsstdwrap:
906
907 editIconsStdWrap
908 ''''''''''''''''
909
910 .. container:: table-row
911
912    Property
913          editIconsStdWrap
914
915    Data type
916          string / :ref:`stdWrap <t3tsref:stdwrap>`
917
918    Description
919          Wrapping around the frontend editing icons
920
921
922
923 .. _objects-image-reference-oneimagestdwrap:
924
925 oneImageStdWrap
926 '''''''''''''''
927
928 .. container:: table-row
929
930    Property
931          oneImageStdWrap
932
933    Data type
934          string / :ref:`stdWrap <t3tsref:stdwrap>`
935
936    Description
937          Wrapping around one "image" in the block (with image and caption)
938
939
940
941 .. _objects-image-reference-imagerowstdwrap:
942
943 imageRowStdWrap
944 '''''''''''''''
945
946 .. container:: table-row
947
948    Property
949          imageRowStdWrap
950
951    Data type
952          string / :ref:`stdWrap <t3tsref:stdwrap>`
953
954    Description
955          Wrapping around one row of images
956
957
958
959 .. _objects-image-reference-imagelastrowstdwrap:
960
961 imageLastRowStdWrap
962 '''''''''''''''''''
963
964 .. container:: table-row
965
966    Property
967          imageLastRowStdWrap
968
969    Data type
970          string / :ref:`stdWrap <t3tsref:stdwrap>`
971
972    Description
973          Wrapping around the last row of images
974
975
976
977 .. _objects-image-reference-imagestdwrap:
978
979 imageStdWrap
980 ''''''''''''
981
982 .. container:: table-row
983
984    Property
985          imageStdWrap
986
987    Data type
988          string / :ref:`stdWrap <t3tsref:stdwrap>`
989
990    Description
991          Wrapping around the whole image block if a width is needed. This is
992          the case when
993
994          - position is center
995
996          - there is more than 1 row
997
998          - or we have a global caption
999
1000
1001
1002 .. _objects-image-reference-imagestdwrapnowidth:
1003
1004 imageStdWrapNoWidth
1005 '''''''''''''''''''
1006
1007 .. container:: table-row
1008
1009    Property
1010          imageStdWrapNoWidth
1011
1012    Data type
1013          string / :ref:`stdWrap <t3tsref:stdwrap>`
1014
1015    Description
1016          Wrapping around the whole image block if no width is needed.