|
0
|
1 # Shoestring
|
|
|
2
|
|
|
3 [ ](http://www.filamentgroup.com/)
|
|
|
4
|
|
|
5 A lightweight, simple DOM utility made to run on a tight budget.
|
|
|
6
|
|
|
7 Shoestring is part of the [Southstreet workflow](https://github.com/filamentgroup/southstreet) at Filament Group.
|
|
|
8
|
|
|
9 You can find more details in the [API documentation](http://filamentgroup.github.io/shoestring/dist/docs/).
|
|
|
10
|
|
|
11 [](https://travis-ci.org/filamentgroup/shoestring) [](https://david-dm.org/filamentgroup/shoestring#info=devDependencies)
|
|
|
12
|
|
|
13 ## Philosophy
|
|
|
14
|
|
|
15
|
|
|
16 Shoestring 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.
|
|
|
17
|
|
|
18 Our goal is to strike a good balance of code weight, runtime speed, browser support, and developer convenience.
|
|
|
19
|
|
|
20
|
|
|
21 ## Features
|
|
|
22
|
|
|
23 Shoestring's API is inspired by jQuery.
|
|
|
24
|
|
|
25 Technically, 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).
|
|
|
26
|
|
|
27 If 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.
|
|
|
28
|
|
|
29 There are three sets of extensions to the Shoestring core: DOM manipulation, events, and ajax.
|
|
|
30
|
|
|
31 ### DOM
|
|
|
32
|
|
|
33 If you've used jQuery, the structure and behavior of the DOM manipulation methods will be immediately familiar:
|
|
|
34
|
|
|
35 ```javascript
|
|
|
36 shoestring( ".foo" ).addClass( "bar" ).attr( "data-baz", "bak" );
|
|
|
37 ```
|
|
|
38
|
|
|
39 That 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.
|
|
|
40
|
|
|
41 ### Events
|
|
|
42
|
|
|
43 Shoestring 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.
|
|
|
44
|
|
|
45 ```javascript
|
|
|
46 shoestring( ".foo" ).bind( "click", function( event ) { ... });
|
|
|
47 ```
|
|
|
48
|
|
|
49 Or with a custom event triggered on a child element:
|
|
|
50
|
|
|
51
|
|
|
52 ```javascript
|
|
|
53 shoestring( ".foo" ).bind( "bar", function( event, arg ) {
|
|
|
54 ...
|
|
|
55 if(arg == 1) { ... }
|
|
|
56 ...
|
|
|
57 });
|
|
|
58
|
|
|
59 // ...
|
|
|
60
|
|
|
61 shoestring( ".foo" ).children().first().trigger( "bar", 1 );
|
|
|
62 ```
|
|
|
63
|
|
|
64 You 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.
|
|
|
65
|
|
|
66
|
|
|
67 ### Ajax
|
|
|
68
|
|
|
69 Shoestring supports a full `shoestring.ajax` method as well as some shorthand helpers like `shoestring.get` and `shoestring.post`.
|
|
|
70
|
|
|
71 ```javascript
|
|
|
72 shoestring.ajax( "/foo", {
|
|
|
73 success: function(){ ... },
|
|
|
74 method: "GET",
|
|
|
75 ...
|
|
|
76 });
|
|
|
77 ```
|
|
|
78
|
|
|
79 Which could also be accomplished using `shoestring.get`
|
|
|
80
|
|
|
81 ```javascript
|
|
|
82 shoestring.get( "/foo", function(){ ... });
|
|
|
83 ```
|
|
|
84
|
|
|
85 You 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.
|
|
|
86
|
|
|
87
|
|
|
88 ## Extensions
|
|
|
89
|
|
|
90 Extending 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:
|
|
|
91
|
|
|
92 ```javascript
|
|
|
93 /**
|
|
|
94 * Remove the current set of elements from the DOM.
|
|
|
95 *
|
|
|
96 * @return shoestring
|
|
|
97 * @this shoestring
|
|
|
98 */
|
|
|
99 shoestring.fn.remove = function(){
|
|
|
100 return this.each(function(){
|
|
|
101 if( this.parentNode ) {
|
|
|
102 this.parentNode.removeChild( this );
|
|
|
103 }
|
|
|
104 });
|
|
|
105 };
|
|
|
106 ```
|
|
|
107
|
|
|
108 It uses the `each` method to handle the DOM elements in the current sequence in turn.
|
|
|
109
|
|
|
110 **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.
|
|
|
111
|
|
|
112 ### Modules
|
|
|
113
|
|
|
114 Each 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.
|
|
|
115
|
|
|
116 ```javascript
|
|
|
117 //>>excludeStart("exclude", pragmas.exclude);
|
|
|
118 define([ "shoestring", "dom/remove" ], function(){
|
|
|
119 //>>excludeEnd("exclude");
|
|
|
120
|
|
|
121 shoestring.fn.foo = function(){ ... };
|
|
|
122
|
|
|
123 //>>excludeStart("exclude", pragmas.exclude);
|
|
|
124 });
|
|
|
125 //>>excludeEnd("exclude");
|
|
|
126 ```
|
|
|
127
|
|
|
128 Note 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.
|
|
|
129
|
|
|
130 ### Dependencies
|
|
|
131
|
|
|
132 Browsing 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.
|
|
|
133
|
|
|
134 ## Builds
|
|
|
135
|
|
|
136 Shoestring 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.
|
|
|
137
|
|
|
138 ### Custom
|
|
|
139
|
|
|
140 This 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:
|
|
|
141
|
|
|
142 1. make sure the project dependencies are installed with `npm install`
|
|
|
143 2. copy `build/development.js` to `build/custom/foo.js`
|
|
|
144 3. run `grunt` or `node node_modules/.bin/grunt`
|
|
|
145 4. use `dist/foo.js`
|
|
|
146
|
|
|
147 ### Tracker
|
|
|
148
|
|
|
149 Included 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.
|
|
|
150
|
|
|
151 ```javascript
|
|
|
152 JSON.parse( window.localStorage.getItem(shoestring.trackedMethodsKey) );
|
|
|
153 ```
|
|
|
154
|
|
|
155 If 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.
|
|
|
156
|
|
|
157 ## Contributing
|
|
|
158
|
|
|
159 Please see the [contribution guidelines](CONTRIBUTING.md).
|
