improved source comments

009_twitter_search_app/js/collections/tweets_collection.js

@@ -38,6 +38,8 @@ define([
 
 		initialize: function() {
 
+			// Observer Pattern - listen for events triggered on object itself
+			// these events are triggered from outside this object! (from FormViews)
 			this.on( 'search', this.search );
 			this.on( 'cancel', this.cancel );
 

009_twitter_search_app/js/views/form_view.js

@@ -25,6 +25,7 @@ define([
 
 		initialize: function() {
 
+			// Observe Pattern - listen for Collection's events
 			this.collection.on( 'cancel', this.clearInput, this );
 
 		},
@@ -55,6 +56,7 @@ define([
 
 			e.preventDefault();
 
+			// Observer Pattern - trigget events to dependency objects!
 			// Trigger a "search" event with arguments to the handled collection.
 			// we don't know if the collection will handle this event so this is the safest way to
 			// dialog between different objects.
@@ -75,6 +77,7 @@ define([
 
 			e.preventDefault();
 
+			// Observer Pattern - trigget events to dependency objects!
 			if ( e.keyCode == 27 ) this.collection.trigger( 'cancel' );
 
 		}

009_twitter_search_app/js/views/title_view.js

@@ -31,6 +31,7 @@ define([
 
 		initialize: function() {
 
+			// Observe Pattern - listen for Collection's events
 			this.collection.on( 'search', this.render, this );
 			this.collection.on( 'cancel', this.render, this );
 

009_twitter_search_app/js/views/tweets_view.js

@@ -31,6 +31,7 @@ define([
 
 		initialize: function() {
 
+			// Observe Pattern - listen for Collection's events
 			// Binds collection's events to internal rendering functions.
 			this.collection.on( 'add', 			this.addItem, 		this );
 			this.collection.on( 'reset', 		this.initSearch, 	this );

009_twitter_search_app/readme.txt

@@ -2,4 +2,44 @@
    LearningBackbone - TwitterSearch - App
 ------------------------------------------------------
 
-Purpose of this example is to test how collections can be used to display things in a page.
+Purpose of this example is to test how collections can be used to display things in a page.
+
+
+
+In questo articolo voglio raccontare come � stata realizzata l'<strong>App dimostrativa</strong> TwitterSearch.
+
+TwitterSearch permette all'utente di <strong>effettuare ricerche su Twitter</strong> inserendo una query di ricerca personalizzata.
+I punti di interesse per l'apprendimento di Backbone sono:
+<ul>
+	<li>utilizzo di <strong>Model e Collection</strong> per la gestione dati</li>
+	<li>utilizzo di <strong>View e sub-views</strong> per il controllo UI</li>
+	<li>comunicazione tra dati e UI tramite la <strong>generazione di eventi</strong></li>
+</ul>
+<p style="text-align: center;"><a title="TwitterSearch Backbone App - Tutorial Example Application" href="http://www.movableapp.com/LearningBackbone/009_twitter_search_app/" target="_blank">Vai alla demo!</a> | <a title="TwitterSearch Backbone App - Tutorial Example Application" href="https://github.com/thepeg/LearningBackbone/tree/master/009_twitter_search_app" target="_blank">Codice sorgente su GitHub</a> | <a title="Learning BackboneJS Tutorial and Examples Project" href="http://movableapp.com/2012/06/backbonejs-by-examples/" target="_blank">LearningBackbone by Examples</a></p>
+<p style="text-align: center;"><!--more--></p>
+
+<h2>Interfaccia Utente</h2>
+<a href="http://www.consulenza-web.com/wp-content/uploads/2012/06/TwitterSearchUI.png"><img class="alignleft  wp-image-825" title="TwitterSearchUI" src="http://www.consulenza-web.com/wp-content/uploads/2012/06/TwitterSearchUI-270x300.png" alt="" width="189" height="210" /></a>L'interfaccia utente � composta una macro-view (Viewport) il cui compito � di organizzare al suo interno le sub-views.
+
+Le sub-views controllano i vari componenti dell'interfaccia grafica ovvero:
+<ul>
+	<li><span style="text-decoration: underline;">TitleView:</span> barra del titolo (stato della ricerca)</li>
+	<li><span style="text-decoration: underline;">FormView:</span> form di input e relativi eventi</li>
+	<li><span style="text-decoration: underline;">TweetsView:</span> risultato ricerca e messaggistica</li>
+</ul>
+<strong>NOTA:</strong> Si sarebbe anche potuto evitare l'utilizzo del Viewport in quanto questa � un'app comunque molto semplice. Tuttavia questa � una <span style="text-decoration: underline;">buona strategia per la progettazione e codifica</span> di applicazioni web complesse.
+Infatti il concetto di view e sub-view pu� essere applicato a componenti e sub-componenti: <strong>i classici widgets!</strong>
+<h2>Gestione dei Dati - Model e Collection</h2>
+I dati manipolati da questa applicazione sono i Tweet caricati attraverso le <a title="Twitter Json API Documentation" href="https://dev.twitter.com/docs/api/1/get/search" target="_blank">API JSON di Twitter</a>.
+Con ogni probabilit� una ricerca fornisce un elevato numero di risultati - un elenco di tweets - quindi il modo migliore di rappresentare questo scenario � una Collection.
+<ul>
+	<li><span style="text-decoration: underline;">TweetsCollection:</span> contiene un elenco di modelli (TweetModel) ed � incaricato di interfacciarsi con l'API Twitter per effettuare le ricerche.</li>
+	<li><span style="text-decoration: underline;">TweetModel:</span> contiene i dati del singolo tweet cos� come vengono forniti da Twitter</li>
+</ul>
+<h2>Interazione tra Componenti</h2>
+Il punto pi� delicato di questa applicazione (dimostrativa!!) � <strong>mettere in comunicazione</strong> la parte logica (Collection) con l'interfaccia utente (Views).
+<ul>
+	<li>Quando l'utente clicca su "Go!" o preme "Invio" � necessario mettere in moto la logica dati per effettuare una nuova ricerca.</li>
+	<li>Quando la ricerca ottiene dei risultati dal server � necessario istruire la sub-view TweetsView affinch� visualizzi i dati.</li>
+</ul>
+In linea di massima vale il principio: "Ad azione corrisponde reazione".