formstone/docs/json/upload.json

Library of modular front end components.

{"main":["upload.js","upload.css"],"options":[{"name":"accept","type":"string","description":"Input accept attribute"},{"name":"action","type":"string","description":"Where to submit uploads"},{"name":"autoUpload","type":"boolean","default":"false","description":"Beging upload when files are dropped"},{"name":"beforeSend","type":"function","description":"Run before request sent, must return modified formdata or `false` to cancel"},{"name":"chunked","type":"boolean","default":"false","description":"Use chunked uploading, if supported"},{"name":"chunkSize","type":"int","default":"100","description":"Size to chunk, in kB"},{"name":"customClass","type":"string","default":"''","description":"Class applied to instance"},{"name":"dataType","type":"string","default":"'html'","description":"Data type of AJAX request"},{"name":"label","type":"string","default":"'Drag and drop files or click to select'","description":"Drop target text; `false` to disable"},{"name":"leave","type":"string","default":"'You have uploads pending, are you sure you want to leave this page?'","description":"Before leave message"},{"name":"maxConcurrent","type":"int","default":"2","description":"Number of files to simultaneously upload"},{"name":"maxFiles","type":"int OR boolean","default":"false","description":"Total number of files that can be uploaded; `false` to disable"},{"name":"maxSize","type":"int","default":"5242880","description":"Max file size allowed"},{"name":"multiple","type":"true","default":"true","description":"Flag to allow mutiple file uploads"},{"name":"postData","type":"object","description":"Extra data to post with upload"},{"name":"postKey","type":"string","default":"'file'","description":"Key to upload file as"},{"name":"theme","type":"string","default":"\"fs-light\"","description":"Theme class name"}],"events":[{"name":"chunkcomplete","description":"File chunk complete"},{"name":"chunkstart","description":"File chunk starting"},{"name":"chunkerror","description":"File chunk error"},{"name":"complete","description":"All uploads are complete"},{"name":"filecomplete","description":"Specific upload complete"},{"name":"filedragenter","description":"File dragged into target"},{"name":"filedragleave","description":"File dragged from target"},{"name":"filedragover","description":"File dragged over target"},{"name":"fileerror","description":"Specific upload error"},{"name":"fileprogress","description":"Specific upload progress"},{"name":"filestart","description":"Specific upload starting"},{"name":"start","description":"Uploads starting"},{"name":"queued","description":"Files are queued for upload"}],"methods":[{"name":"abort","description":"Cancels all active uploads.","examples":["$(\".target\").upload(\"abort\");"]},{"name":"defaults","description":"Extends plugin default settings; effects instances created hereafter.","params":[{"name":"options","type":"object","default":"{}","description":"New plugin defaults"}],"examples":["$.upload(\"defaults\", { ... });"]},{"name":"destroy","description":"Removes plugin instance.","examples":["$(\".target\").upload(\"destroy\");"]},{"name":"disable","description":"Disables target instance.","examples":["$(\".target\").upload(\"disable\");"]},{"name":"enable","description":"Enables target instance.","examples":["$(\".target\").upload(\"enable\");"]},{"name":"start","description":"Starts queued uploads; Use when autoUpload is set to false.","examples":["$(\".target\").upload(\"start\");"]}],"name":"Upload","type":"widget","description":"A jQuery plugin for simple drag and drop uploads.","dependencies":["jQuery","core.js"],"css":[{"name":".fs-upload-element","type":"element","description":"Target elmement"},{"name":".fs-upload","type":"element","description":"Base widget class"},{"name":".fs-upload.fs-upload-dropping","type":"modifier","description":"Indicates dropping state"},{"name":".fs-upload.fs-upload-disabled","type":"modifier","description":"Indicates disabled state"},{"name":".fs-upload-input","type":"element","description":"Masked Input"},{"name":".fs-upload-target","type":"element","description":"Drop target"}],"use":"### Basic\n\nUpload will create a simple 'drop zone' for file uploads:\n\n```javascript\n$(\".target\").upload({\n  action: \"upload.php\"\n});\n```\n\n```markup\n<div class=\"target\"></div>\n```\n\nNote: Older browsers do not support the <a href=\"http://caniuse.com/#feat=fileapi\" target=\"_blank\">File API</a>. Developers will need to provide a proper fallback. Support can be checked in the `Formstone.support` object:\n\n```js\nif (Formstone.support.file) {\n  ...\n}\n```\n\n### Form Data\n\nForm Data can be modified before the request is made. The request can also be aborted based on file attributes:\n\n```javascript\n$(\".target\").upload({\n  beforeSend: onBeforeSend\n});\n\nfunction onBeforeSend(formData, file) {\n  // Cancel request\n  if (file.name.indexOf(\".jpg\") < 0) {\n    return false;\n  }\n\n  // Modify and return form data\n  formdata.append(\"input_name\", \"input_value\");\n\n  return formData;\n}\n```\n\n### Abort\n\nActive uploads can be aborted one at a time by passing the file's index, or abort the entire queue by excluding the second parameter:\n\n```javascript\n// Abort single file\n$(\".target\").upload(\"abort\", file.index);\n\n// Abort entire queue\n$(\".target\").upload(\"abort\");\n```\n\n### Uploads\n\nUpload does not store or manipulate uploaded files on the server, it simply facilitates the asynchronous upload process from the front end.\n","demo":"<h4>Basic</h4>\r\n\r\n<!-- START: FIRSTDEMO -->\r\n\r\n<style>\r\n  .filelists { margin: 20px 0; }\r\n  .filelists h5 { margin: 10px 0 0; }\r\n  .filelists .cancel_all { color: red; cursor: pointer; clear: both; font-size: 10px; margin: 0; text-transform: uppercase; }\r\n  .filelist { margin: 0; padding: 10px 0; }\r\n  .filelist li { background: #fff; border-bottom: 1px solid #ECEFF1; font-size: 14px; list-style: none; padding: 5px; position: relative; }\n  .filelist li:before { display: none !important; } /* main site demos */\n  .filelist li .bar { background: #eceff1; content: ''; height: 100%; left: 0; position: absolute; top: 0; width: 0; z-index: 0;\r\n    -webkit-transition: width 0.1s linear;\r\n        transition: width 0.1s linear;\r\n  }\r\n  .filelist li .content { display: block; overflow: hidden; position: relative; z-index: 1; }\r\n  .filelist li .file { color: #455A64; float: left; display: block; overflow: hidden; text-overflow: ellipsis; max-width: 50%; white-space: nowrap; }\r\n  .filelist li .progress { color: #B0BEC5; display: block; float: right; font-size: 10px; text-transform: uppercase; }\r\n  .filelist li .cancel { color: red; cursor: pointer; display: block; float: right; font-size: 10px; margin: 0 0 0 10px; text-transform: uppercase; }\r\n  .filelist li.error .file { color: red; }\r\n  .filelist li.error .progress { color: red; }\r\n  .filelist li.error .cancel { display: none; }\r\n</style>\r\n\r\n<script>\r\n  Formstone.Ready(function() {\r\n    $(\".upload\").upload({\r\n      maxSize: 1073741824,\r\n      beforeSend: onBeforeSend\r\n    }).on(\"start.upload\", onStart)\r\n      .on(\"complete.upload\", onComplete)\r\n      .on(\"filestart.upload\", onFileStart)\r\n      .on(\"fileprogress.upload\", onFileProgress)\r\n      .on(\"filecomplete.upload\", onFileComplete)\r\n      .on(\"fileerror.upload\", onFileError)\r\n      .on(\"chunkstart.upload\", onChunkStart)\r\n      .on(\"chunkprogress.upload\", onChunkProgress)\r\n      .on(\"chunkcomplete.upload\", onChunkComplete)\r\n      .on(\"chunkerror.upload\", onChunkError)\r\n      .on(\"queued.upload\", onQueued);\r\n\r\n    $(\".filelist.queue\").on(\"click\", \".cancel\", onCancel);\r\n    $(\".cancel_all\").on(\"click\", onCancelAll);\r\n  });\r\n\r\n  function onCancel(e) {\r\n    console.log(\"Cancel\");\r\n    var index = $(this).parents(\"li\").data(\"index\");\r\n    $(this).parents(\"form\").find(\".upload\").upload(\"abort\", parseInt(index, 10));\r\n  }\r\n\r\n  function onCancelAll(e) {\r\n    console.log(\"Cancel All\");\r\n    $(this).parents(\"form\").find(\".upload\").upload(\"abort\");\r\n  }\r\n\r\n  function onBeforeSend(formData, file) {\r\n    console.log(\"Before Send\");\r\n    formData.append(\"test_field\", \"test_value\");\r\n    // return (file.name.indexOf(\".jpg\") < -1) ? false : formData; // cancel all jpgs\r\n    return formData;\r\n  }\r\n\r\n  function onQueued(e, files) {\r\n    console.log(\"Queued\");\r\n    var html = '';\r\n    for (var i = 0; i < files.length; i++) {\r\n      html += '<li data-index=\"' + files[i].index + '\"><span class=\"content\"><span class=\"file\">' + files[i].name + '</span><span class=\"cancel\">Cancel</span><span class=\"progress\">Queued</span></span><span class=\"bar\"></span></li>';\r\n    }\r\n\r\n    $(this).parents(\"form\").find(\".filelist.queue\")\r\n      .append(html);\r\n  }\r\n\r\n  function onStart(e, files) {\r\n    console.log(\"Start\");\r\n    $(this).parents(\"form\").find(\".filelist.queue\")\r\n      .find(\"li\")\r\n      .find(\".progress\").text(\"Waiting\");\r\n  }\r\n\r\n  function onComplete(e) {\r\n    console.log(\"Complete\");\r\n    // All done!\r\n  }\r\n\r\n  function onFileStart(e, file) {\r\n    console.log(\"File Start\");\r\n    $(this).parents(\"form\").find(\".filelist.queue\")\r\n      .find(\"li[data-index=\" + file.index + \"]\")\r\n      .find(\".progress\").text(\"0%\");\r\n  }\r\n\r\n  function onFileProgress(e, file, percent) {\r\n    console.log(\"File Progress\");\r\n    var $file = $(this).parents(\"form\").find(\".filelist.queue\").find(\"li[data-index=\" + file.index + \"]\");\r\n\r\n    $file.find(\".progress\").text(percent + \"%\")\r\n    $file.find(\".bar\").css(\"width\", percent + \"%\");\r\n  }\r\n\r\n  function onFileComplete(e, file, response) {\r\n    console.log(\"File Complete\");\r\n    if (response.trim() === \"\" || response.toLowerCase().indexOf(\"error\") > -1) {\r\n      $(this).parents(\"form\").find(\".filelist.queue\")\r\n        .find(\"li[data-index=\" + file.index + \"]\").addClass(\"error\")\r\n        .find(\".progress\").text(response.trim());\r\n    } else {\r\n      var $target = $(this).parents(\"form\").find(\".filelist.queue\").find(\"li[data-index=\" + file.index + \"]\");\r\n      $target.find(\".file\").text(file.name);\r\n      $target.find(\".progress\").remove();\r\n      $target.find(\".cancel\").remove();\r\n      $target.appendTo( $(this).parents(\"form\").find(\".filelist.complete\") );\r\n    }\r\n  }\r\n\r\n  function onFileError(e, file, error) {\r\n    console.log(\"File Error\");\r\n    $(this).parents(\"form\").find(\".filelist.queue\")\r\n      .find(\"li[data-index=\" + file.index + \"]\").addClass(\"error\")\r\n      .find(\".progress\").text(\"Error: \" + error);\r\n  }\r\n\r\n  function onChunkStart(e, file) {\r\n    console.log(\"Chunk Start\");\r\n  }\r\n\r\n  function onChunkProgress(e, file, percent) {\r\n    console.log(\"Chunk Progress\");\r\n  }\r\n\r\n  function onChunkComplete(e, file, response) {\r\n    console.log(\"Chunk Complete\");\r\n  }\r\n\r\n  function onChunkError(e, file, error) {\r\n    console.log(\"Chunk Error\");\r\n  }\r\n</script>\r\n\r\n<div class=\"demo_container\">\r\n  <div class=\"demo_example\">\r\n    <form action=\"#\" method=\"GET\" class=\"form demo_form\">\r\n      <div class=\"upload\" data-upload-options='{\"action\":\"../_extra/upload-target.php\"}'></div>\n      <div class=\"filelists\">\r\n        <h5>Complete</h5>\r\n        <ol class=\"filelist complete\">\r\n        </ol>\r\n        <h5>Queued</h5>\r\n        <ol class=\"filelist queue\">\r\n        </ol>\r\n        <span class=\"cancel_all\">Cancel All</span>\r\n      </div>\r\n    </form>\r\n  </div>\r\n  <div class=\"demo_code\">\r\n    <pre><code class=\"language-html\">&lt;div class=&quot;upload&quot;&gt;&lt;/div&gt;</code></pre>\r\n    <pre><code class=\"language-javascript\">$(\".upload\").upload({\r\n  action: \"//example.com/handle-upload.php\"\r\n});</code></pre>\r\n  </div>\r\n</div>\r\n\r\n<!-- END: FIRSTDEMO -->\r\n\r\n<h4>Chunked Uploads</h4>\r\n<div class=\"demo_container\">\r\n  <div class=\"demo_example\">\r\n    <form action=\"#\" method=\"GET\" class=\"form demo_form\">\r\n      <div class=\"upload\" data-upload-options='{\"action\":\"../_extra/upload-chunked.php\",\"chunked\":true}'></div>\n      <div class=\"filelists\">\r\n        <h5>Complete</h5>\r\n        <ol class=\"filelist complete\">\r\n        </ol>\r\n        <h5>Queued</h5>\r\n        <ol class=\"filelist queue\">\r\n        </ol>\r\n        <span class=\"cancel_all\">Cancel All</span>\r\n      </div>\r\n    </form>\r\n  </div>\r\n  <div class=\"demo_code\">\r\n    <pre><code class=\"language-html\">&lt;div class=&quot;upload&quot;&gt;&lt;/div&gt;</code></pre>\r\n    <pre><code class=\"language-javascript\">$(\".upload\").upload({\r\n  action: \"//example.com/handle-chunked-upload.php\",\r\n  chunked: true\r\n});</code></pre>\r\n  </div>\r\n</div>\r\n\r\n<h4>No Theme</h4>\r\n<div class=\"demo_container\">\r\n  <div class=\"demo_example\">\r\n    <form action=\"#\" method=\"GET\" class=\"form demo_form\">\r\n      <div class=\"upload\" data-upload-options='{\"action\":\"../_extra/upload-target.php\",\"theme\":\"\"}'></div>\r\n      <div class=\"filelists\">\r\n        <h5>Complete</h5>\r\n        <ol class=\"filelist complete\">\r\n        </ol>\r\n        <h5>Queued</h5>\r\n        <ol class=\"filelist queue\">\r\n        </ol>\r\n        <span class=\"cancel_all\">Cancel All</span>\r\n      </div>\r\n    </form>\r\n  </div>\r\n  <div class=\"demo_code\">\r\n    <pre><code class=\"language-html\">&lt;div class=&quot;upload&quot;&gt;&lt;/div&gt;</code></pre>\r\n    <pre><code class=\"language-javascript\">$(\".upload\").upload({\r\n  action: \"//example.com/handle-upload.php\",\r\n  theme: \"\"\r\n});</code></pre>\r\n  </div>\r\n</div>\r\n","document":"# Upload\n\nA jQuery plugin for simple drag and drop uploads.\n\n<!-- HEADER END -->\n\n<!-- NAV START -->\n\n* [Use](#use)\n* [Options](#options)\n* [Events](#events)\n* [Methods](#methods)\n* [CSS](#css)\n\n<!-- NAV END -->\n\n<!-- DEMO BUTTON -->\n\n<a name=\"use\"></a>\n\n## Using Upload\n\n\n#### Main\n\n```markup\nupload.js\nupload.css\n```\n\n\n#### Dependencies\n\n```markup\njQuery\ncore.js\n```\n\n### Basic\n\nUpload will create a simple 'drop zone' for file uploads:\n\n```javascript\n$(\".target\").upload({\n  action: \"upload.php\"\n});\n```\n\n```markup\n<div class=\"target\"></div>\n```\n\nNote: Older browsers do not support the <a href=\"http://caniuse.com/#feat=fileapi\" target=\"_blank\">File API</a>. Developers will need to provide a proper fallback. Support can be checked in the `Formstone.support` object:\n\n```js\nif (Formstone.support.file) {\n  ...\n}\n```\n\n### Form Data\n\nForm Data can be modified before the request is made. The request can also be aborted based on file attributes:\n\n```javascript\n$(\".target\").upload({\n  beforeSend: onBeforeSend\n});\n\nfunction onBeforeSend(formData, file) {\n  // Cancel request\n  if (file.name.indexOf(\".jpg\") < 0) {\n    return false;\n  }\n\n  // Modify and return form data\n  formdata.append(\"input_name\", \"input_value\");\n\n  return formData;\n}\n```\n\n### Abort\n\nActive uploads can be aborted one at a time by passing the file's index, or abort the entire queue by excluding the second parameter:\n\n```javascript\n// Abort single file\n$(\".target\").upload(\"abort\", file.index);\n\n// Abort entire queue\n$(\".target\").upload(\"abort\");\n```\n\n### Uploads\n\nUpload does not store or manipulate uploaded files on the server, it simply facilitates the asynchronous upload process from the front end.\n\n\n\n<a name=\"options\"></a>\n\n## Options\n\nSet instance options by passing a valid object at initialization, or to the public `defaults` method. Custom options for a specific instance can also be set by attaching a `data-upload-options` attribute to the target elment. This attribute should contain the properly formatted JSON object representing the custom options.\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| `accept` | `string` | &nbsp; | Input accept attribute |\n| `action` | `string` | &nbsp; | Where to submit uploads |\n| `autoUpload` | `boolean` | `false` | Beging upload when files are dropped |\n| `beforeSend` | `function` | &nbsp; | Run before request sent, must return modified formdata or `false` to cancel |\n| `chunked` | `boolean` | `false` | Use chunked uploading, if supported |\n| `chunkSize` | `int` | `100` | Size to chunk, in kB |\n| `customClass` | `string` | `''` | Class applied to instance |\n| `dataType` | `string` | `'html'` | Data type of AJAX request |\n| `label` | `string` | `'Drag and drop files or click to select'` | Drop target text; `false` to disable |\n| `leave` | `string` | `'You have uploads pending, are you sure you want to leave this page?'` | Before leave message |\n| `maxConcurrent` | `int` | `2` | Number of files to simultaneously upload |\n| `maxFiles` | `int OR boolean` | `false` | Total number of files that can be uploaded; `false` to disable |\n| `maxSize` | `int` | `5242880` | Max file size allowed |\n| `multiple` | `true` | `true` | Flag to allow mutiple file uploads |\n| `postData` | `object` | &nbsp; | Extra data to post with upload |\n| `postKey` | `string` | `'file'` | Key to upload file as |\n| `theme` | `string` | `\"fs-light\"` | Theme class name |\n\n<hr>\n<a name=\"events\"></a>\n\n## Events\n\nEvents are triggered on the target instance's element, unless otherwise stated.\n\n| Event | Description |\n| --- | --- |\n| `chunkcomplete` | File chunk complete |\n| `chunkstart` | File chunk starting |\n| `chunkerror` | File chunk error |\n| `complete` | All uploads are complete |\n| `filecomplete` | Specific upload complete |\n| `filedragenter` | File dragged into target |\n| `filedragleave` | File dragged from target |\n| `filedragover` | File dragged over target |\n| `fileerror` | Specific upload error |\n| `fileprogress` | Specific upload progress |\n| `filestart` | Specific upload starting |\n| `start` | Uploads starting |\n| `queued` | Files are queued for upload |\n\n<hr>\n<a name=\"methods\"></a>\n\n## Methods\n\nMethods are publicly available to all active instances, unless otherwise stated.\n\n### abort\n\nCancels all active uploads.\n\n```javascript\n$(\".target\").upload(\"abort\");\n```\n\n### defaults\n\nExtends plugin default settings; effects instances created hereafter.\n\n```javascript\n$.upload(\"defaults\", { ... });\n```\n\n#### Parameters\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| `options` | `object` | `{}` | New plugin defaults |\n\n### destroy\n\nRemoves plugin instance.\n\n```javascript\n$(\".target\").upload(\"destroy\");\n```\n\n### disable\n\nDisables target instance.\n\n```javascript\n$(\".target\").upload(\"disable\");\n```\n\n### enable\n\nEnables target instance.\n\n```javascript\n$(\".target\").upload(\"enable\");\n```\n\n### start\n\nStarts queued uploads; Use when autoUpload is set to false.\n\n```javascript\n$(\".target\").upload(\"start\");\n```\n\n<hr>\n<a name=\"css\"></a>\n\n## CSS\n\n| Class | Type | Description |\n| --- | --- | --- |\n| `.fs-upload-element` | `element` | Target elmement |\n| `.fs-upload` | `element` | Base widget class |\n| `.fs-upload.fs-upload-dropping` | `modifier` | Indicates dropping state |\n| `.fs-upload.fs-upload-disabled` | `modifier` | Indicates disabled state |\n| `.fs-upload-input` | `element` | Masked Input |\n| `.fs-upload-target` | `element` | Drop target |\n\n"}