{"id":22353995,"url":"https://github.com/movableink/cropduster","last_synced_at":"2025-07-30T08:34:42.944Z","repository":{"id":29296563,"uuid":"32829553","full_name":"movableink/cropduster","owner":"movableink","description":"Support tools for Movable Ink Web Crops","archived":false,"fork":false,"pushed_at":"2023-04-18T17:08:04.000Z","size":1793,"stargazers_count":12,"open_issues_count":19,"forks_count":2,"subscribers_count":66,"default_branch":"master","last_synced_at":"2024-11-29T22:56:03.983Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/movableink.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-24T22:46:34.000Z","updated_at":"2023-04-18T18:26:53.000Z","dependencies_parsed_at":"2024-06-19T00:23:41.668Z","dependency_job_id":"cd0b4939-a933-48b0-a3da-bc57104df895","html_url":"https://github.com/movableink/cropduster","commit_stats":{"total_commits":172,"total_committers":15,"mean_commits":"11.466666666666667","dds":0.5988372093023255,"last_synced_commit":"4f235359054213e8b575b95847f74226eaa881ea"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/movableink%2Fcropduster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/movableink%2Fcropduster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/movableink%2Fcropduster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/movableink%2Fcropduster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/movableink","download_url":"https://codeload.github.com/movableink/cropduster/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228114882,"owners_count":17871742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-04T13:10:46.657Z","updated_at":"2024-12-04T13:10:47.157Z","avatar_url":"https://github.com/movableink.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cropduster\n\nCropduster is a collection of tools for building pages to be web cropped by\nMovable Ink.\n\n[![Build Status](https://travis-ci.org/movableink/cropduster.svg?branch=master)](https://travis-ci.org/movableink/cropduster)\n\n## Installation\n\nCropduster is on npm. Install it with:\n\n```bash\nnpm install --save-dev cropduster\n```\n\nThe use it by importing it from your es6-enabled javascript file:\n\n```javascript\nimport CD from 'cropduster';\n```\n\n## Legacy Installation\n\nTo use Cropduster directly in the browser, loaded from a script tag, you can\nfind legacy versions at:\n\nhttp://projects.movableink.com/production/libs/cropduster.[version].js\n\nWhere you replace `[version]` with the version you want to use.\n\nBrowser-only cropduster versions are no longer being published for new versions.\n\n## API\n\n### Asynchronous actions\nSometimes, Capturama needs to be explicitly told to hold off on finishing its\nscreen capture in order for some asynchronous actions to fire and complete. This\ncan be accomplished by calling `CD.pause` when an asynchronous action is about\nto start, and `CD.resume` when it has completed. `pause` takes a `maxSuspension`\nNumber argument specifying the maximum amount of time in milliseconds that your\nasynchronous action is allowed to take, and both functions take an optional\nfinal argument of a String message explaining the suspension, purely used for\ndebugging the Capturama log.\n\nIf you are using the Cropduster API for common asynchronous actions like\nfetching a URL or an image with `CD.get` and `CD.getImage`, or if you are using\nPromises directly, you do not need to manually call pause and resume. These\nmethods are used internally in the necessary places. However, if you are\ndoing something unusual that requires work to be delayed manually, each call to\n`CD.pause` must have a corresponding call to `CD.resume`, or the request to\nCapturama will eventually time out.\n\nExample:\n```javascript\nconst target = document.getElementById('text-box');\nconst customerQuality = CD.param('mi_customer_rating');\nconst tenSeconds = 10 * 1000;\n\nif (customerQuality === 'very-good') {\n  target.innerText = 'good customers get images quickly';\n} else if (customerQuality === 'very-bad') {\n  CD.pause(tenSeconds, 'making bad customers wait for their email to load...');\n\n  setTimeout(() =\u003e {\n    CD.resume();\n    target.innerText = 'bad customers have to wait for their images';\n  }, 1000);\n}\n```\n\nIt is generally recommended to call CD.pause as the last thing before starting\nan asynchronous action, and CD.resume as the very first thing once that action\nhas finished. If your asynchronous action completes successfully, but your\ncallback runs some code before calling CD.resume again, then you run the risk of\ntriggering a JavaScript error that stops execution of the current script. If\nCD.resume is not called after that first CD.pause, your image will eventually\ntime out, as opposed to failing immediately.\n\n*NOTE:* Cropduster previously offered `CD.suspend` and `CD.capture` functions\nthat achieved a similar goal. These functions have been replaced with `pause`\nand `resume`, to support a better synchronisation of state with Capturama, and\nto give a clearer sense of how these functions affect Capturama's workflow.\n\n### Selecting elements\n\n`CD.$` is useful for getting an array of DOM elements via a CSS selector. It always returns an array.\n\nExample:\n\n```javascript\nconst elements = CD.$('div.items');\nfor (let i = 0; i \u003c elements.length; i++) {\n  const element = elements[i];\n  element.style.display = 'none';\n}\n```\n\nor:\n\n```javascript\nconst elements = CD.$('div.items');\nfor (const element of elements) {\n  element.style.display = 'none';\n}\n```\n\n### Query params\n\n`CD.param` retrieves query parameters from the current document's URL. It does not support nested params or arrays of values.\n\nExample:\n\n```javascript\n// document.location is 'http://example.com/?fname=john\nconst fname = CD.param('fname');\nconsole.log(fname); // logs 'john'\n```\n\n### Fetching third-party resources\n\nMovable Ink's capture engine traditionally captures the web page as soon as the page's `ready` event fires. This can cause\nissues when the user tries to fetch pages via ajax, as the capture engine does not wait for the ajax load to complete\nbefore rendering. In order to delay capture until the request has finished, use `CD.get`. It temporarily suspends capture\nuntil the request completes. Note: the URL has to be CORS-accessible, see `CD.getCORS` if it isn't. When in doubt, use `CD.getCORS`.\n\nExample:\n\n```javascript\nCD.get('http://cors-enabled-site.com/page').then((response) =\u003e {\n  const { data, status, contentType } = response;\n  CD.$('h1')[0].innerHTML = data.header;\n});\n```\n\nSend POST and sending extra headers:\n\n```javascript\nCD.get('http://cors-enabled-site.com/page', {\n  method: 'POST',\n  body: '{\"ok\": \"yes\"}',\n  headers: {\n    'Accept': 'application/json'\n  }\n}).then((response) =\u003e {\n  CD.$('h1')[0].innerHTML = response.data.h1;\n})\n```\n\n### Fetching third-party resources with CORS\n\nSecurity restrictions prevent web pages from making cross-domain ajax requests. CORS\nis a workaround, but requires support from the website, and many websites do not\nsupport it. Instead, use `CD.getCORS` to use Movable Ink's CORS proxy to access the\npage.\n\nExample:\n\n```javascript\nCD.getCORS('http://example.com/page').then((response) =\u003e {\n  CD.$('h1')[0].innerHTML = response.data.header;\n});\n```\n\n### Fetching images\n\n_Deprecated:_ The `CD.getImage()` and `CD.getImages()` calls have been superseded by `CD.waitForAsset()`. They will continue to work for the foreseeable future, but `CD.waitForAsset` is preferred.\n\n`CD.waitForAsset` ensures that in-flight requests for a particular asset URL complete before capturing the page. `CD.waitForAsset` does not fetch the image, that is up to you to do however you may normally do it. If the image is not loading (\"in-flight\") when capturama tries to capture the page, there will be no impact. It can be called any time before page capture. `CD.waitForAsset` is compatible with `\u003cimg\u003e` tags, css `background-image` properties, and any other way an image is loaded into a webpage.\n\nExample:\n\n```javascript\nCD.$('.background')[0].style.backgroundImage = 'url(http://example.com/foo.png)';\nCD.waitForAsset('http://example.com/foo.png');\n```\n\n### Redirecting to another image\n\nSometimes, it is necessary to redirect to an image rather than rendering dynamic content. For example, a countdown timer may\nwant to just show an image after the countdown has expired. It is certainly possible to just render the image inside the\nwebpage and crop that, but a better solution is to use `CD.setImageRedirect` to issue a 302 redirect to the user to send them\nto the static content. If the function is called multiple times, the last image URL called is used.\n\nExample:\n\n```javascript\nCD.setImageRedirect('http://example.com/foo.png');\nconsole.log('user will be shown image located at http://example.com/foo.png');\n```\n\n### Storing extra analytics data\n\nIt is possible to store extra data using the `CD.setExtraData` call. This data will be available in the `extra_data` field of\nthe User-level Reports. Pass a javascript object, and it will be turned into JSON and stored in `extra_data`. Calling multiple\ntimes results in the objects being combined and any duplicate keys overwritten.\n\nExample:\n\n```javascript\nCD.setExtraData({userId: 5});\nCD.setExtraData({shownCategory: 'shoes'});\nconsole.log('extra_data field now contains {\"userId\":5,\"shownCategory\":\"shoes\"}');\n```\n\n### Setting custom per-user clickthrough URLs\n\nWhen showing dynamic content, it may be useful to be able to associate dynamic content with matching clickthroughs. Using\n`CD.setClickthrough`, you can save a clickthrough URL that users will visit when they click on the web crop. In order to work\nproperly, the query params on both the embed code's image and link must match. If called multiple times, only the last called\nclickthrough URL will be used.\n\nExample:\n\n```javascript\nCD.setClickthrough('http://example.com');\nconsole.log('If user clicks on the web crop, they will go to http://example.com');\n```\n\n## Testing\n\n    yarn install\n    yarn run test\n\n## Publishing\n\n 1. Open a pull request with your change; add a new entry to the changelog called \"Latest\" and list out your changes.\n 2. Wait for your pull request to get approved, then merge it into master.\n 3. Run the release command for the type of change, following the prompts (this will tag and push to github and release to npm):\n   * If you do not have access to publish to npm, ask @mnutt.\n   * If your change introduces any breaking changes whatsoever, it needs a major version bump. These should definitely be listed in the changelog.\n    - `yarn run release major`\n   * If your change introduces new features but does not break any existing workflows, it should bump the minor version.\n    - `yarn run release minor`\n   * If your change is fixes bugs or updates tests or something, you can just bump the patch version.\n    - `yarn run release` or `yarn run release patch`\n\n\n## Changelog\n\n### 7.0.0\n\n * Skip proxying requests for internal domains that support CORS\n\n### 6.0.0\n * Remove use of `fetch` (major bump as exposure to `response` object is a breaking change)\n\n### 5.5.0\n * Support non `utf-8` response encoding for `CD.get`\n\n### 5.4.0\n * Expose `response` in resolved CD.get Promise\n\n### 5.3.0\n * Bundling change: our package.json `main` points to webpacked version, `module` points to es6 version. Prefer es6 version unless you know you need the webpacked version.\n\n### 5.2.0\n * CD.get uses the `fetch` API instead of XMLHttpRequest\n\n### 5.1.0\n  * Add `withoutCredentials` to `CD.get()` options to disable sending `withCredentials` in requests.\n\n### 5.0.0\n  * Compiles the app with Webpack and Babel down to ES5 with sourcemaps.\n  * Returns Promises from CD.get, CD.getCORS, CD.getImage and CD.getImages\n  * NPM publishes the browser-ready script in dist/cropduster.browser.js\n\n### 4.1.0\n  * Add `withCredentials: true` to all `CD.get()` requests.\n\n### 4.0.1\n  * npm publishes the alternate es5 scripts in dist/cropduster.es5.js.\n\n### 4.0.0\n  * Switch from bower to npm; CD is now exported as es6 module. See the new installation instructions above.\n\n### 3.4.2\n  * Remove `bower` from npm postinstall, for npm usage.\n\n### 3.4.1\n  * Adds `CD.params()`, returning an object with all parameters.\n\n### 3.4.0\n  * Exposes the `content-type` response header within the callback of `CD.get()`.\n\n### 3.3.0\n  * Add support for `CD.waitForAsset()`. This API can be used to ensure that we will not render while the passed URL is in-flight.\n\n### 3.2.3\n  * fix bower/npm version numbers\n\n### 3.2.2\n  * Ensure that `CD.suspend(msg)` always logs the `msg` string\n\n### 3.2.1\n  * `CD.get()` and `CD.getCORS()` return the (integer) http status as the second argument of their callbacks. This is currently completely backwards-compatible, but we would like to make backwards-incompatible changes to this API in the future.\n\n### 3.2.0\n  * Support `CD.cancelRequest(msg)` for when crop wants to show fallback but not trigger error condition\n  * Support `CD.throwError(msg)` for when crop fails (such as XHR failure) and trigger error\n  * `CD.begin(msg)` and `CD.end(msg)` support an argument that will be logged for easier debugging\n\n### 3.1.1\n  * Support for `CD.getCORS()` with non-standard ports\n\n### 3.1.0\n  * `CD.getCORS()` sends `x-mi-cbe` request header to ensure requests consistently go to the same backend\n\n### 3.0.0\n  * No more reference counting or maxSuspensions\n  * `CD.getImages()` accepts two callbacks, one for when all images resolve and once for after each image resolves\n\n### 2.7.3\n  * `CD.capture` forces a redraw on the page\n\n### 2.7.2\n  * Ensure that `CD.getImages` actually suspends crop\n\n### 2.7.1\n  * Remove window.onerror handler\n  * Ensure that failing requests actually call callback with `null`, rather than empty string\n\n### 2.7.0\n  * Failing requests call the callback with `null`.\n  * Do not pass cors ttl headers on regular `get` request.\n\n### 2.6.0\n  * Add `get` to fetch resources without using CORS\n\n### 2.5.0\n  * Add `setImageRedirect`, `setClickthrough`, and `setExtraData`\n  * Set up TravisCI test suite\n\n### 2.4.0\n  * New options for CD.getCORS: `method` for changing HTTP method, `body` for sending request body when `POST` method is used,\n    and `headers` object for sending extra request headers.\n\n### 2.3.0\n  * Guarantee correct ordering of callbacks in getImages()\n\n## License\n\nCopyright \u0026copy; 2015 Movable, Inc\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmovableink%2Fcropduster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmovableink%2Fcropduster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmovableink%2Fcropduster/lists"}