jquery.guillotine
Version:
Allow users to crop images within an area (fully responsive). Supports dragging (touch support), zoom and rotation.
49 lines (48 loc) • 7.66 kB
JSON
{
"name": "jquery.guillotine",
"version": "1.4.3",
"description": "Allow users to crop images within an area (fully responsive). Supports dragging (touch support), zoom and rotation.",
"author": {
"name": "Matías A. Gagliano"
},
"license": "(GPL-3.0 OR MIT)",
"homepage": "http://guillotine.js.org",
"repository": {
"type": "git",
"url": "git+https://github.com/matiasgagliano/guillotine.git"
},
"keywords": [
"guillotine",
"jquery",
"jquery-plugin",
"image",
"crop",
"rotate",
"zoom",
"drag",
"fit",
"center",
"touch",
"responsive",
"fluid"
],
"files": [
"css",
"js",
"README.md"
],
"main": "js/jquery.guillotine.js",
"style": "css/*.css",
"dependencies": {
"jquery": ">= 1.8.0"
},
"readme": "jQuery Guillotine Plugin\n========================\n\n[](https://npmjs.org/package/guillotine)\n\nDemo\n----\n<http://guillotine.js.org>\n\n\nDescription\n-----------\nGuillotine is a jQuery plugin that allows to **drag**, **zoom** or **rotate**\nan image to select a cropping area. Like selecting the display area of a\nprofile picture or avatar.\n\n* **Responsive:** The window (or selection area) is fully responsive (fluid).\n* **Touch support:** Dragging the image also works on touch devices.\n\n*(2.7kb minified and gzipped)*\n\n\nSetup\n-----\n1. Load the required files:\n * *jquery.js*\n * *jquery.guillotine.js*\n * *jquery.guillotine.css*\n\n2. Set the width of the parent element:\n ```html\n <div id=\"theparent\" style=\"width: 80%;\">\n <img id=\"thepicture\" src=\"url/to/image\">\n </div>\n ```\n\n The window (\"the guillotine\") that will wrap around the image when the\n plugin is instantiated is fully responsive (fluid) so it will always take\n all the width left by its parent.\n\n3. Instantiate the plugin:\n ```javascript\n var picture = $('#thepicture'); // Must be already loaded or cached!\n picture.guillotine({width: 400, height: 300});\n ```\n\n Here we set the dimensions we want for the cropped image (400x300), which\n are totally independent of the size in which the \"guillotine\" or \"window\"\n is actually displayed on screen.\n\n Even though it's responsive, the data returned always corresponds to the\n predefined dimensions. In this case, it will always get a cropped image of\n 400 by 300 pixels.\n\n **Notice:** Make sure that the target element is ready before instantiating!\n\n If it's an image, make sure that it is already loaded or cached before\n calling Guillotine, so it can get its dimensions and display it properly.\n You can use the *onload* event, the *complete* property or check that the\n image has a width greater than zero to determine if it's loaded.\n\n\n4. Bind actions:\n ```javascript\n $('#rotate-left-button').click(function(){\n picture.guillotine('rotateLeft');\n });\n\n $('#zoom-in-button').click(function(){\n picture.guillotine('zoomIn');\n });\n\n ...\n ```\n\n5. Handle cropping instructions:\n\n The plugin is not meant to actually crop images but to generate the\n necessary instructions to do so on the server.\n\n * You can get the instructions at any point by calling 'getData':\n ```javascript\n data = picture.guillotine('getData');\n // { scale: 1.4, angle: 270, x: 10, y: 20, w: 400, h: 300 }\n ```\n\n **Important:** You should rotate and scale first, and then apply\n the cropping coordinates to get it right!\n\n * Or you can use a callback or a custom event to listen for changes:\n ```javascript\n var otherPicture = $('#other-picture');\n otherPicture.guillotine({eventOnChange: 'guillotinechange'});\n otherPicture.on('guillotinechange', function(ev, data, action){\n // this = current element\n // ev = event object\n // data = { scale: 1.4, angle: 270, x: 10, y: 20, w: 400, h: 300 }\n // action = drag/rotateLeft/rotateRight/center/fit/zoomIn/zoomOut/setScale/setHeight/setWidth/reset\n // Save data on hidden inputs...\n });\n ```\n\n Set the 'onChange' option instead if you prefer to use a callback:\n ```javascript\n otherPicture.guillotine({\n onChange: function(data, action){\n // Do something...\n }\n });\n ```\n\n6. Enjoy!\n\n\nAPI\n---\nOnce instantiated, you can interact with the plugin by passing instructions as strings.\nHere is the complete **public API**:\n\n```javascript\n// Transformations\n// rotateLeft, rotateRight, center, fit, zoomIn, zoomOut, setScale, setHeight, setWidth, reset\npicture.guillotine('zoomOut');\npicture.guillotine('rotateRight');\n...\n\n// Get current data\n// { scale: 1.4, angle: 270, x: 10, y: 20, w: 400, h: 300 }\nvar data = picture.guillotine('getData');\n\n// Get instance (Guillotine instance)\nvar guillotine = picture.guillotine('instance');\n\n// Disable/Enable the plugin\npicture.guillotine('disable');\npicture.guillotine('enable');\n\n// Remove the plugin (reset everything)\npicture.guillotine('remove');\n\n```\n\nOptionally, you can set the initial position and state of the image with the\n**init** option. It takes a data object similar to the one returned by *getData*.\nYou may set *angle*, *scale*, *x* and *y*, any other property will be ignored:\n```javascript\npicture.guillotine({\n width: 400,\n height: 300,\n init: { angle: 90, x: 80 }\n});\n\n```\n\nFor further info and options dig through the [code base] (src/jquery.guillotine.coffee)\nthat has a fair share of comments and it's intentionally coded in CoffeScript\nto ease out reading and customizing it.\n\n\nSupport\n-------\n* **Dragging** support for both mouse and touch devices (works on IE8).\n* **Rotation** is achieved using CSS3 'transform' property, so it doesn't work\n on IE8, but it's automatically disabled on devices that don't support it.\n In such case *rotateLeft* and *rotateRight* won't perform any action but will\n still trigger the event and/or callback to let you know the user is trying and\n allow you to handle it appropriately.\n* **Zoom**, **Fit** and **Center** are handled with absolute positioning,\n they work on IE8.\n\nFor a more detailed list of supported browsers and devises check out the\n[support page](//github.com/matiasgagliano/guillotine/wiki/Support) on the wiki.\n\nIt would be great if you could test it on other browsers and devices and share\nyour experience on the wiki (or open an issue if it doesn't work properly).\n\n\nLicense\n-------\nGuillotine is dual licensed under the MIT or GPLv3 licenses.\n* <http://opensource.org/licenses/MIT>\n* <http://opensource.org/licenses/GPL-3.0>\n\n\nMore features\n-------------\nThe plugin aims to have a simple and general API to allow interaction, specific\nfeatures and the user interface are left for the developer to implement.\nThis allows the plugin to be as flexible as possible.\n\nFor edge cases is that the [code base](src/jquery.guillotine.coffee)\nhas been kept as maintainable as possible, in those cases you are free and\nencouraged to customize the plugin to suite your needs.\n\n\nContributing\n------------\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n",
"readmeFilename": "README.md",
"bugs": {
"url": "https://github.com/matiasgagliano/guillotine/issues"
},
"_id": "jquery.guillotine@1.4.1",
"scripts": {},
"_shasum": "5635d2a96af48196aff6c3d07e20dd5fe53a0f64",
"_from": "jquery.guillotine@latest"
}