library/cropper/cropper.html

   1    1.
   2       <script type="text/javascript" src="scripts/cropper/lib/prototype.js" language="javascript"></script>
   3    2.
   4       <script type="text/javascript" src="scripts/cropper/lib/scriptaculous.js?load=builder,dragdrop" language="javascript"></script>
   5    3.
   6       <script type="text/javascript" src="scripts/cropper/cropper.js" language="javascript"></script>
   7
   8 Options
   9
  10 ratioDim obj
  11     The pixel dimensions to apply as a restrictive ratio, with properties x & y.
  12 minWidth int
  13     The minimum width for the select area in pixels.
  14 minHeight int
  15     The mimimum height for the select area in pixels.
  16 maxWidth int
  17     The maximum width for the select areas in pixels (if both minWidth & maxWidth set to same the width of the cropper will be fixed)
  18 maxHeight int
  19     The maximum height for the select areas in pixels (if both minHeight & maxHeight set to same the height of the cropper will be fixed)
  20 displayOnInit int
  21     Whether to display the select area on initialisation, only used when providing minimum width & height or ratio.
  22 onEndCrop func
  23     The callback function to provide the crop details to on end of a crop.
  24 captureKeys boolean
  25     Whether to capture the keys for moving the select area, as these can cause some problems at the moment.
  26 onloadCoords obj
  27     A coordinates object with properties x1, y1, x2 & y2; for the coordinates of the select area to display onload
  28
  29 The callback function
  30
  31 The callback function is a function that allows you to capture the crop co-ordinates when the user finished a crop movement, it is passed two arguments:
  32
  33     * coords, obj, coordinates object with properties x1, y1, x2 & y2; for the coordinates of the select area.
  34     * dimensions, obj, dimensions object with properities width & height; for the dimensions of the select area.
  35
  36 An example function which outputs the crop values to form fields:
  37 Display code as plain text
  38 JavaScript:
  39
  40    1.
  41       function onEndCrop( coords, dimensions ) {
  42    2.
  43           $( 'x1' ).value = coords.x1;
  44    3.
  45           $( 'y1' ).value = coords.y1;
  46    4.
  47           $( 'x2' ).value = coords.x2;
  48    5.
  49           $( 'y2' ).value = coords.y2;
  50    6.
  51           $( 'width' ).value = dimensions.width;
  52    7.
  53           $( 'height' ).value = dimensions.height;
  54    8.
  55       }
  56
  57 Basic interface
  58
  59 This basic example will attach the cropper UI to the test image and return crop results to the provided callback function.
  60 Display code as plain text
  61 HTML:
  62
  63    1.
  64       <img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
  65    2.
  66
  67    3.
  68           <script type="text/javascript" language="javascript">
  69    4.
  70           Event.observe( window, 'load', function() {
  71    5.
  72               new Cropper.Img(
  73    6.
  74                   'testImage',
  75    7.
  76                   { onEndCrop: onEndCrop }
  77    8.
  78               );
  79    9.
  80           } );
  81   10.
  82       </script>
  83
  84 Minimum dimensions
  85
  86 You can apply minimum dimensions to a single axis or both, this example applies minimum dimensions to both axis.
  87 Display code as plain text
  88 HTML:
  89
  90    1.
  91       <img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
  92    2.
  93
  94    3.
  95       <script type="text/javascript" language="javascript">
  96    4.
  97           Event.observe( window, 'load', function() {
  98    5.
  99               new Cropper.Img(
 100    6.
 101                   'testImage',
 102    7.
 103                   {
 104    8.
 105                       minWidth: 220,
 106    9.
 107                       minHeight: 120,
 108   10.
 109                       onEndCrop: onEndCrop
 110   11.
 111                   }
 112   12.
 113               );
 114   13.
 115           } );
 116   14.
 117       </script>
 118
 119 Select area ratio
 120
 121 You can apply a ratio to the selection area, this example applies a 4:3 ratio to the select area.
 122 Display code as plain text
 123 HTML:
 124
 125    1.
 126       <img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
 127    2.
 128
 129    3.
 130       <script type="text/javascript" language="javascript">
 131    4.
 132           Event.observe( window, 'load', function() {
 133    5.
 134               new Cropper.Img(
 135    6.
 136                   'testImage',
 137    7.
 138                   {
 139    8.
 140                       ratioDim: {
 141    9.
 142                           x: 220,
 143   10.
 144                           y: 165
 145   11.
 146                       },
 147   12.
 148                       displayOnInit: true,
 149   13.
 150                       onEndCrop: onEndCrop
 151   14.
 152                   }
 153   15.
 154               );
 155   16.
 156           } );
 157   17.
 158       </script>
 159
 160 With crop preview
 161
 162 You can display a dynamically prouced preview of the resulting crop by using the ImgWithPreview subclass, a preview can only be displayed when we have a fixed size (set via minWidth & minHeight options). Note that the displayOnInit option is not required as this is the default behaviour when displaying a crop preview.
 163 Display code as plain text
 164 HTML:
 165
 166    1.
 167       <img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
 168    2.
 169       <div id="previewWrap"></div>
 170    3.
 171
 172    4.
 173       <script type="text/javascript" language="javascript">
 174    5.
 175           Event.observe( window, 'load', function() {
 176    6.
 177               new Cropper.ImgWithPreview(
 178    7.
 179                   'testImage',
 180    8.
 181                   {
 182    9.
 183                       previewWrap: 'previewWrap',
 184   10.
 185                       minWidth: 120,
 186   11.
 187                       minHeight: 120,
 188   12.
 189                       ratioDim: { x: 200, y: 120 },
 190   13.
 191                       onEndCrop: onEndCrop
 192   14.
 193                   }
 194   15.
 195               );
 196   16.
 197           } );
 198   17.
 199       </script>
 200
 201 Known Issues
 202
 203     * Safari animated gifs, only one of each will animate, this seems to be a known Safari issue.
 204     * After drawing an area and then clicking to start a new drag in IE 5.5 the rendered height appears as the last height until the user drags, this appears to be the related to another IE error (which has been fixed) where IE does not always redraw the select area properly.
 205     * Lack of CSS opacity support in Opera before version 9 mean we disable those style rules, if Opera 8 support is important you & you want the overlay to work then you can use the Opera rules in the CSS to apply a black PNG with 50% alpha transparency to replicate the effect.
 206     * Styling & borders on image, any CSS styling applied directly to the image itself (floats, borders, padding, margin, etc.) will cause problems with the cropper. The use of a wrapper element to apply these styles to is recommended.
 207     * overflow: auto or overflow: scroll on parent will cause cropper to burst out of parent in IE and Opera when applied (maybe Mac browsers too) I'm not sure why yet.
 208
 209 If you use CakePHP you will notice that including this in your script will break the CSS layout. This is due to the CSS rule
 210
 211 form div{
 212 vertical-align: text-top;
 213 margin-left: 1em;
 214 margin-bottom:2em;
 215 overflow: auto;
 216 }
 217
 218 A simple workaround is to add another rule directly after this like so:
 219
 220 form div.no_cake, form div.no_cake div {
 221 margin:0;
 222 overflow:hidden;
 223 }
 224
 225 and then in your code surround the img tag with a div with the class name of no_cake.
 226
 227 Cheers
 228