Installation


To test the examples is necessary to extract the folder "picture.cut" for a php environment running on a server

Server Requirements

  • PHP 5+
  • GD extension

Client-side Requirements

  • jQuery
  • jQuery UI
    • UI Core
    • Interactions (Draggable, Resizable)
    • Widgets (Dialog, Button)
  • BootStrap (for bootstrap theme)

How to use it


include files and dependencies in this order.

        
              <link rel="stylesheet" href="dependencies/bootstrap-3.2.0/css/bootstrap.min.css"> <!--for bootstrap theme-->    

              <script src="dependencies/jquery/jquery-1.11.1.min.js"></script>        
              <script src="dependencies/bootstrap-3.2.0/js/bootstrap.min.js"></script><!--for bootstrap theme-->    
              <script src="dependencies/jquery-ui-1.11.1.custom/jquery-ui.min.js"></script>
              
              <script src="jquery.picture.cut/src/jquery.picture.cut.js"></script>    
                  

The plugin must be instantiated in a div, it will work as a container


              <div id="container_image"></div>        
                   

Instantiating the plugin, basic mode


              $("#container_image").PictureCut({
                  InputOfImageDirectory       : "image",
                  PluginFolderOnServer        : "/jquery.picture.cut/",
                  FolderOnServer              : "/uploads/",
                  EnableCrop                  : true,
                  CropWindowStyle             : "Bootstrap"
              });
                  

The PluginFolderOnServer and FolderOnServer property need to be defined, they will be better detailed in the next topic, it is important to know that the directory defined in FolderOnServer need to be writable 777.

Parameters


Type Array
Description This parameter will receive extensions accepted by the plugin.
Default
["jpg","png","gif"]
Type String
Description The plugin will automatically generate a hidden input type that will receive the full address (url) of the image, this parameter will be the name hidden input.
Default
"image"
Type Object
Description This attribute will receive values to be defined as an attribute for InputOfImageDirectory
Default
{}
Type String
Description This attribute will receive the name to be set to the input file
Default
"file-" + InputOfImageDirectory
Type String
Description this attribute will receive the upload action to be submitted, the route or path to file must be defined as a relative URL based on the document root
Default
PluginFolderOnServer + "src/php/upload.php"
Type String
Description this attribute will receive the crop action to be submitted, the route or path to file must be defined as a relative URL based on the document root
Default
PluginFolderOnServer + "src/php/crop.php"
Type String
Description This parameter will receive the folder that will store the image, it is important to know that the directory defined here need to have write permissions 777, This parameter is required plugin can not be instantiated if it is null, the defined directory must be a relative URL based on the document root example: "/assets/uploads"
Default
null
Type Object
Description This parameter takes an object to be sent to the upload action.
Default
{}
Type String
Description This parameter will receive the url to the default image of image button
Default
PluginFolderOnServer + "src/img/icon_add_image2.png"
Type Boolean
Description Activate clipping, This parameter takes a boolean value.
Default
false
Type Boolean
Description Enable image resizing, it is important to know that the image will be resized only if the size exceed the values ​​defined in MinimumWidthToResize and MinimumHeightToResize.
Default
true
Type Integer
Description Enable image resizing, it is important to know that the image will be resized only if the size exceed the values ​​defined in MinimumWidthToResize and MinimumHeightToResize.
Default
true
Type Integer
Description The minimum width to be resized if it exceeds the value set here.
Default
1024
Type Integer
Description The minimum height to be resized if it exceeds the value set here.
Default
630
Type Integer
Description Maximum size in Kbytes defined file, this attribute is only valid when the EnableMaximumSize option is enabled.
Default
1024 //kbytes
Type Boolean
Description Enable handling of file size, the maximum file size is set to MaximumSize, this feature is only valid for jpg, If this option is enabled with the function resize (EnableResize), first the file size will be manipulated and then the width and height of the image. algorithm that treats the file size can modify the width and height of the image for the maximum size defined.
Default
false
Type String
Description This parameter receives the directory that the plugin is stored, the plugin can not be instantiated without this setting, the path needs to be defined as a relative url based on the document root, example: "/assets/jquery.picture.cut/"
Default
null
Type String
Description This parameter receives the style of the trimming frame. currently have three styles available "Bootstrap", "jQueryUI", "PopStyle" the next version of the plugin we will provide a manual to develop your own theme.
Default
"Bootstrap"
Type Boolean
Description Activate random file name, if this attribute is false the image remained with the original name.
Default
true
Type Boolean
Description This parameter enables a button to add or remove beneath the image button
Default
true
Type Object
Description This parameter receives css attributes to be defined for the image button.
Default

            {
              border:"1px #CCC solid",
              width :170,
              height:150
            }
                                        
Type Object
Description

this parameter will receive the clipping options available for the User

widescreen: enables the cutout in 16/9 aspect ratio

letterbox : enables the cutout in 4/3 aspect ratio

free : enables the free cutout

Default
                                          
            {
              widescreen: true,
              letterbox: true,
              free   : true
            }
                                        
Type Boolean
Description Enables the change of orientation of the clipping
Default
true
Type Event function
Description this parameter will receive a function to run after upload if clipping is enabled, the function will be executed as soon as the image loads in the image button.

the event will receive a parameter with the image data.

            {
                status          : [Boolean],
                currentFileName : [String],
                currentWidth    : [Integer],
                currentHeight   : [Integer],
                currentFileSize : [Integer],
                request         : [String],
                options         : {
                    FolderOnServer  : [Integer]
                }
            }                                   
                                           
Default
function(data){}

How works the server side


these implementations are done, all files are included with the plugin.


upload
crop

Upload

Server Side implementation upload

src/php/upload.php

    

          require_once('core/PictureCut.php');

          try {
            
            
            $pictureCut = PictureCut::createSingleton(); //creating an singleton instance of the class PictureCut
            
            
            if($pictureCut->upload()){ //calling the method that will upload    
              print $pictureCut->toJson(); //print the data to the plugin (client side).
            } else {    
              print $pictureCut->exceptionsToJson(); //print exceptions if the upload fails
            }

          } catch (Exception $e) {  
            print $e->getMessage(); //print exceptions instance.
          }
              
            
              

Object submitted to upload.php

          { 
            inputOfFile           : [Files],
            request               : [String],
            inputOfFile           : [String],
            enableResize          : [Boolean],
            minimumWidthToResize  : [Integer],
            minimumHeightToResize : [Integer],
            folderOnServer        : [String],
            imageNameRandom       : [Boolean],
            maximumSize           : [Integer],
            enableMaximumSize     : [Boolean]
          }
                
              

Object returned to the plugin from upload.php

          {
              status          : [Boolean],
              currentFileName : [String],
              currentWidth    : [Integer],
              currentHeight   : [Integer],
              currentFileSize : [Integer],
              request         : [String]
          }

          


Crop

Server Side implementation crop

src/php/crop.php

                    
          require_once('core/PictureCut.php');

          try {

            $pictureCut = PictureCut::createSingleton();  //creating an singleton instance of the class PictureCut
            
            if($pictureCut->crop()){  //calling the method that will cut
              print $pictureCut->toJson();  //print the data to the plugin (client side).
            } else {
               print $pictureCut->exceptionsToJson(); //print exceptions if the upload fails
            }

          } catch (Exception $e) {
            print $e->getMessage();  //print exceptions instance.
          }

                

Object submitted to crop.php

          {  
            currentFileName   : [String],
            currentWidth      : [Integer],
            currentHeight     : [Integer],
            currentFileSize   : [Integer],
            request           : [String],
            folderOnServer    : [String],
            inputOfFile       : [String],
            maximumSize       : [Integer],
            enableMaximumSize : [Boolean],
            toCropImgX        : [Integer],
            toCropImgY        : [Integer],
            toCropImgW        : [Integer],
            toCropImgH        : [Integer]
          }
                

Object returned to the plugin from crop.php

          {
              status          : [Boolean],
              currentFileName : [String],
              currentWidth    : [Integer],
              currentHeight   : [Integer],
              currentFileSize : [Integer],
              request         : [String]
          }

          

Credits


This project is only possible because of these libraries