Permalink
Browse files

Update README to let people know this is an obsolete name

  • Loading branch information...
Hamish Friedlander
Hamish Friedlander committed Nov 30, 2009
1 parent 7bf2d39 commit 9a771763a06dc41977a19f293e4e76beb630f6fc
Showing with 4 additions and 326 deletions.
  1. +4 −326 README.textile
View
@@ -1,334 +1,12 @@
-h1. Entwine - Support for Concrete UI style programming in jQuery
+h1. Concrete - Support for Concrete UI style programming in jQuery
By Hamish Friedlander, with thanks to "SilverStripe":http://www.silverstripe.com/
-Entwine tries to provide a new model of code organisation - a replacement for Object Oriented programming that is focused on adding functions to groups of DOM elements based on the structure and contents of those DOM elements. It's a merging of the model and view layer that initially seems weird, but can give very powerful results.
+h1. This project has been renamed to jQuery Entwine
-We're standing on the shoulders of giants here - combining ideas from Prototype's behaviour & lowpro and jQuery's effen & livequery (who themselves stole ideals from Self's Morphic UI and others), but extending & combining the concepts presented in those tools to provide a complete alternative to traditional OO concepts - self-aware methods, inheritance, polymorphisim and namespacing without a single class definition.
-
-h2. Getting Started
-
-* Walk through the "Tutorial":http://hafriedlander.github.com/jquery.entwine/tutorial/
-* Watch the "Screencast":http://www.vimeo.com/6353390 (shot during a introductory developer meeting at SilverStripe)
-* Join the "Google Group":http://groups.google.com/group/jquery-entwine and let us know what you think, or what other features you'd like to see
-
-h2. Name change
-
-jQuery Entwine used to be called jQuery Concrete. The name was changed to avoid confusion with another product. The concrete function remains as an alias, but all new code should use entwine
-
-h2. Basic use
-
-h4. First intro
-
-To attach methods to DOM nodes, call the `entwine` function on a jQuery selector object, passing a hash listing the method names and bodys
-
-<pre><code>
- $('div').entwine({
- foo: function(..){..},
- bar: function(..){..}
- });
-</code></pre>
-
-You can then call those methods on any jQuery object.
-
-<pre><code>
- $('#a').foo();
-</code></pre>
-
-Any elements in the jQuery selection that match the selector used during definition ('div' in this example) will have foo called with that element
-set as this. Any other objects are skipped. The return value will be the return value of foo() for the last matched DOM object in the set
-
-h4. A proper example
-
-Given this DOM structure:
-
-<pre><code>
- <body>
- <div class="internal_text">Internal text</div>
- <div class="attribute_text" rel="Attribute text"></div>
- <div>Nonsense</div>
- </body>
-</code></pre>
-
-And this entwine definition
-
-<pre><code>
- $('.internal_text').entwine({
- foo: function(){ console.log(this.text()); }
- });
- $('.attribute_text').entwine({
- foo: function(){ console.log(this.attr('rel')); }
- });
-</code></pre>
-
-Then this call
-
-<pre><code>
- $('div').foo();
-</code></pre>
-
-Will log this to the console
-
-<pre><code>
- Internal text
- Attribute text
-</code></pre>
-
-h4. Limitations
-
-When defining methods, the jQuery object that entwine is called on must be a plain selector, without context. These examples will not work
-
-<pre><code>
- $('div', el).entwine(...)
- $([ela, elb, elc]).entwine(...)
- $('<div id="a"></div>').entwine(...)
-</code></pre>
-
-h2. Live
-
-The definitions you provide are not bound to the elements that match at definition time. You can declare behaviour prior to the DOM existing in any
-form (i.e. prior to DOMReady) and later calls will function correctly.
-
-h2. Selector specifity
-
-When there are two definitions for a particular method on a particular DOM node, the function with the most _specific_ selector is used.
-_Specifity_ is calculated as defined by the CSS 2/3 spec. This can be seen as _subclassing_ applied to behaviour.
-
-Another example. Given this DOM structure
-
-<pre><code>
- <body>
- <div>Internal text</div>
- <div class="attribute_text" rel="Attribute text"></div>
- <div>Nonsense</div>
- </body>
-</code></pre>
-
-And this entwine definition
-
-<pre><code>
- $('div').entwine({
- foo: function(){ console.log(this.text()); }
- });
- $('.attribute_text').entwine({
- foo: function(){ console.log(this.attr('rel')); }
- });
-</code></pre>
-
-Then this call
-
-<pre><code>
- $('div').foo();
-</code></pre>
-
-Will log this to the console
-
-<pre><code>
- Internal text
- Attribute text
- Nonsense
-</code></pre>
-
-h2. Events
-
-If you declare a function with a name starting with 'on', then instead of defining that function, it will be bound to an event of that
-name. Just like other functions this binding will be live, and only the most specific definition will be used
-
-<pre><code>
- <head>
- <script type='text/javascript'>
- /* No need for onready wrapper. Events are bound as needed */
- $('div').entwine({
- onclick: function(){ this.css({backgroundColor: 'blue'}); }
- });
- $('.green').entwine({
- onclick: function(){ this.css({color: 'green'}); }
- });
- </script>
- <body>
- <div>Background will turn blue when clicked on</div>
- <div>Will also have blue background when clicked on</div>
- <div class='green'>Will have green text when clicked on. Background color will not change</div>
- </body>
-</code></pre>
-
-h2. Constructors / Destructors
-
-Declaring a function with the name `onmatch` will create a behavior that is called on each object when it matches. Likewise, `onunmatch` will
-be called when an object that did match this selector stops matching it (because it is removed, or because you've changed its properties).
-
-Note that an onunmatch block must be paired with an onmatch block - an onunmatch without an onmatch _in the same entwine definition block_ is illegal
-
-Like other functions, only the most specific definition will be used. However, because property changes are not atomic, this may not work as you
-expect.
-
-h2. Namespaces
-
-To avoid name clashes, to allow multiple bindings to the same event, and to generally seperate a set of functions from other code you can use namespaces
-
-<pre><code>
- $.entwine('foo.bar', function($){
- $('div').entwine({
- baz: function(){}
- });
- });
-</code></pre>
-
-You can then call these functions like this:
-
-<pre><code>
- $('div').entwine('foo.bar').baz()
-</code></pre>
-
-Namespaced functions work just like regular functions (`this` is still set to a matching DOM Node). However, specifity is calculated per namespace.
-This is particularly useful for events, because given this:
-
-<pre><code>
- $('div').entwine({
- onclick: function(){ this.css({backgroundColor: 'blue'}); }
- });
-
- $.entwine('foo', function($){
- $('div').entwine({
- onclick: function(){ this.css({color: 'green'}); }
- });
- });
-</code></pre>
-
-Clicking on a div will change the background **and** foreground color.
-
-This is particularly important when writing reusable code, since otherwise you can't know before hand whether your event handler will be called or not
-
-Although a namespace can be any string, best practise is to name them with dotted-identifier notation.
-
-h4. Namespaces and scope (or What the hell's up with that ugly function closure)
-
-Inside a namespace definition, functions remember the namespace they are in, and calls to other functions will be looked up inside that namespace first.
-Where they don't exist, they will be looked up in the base namespace
-
-<pre><code>
- $.entwine('foo', function($){
- $('div').entwine({
- bar: function() { this.baz(); this.qux(); }
- baz: function() { console.log('baz'); }
- })
- })
-
- $('div').entwine({
- qux: function() { console.log('qux'); }
- })
-</code></pre>
-
-Will print baz, qux to the console
-
-Note that 'exists' means that a function is declared in this namespace for _any_ selector, not just a matching one. Given the dom
-
-<pre><code>
- <div>Internal text</div>
-</code></pre>
-
-And the entwine definitions
-
-<pre><code>
- $.entwine('foo', function($){
- $('div').entwine({
- bar: function() { this.baz(); }
- });
- $('span').entwine({
- baz: function() { console.log('a'); }
- });
- })
-
-
- $('div').entwine({
- baz: function() { console.log('b'); }
- })
-</code></pre>
-
-Then doing $('div').bar(); will _not_ display b. Even though the span rule could never match a div, because baz is defined for some rule in the foo namespace, the base namespace will never be checked
-
-h4. Nesting namespace blocks
-
-You can also nest declarations. In this next example, we're defining the functions $().entwine('zap').bar() and $().entwine('zap.pow').baz()
-
-<pre><code>
- $.entwine('zap', function($){
- $('div').entwine({
- bar: function() { .. }
- })
- $.entwine('pow', function($){
- $('div').entwine({
- baz: function() { .. }
- })
- })
- })
-</code></pre>
-
-h4. Calling to another namespace (and forcing base)
-
-Inside a namespace, namespace lookups are by default relative to the current namespace.
-
-In some situations (such as the last example) you may want to force using the base namespace. In this case you can call entwine with the first argument being the base namespace code '.'. For example, if the first definition in the previous example was
-
-<pre><code>
- $.entwine('foo', function($){
- $('div').entwine({
- bar: function() { this.entwine('.').baz(); }
- })
- })
-</code></pre>
-
-Then b _would_ be output to the console.
-
-h4. Using
-
-Sometimes a block outside of a namespace will need to refer to that namespace repeatedly. By passing a function to the entwine function, you can change the looked-up namespace
-
-<pre><code>
- $.entwine('foo', function($){
- $('div').entwine({
- bar: function() { console.log('a'); }
- })
- })
-
- $('div').entwine('foo', function(){
- this.bar();
- this.bar();
- this.bar();
- });
-</code></pre>
-
-This equivalent to /with/ in javascript, and just like /with/, care should be taken to only use this construct in situations that merit it.
-
-h2. Tests
-
-Specs are written using the awesome "JSpec":http://github.com/visionmedia/jspec library. You can run them in two ways
-
-h4. Ad-hoc
-
-Open the file `spec/spec.html` in any modern browser
-
-h4. Continuous testing
-
-JSpec has a command line client which can be used for continuous testing. Make sure ruby is installed and enabled the "Gemcutter":http://gemcutter.org/ gem hosting service, like so:
-
-<pre><code>
- sudo gem install gemcutter
- sudo gem tumble
-</code></pre>
-
-Then install the jspec binary:
-
-<pre><code>
- sudo gem install jspec
-</code></pre>
-
-The JSpec command line tool should now be installed. This command will re-run the specs whenever you edit a file:
-
-<pre><code>
- jspec spec/spec.html -p src,spec
-</code></pre>
+This repository exists so that URLs won't break. I will attempt to continue to mirror updates to jQuery Entwine here, but you should update your remotes to the new "jquery.entwine":git://github.com/hafriedlander/jquery.entwine.git project as soon as possible
+Please see the "new project page":http://github.com/hafriedlander/jquery.entwine for more information about jQuery Entwine
h2. License

0 comments on commit 9a77176

Please sign in to comment.