{"id":13518564,"url":"https://github.com/filamentgroup/shoestring","last_synced_at":"2025-10-22T18:17:37.603Z","repository":{"id":2931242,"uuid":"3942658","full_name":"filamentgroup/shoestring","owner":"filamentgroup","description":" A lightweight, simple DOM utility made to run on a tight budget.","archived":true,"fork":false,"pushed_at":"2022-08-30T21:37:43.000Z","size":960,"stargazers_count":439,"open_issues_count":3,"forks_count":20,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-01-11T20:54:23.904Z","etag":null,"topics":["dom","dom-utilities","jquery"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filamentgroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-04-05T18:18:42.000Z","updated_at":"2024-10-05T07:27:55.000Z","dependencies_parsed_at":"2022-08-31T02:51:10.948Z","dependency_job_id":null,"html_url":"https://github.com/filamentgroup/shoestring","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filamentgroup%2Fshoestring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filamentgroup%2Fshoestring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filamentgroup%2Fshoestring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filamentgroup%2Fshoestring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filamentgroup","download_url":"https://codeload.github.com/filamentgroup/shoestring/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234732484,"owners_count":18878416,"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":["dom","dom-utilities","jquery"],"created_at":"2024-08-01T05:01:46.298Z","updated_at":"2025-09-30T11:31:56.402Z","avatar_url":"https://github.com/filamentgroup.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":":warning: This project is archived and the repository is no longer maintained. \n\n# Shoestring\n\n[![Filament Group](http://filamentgroup.com/images/fg-logo-positive-sm-crop.png) ](http://www.filamentgroup.com/)\n\nA lightweight, simple DOM utility made to run on a tight budget.\n\nShoestring is part of the [Southstreet workflow](https://github.com/filamentgroup/southstreet) at Filament Group.\n\nYou can find more details in the [API documentation](http://filamentgroup.github.io/shoestring/dist/docs/).\n\n[![Build Status](https://travis-ci.org/filamentgroup/shoestring.svg?branch=master)](https://travis-ci.org/filamentgroup/shoestring) \n\n## Philosophy\n\n\nShoestring is a lightweight, modular DOM framework intended for developers who need their code to download and run as fast as possible. It is intended to be \"just enough\" of a tool to efficently write maintainable cross-browser JavaScript. The API is modeled after jQuery but we intentionally implement a tiny subset of the API to cover only the methods we commonly need in our projects.  Each feature is built as an optional extension to a minimal core so each can be removed from the production build (dependencies between extensions are rare). The selector engine delegates to modern browsers' native `document.querySelectorAll` (IE8) and `addEventListener` (IE9), which means it requires browsers that support those features. For projects that require deeper compatibility or a richer set of features, it is simple to swap in jQuery instead. As a rule, anything that works with Shoestring should work with jQuery, but not the converse.\n\nOur goal is to strike a good balance of code weight, runtime speed, browser support, and developer convenience. \n\n\n## Features\n\nShoestring's API is inspired by jQuery.\n\nTechnically, shoestring.js is a very small, extendable core function. That core function doesn't come with much more than a means of finding and/or generating HTML elements, a DOM-ready handler, and a few essential element-traversal methods like `each`, `find`, `children`. Using its `shoestring.fn` API, its core is easy to extend further, and many extensions are available for you to include in your build – the default build includes all extensions, but it's still very small (~3kb compressed).\n\nIf you are concerned about compatibility issues/pitfalls consider using the development build releases (`-dev` in the [releases](https://github.com/filamentgroup/shoestring/releases)). We've endeavored to throw exceptions where a particular invocation pattern or feature isn't supported as a means to document the disparity. We recommend that you use the development version in development and the regular non-`-dev` version in production.\n\nThere are three sets of extensions to the Shoestring core: DOM manipulation, events, and ajax.\n\n### DOM\n\nIf you've used jQuery, the structure and behavior of the DOM manipulation methods will be immediately familiar:\n\n```javascript\nshoestring( \".foo\" ).addClass( \"bar\" ).attr( \"data-baz\", \"bak\" );\n```\n\nThat is, construct a sequence of elements from the DOM and invoke each method on all the elements of the sequence in turn. You can find a full list of the supported DOM methods and their arguments in the [API docs](http://filamentgroup.github.io/shoestring/dist/docs/) under the `dom/*` subdirectory.\n\n### Events\n\nShoestring supports most of the jQuery events API including: custom events that bubble, event namespaces, a normalized event object, event arguments, DOM Ready, a `.one` method, comprehensive `.unbind`, etc. The major difference here is that Shoestring does not support the event delegation helpers built into jQuery, like `.delegate` or `.on` with a selector argument.\n\n```javascript\nshoestring( \".foo\" ).bind( \"click\", function( event ) { ... });\n```\n\nOr with a custom event triggered on a child element:\n\n\n```javascript\nshoestring( \".foo\" ).bind( \"bar\", function( event, arg ) {\n  ...\n  if(arg == 1) { ... }\n  ...\n});\n\n// ...\n\nshoestring( \".foo\" ).children().first().trigger( \"bar\", 1 );\n```\n\nYou can find a full list of the supported event methods and their arguments in the [API docs](http://filamentgroup.github.io/shoestring/dist/docs/) under the `events/*` subdirectory.\n\n\n### Ajax\n\nShoestring supports a full `shoestring.ajax` method as well as some shorthand helpers like `shoestring.get` and `shoestring.post`.\n\n```javascript\nshoestring.ajax( \"/foo\", {\n  success: function(){ ... },\n  method: \"GET\",\n  ...\n});\n```\n\nWhich could also be accomplished using `shoestring.get`\n\n```javascript\nshoestring.get( \"/foo\", function(){ ... });\n```\n\nYou can find a full list of the supported ajax methods and their arguments in the [API docs](http://filamentgroup.github.io/shoestring/dist/docs/) under the `ajax/*` subdirectory.\n\n\n## Extensions\n\nExtending Shoestring is done in nearly the same fashion as jQuery. There is an object on which you can define properties using functions and those functions will have access to the Shoestring DOM element sequence during invocation using `this`. As an example the `remove` method:\n\n```javascript\n/**\n * Remove the current set of elements from the DOM.\n *\n * @return shoestring\n * @this shoestring\n */\nshoestring.fn.remove = function(){\n  return this.each(function(){\n    if( this.parentNode ) {\n      this.parentNode.removeChild( this );\n    }\n  });\n};\n```\n\nIt uses the `each` method to handle the DOM elements in the current sequence in turn.\n\n**NOTE** these definitions must be made before a Shoestring object that depends on them is constructed. This is in contrast with jQuery where each object has access to new methods through the prototype chain.\n\n### Modules\n\nEach extension to Shoestring included in the repository is defined as an AMD module, but only for build purposes. We don't support, or plan to support, loading the library as modules in the browser.\n\n```javascript\n//\u003e\u003eexcludeStart(\"exclude\", pragmas.exclude);\ndefine([ \"shoestring\", \"dom/remove\" ], function(){\n//\u003e\u003eexcludeEnd(\"exclude\");\n\nshoestring.fn.foo = function(){ ... };\n\n//\u003e\u003eexcludeStart(\"exclude\", pragmas.exclude);\n});\n//\u003e\u003eexcludeEnd(\"exclude\");\n```\n\nNote that the AMD wrapper is removed during the process of the build and that the dependencies are defined from the `src` subdirectory. More on custom builds below.\n\n### Dependencies\n\nBrowsing the modules in Shoestring you'll notice that very few have explicit dependencies in their module definitions. This is by design. We are interested in being able to select the minimum number of methods necessary for a given project to reduce load and parse times.\n\n## Builds\n\nShoestring releases include two different builds, one for development and one for production. The development build is larger. It is intended to help with jQuery compatibility issues and includes other development utilities like the method tracker. The production build is meant to be shipped in production and does not include the extra dev-time helpers.\n\n### Custom\n\nThis repository supports custom builds through creating a meta-module in the `build/custom/` directory and running the default Grunt task. To get started building a custom production build, do the following:\n\n1. make sure the project dependencies are installed with `npm install`\n2. copy `build/development.js` to `build/custom/foo.js`\n3. run `grunt` or `node node_modules/.bin/grunt`\n4. use `dist/foo.js`\n\n### Tracker\n\nIncluded in the development build is a method tracker. It works by proxying all calls to `shoestring.fn` methods through a corresponding method that records the invocation in local storage. **NOTE** this does not include methods defined on `shoestring`. Then the methods being used across pages by your application can be inspected.\n\n```javascript\nJSON.parse( window.localStorage.getItem(shoestring.trackedMethodsKey) );\n```\n\nIf the method tracker is included during a significant portion of development this list can be used to remove unused functions from your Shoestring build with a custom meta-module.\n\n## Contributing\n\nPlease see the [contribution guidelines](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilamentgroup%2Fshoestring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilamentgroup%2Fshoestring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilamentgroup%2Fshoestring/lists"}