1 // ==========================================================================
  2 // Project:   The M-Project - Mobile HTML5 Application Framework
  3 // Copyright: �2010 M-Way Solutions GmbH. All rights reserved.
  4 // Creator:   Dominik
  5 // Date:      02.11.2010
  6 // License:   Dual licensed under the MIT or GPL Version 2 licenses.
  7 //            http://github.com/mwaylabs/The-M-Project/blob/master/MIT-LICENSE
  8 //            http://github.com/mwaylabs/The-M-Project/blob/master/GPL-LICENSE
  9 // ==========================================================================
 10 
 11 m_require('core/foundation/view.js');
 12 
 13 
 14 /**
 15  * @class
 16  *
 17  * The ViewManager manages and knows all views that are used in the application. The ViewManager is part of M.Application.
 18  *
 19  * It is used by various other components (e.g. controller: switchToPage) to connect from javascript objects to their
 20  * HTML representation. 
 21  *
 22  * @extends M.Object
 23  */
 24 M.ViewManager = M.Object.extend(
 25 /** @scope M.ViewManager.prototype */ {
 26 
 27     /**
 28      * The type of this object.
 29      *
 30      * @type String
 31      */
 32     type: 'M.ViewManager',
 33 
 34     /**
 35      * The nextId delivered to a view (used as html id attribute value) with prefix m_.
 36      * Initial state is 0, will be incremeneted by 1 on each call.
 37      *
 38      * @type Number
 39      */
 40     nextId: 0,
 41 
 42     /**
 43      * Prefix for Id.
 44      *
 45      * @type String
 46      */
 47     idPrefix: 'm_',
 48 
 49     /**
 50      * Array containing all views used in the application.
 51      *
 52      * @type Object
 53      */
 54     viewList: [],
 55 
 56     /**
 57      * A reference to the currently displayed page.
 58      *
 59      * @type Object
 60      */
 61     currentPage: null,
 62 
 63     /**
 64      * A reference to the latest found view which is necessary for the findView() method.
 65      *
 66      * @type Object
 67      */
 68     foundView: null,
 69 
 70     /**
 71      * Returns the next Id build from nextId property incremented by 1 and the prefix.
 72      * The id is used as the value for the HTML attribute id.
 73      * @returns {String} The next id for a view, e.g. 'm_123' (if last id was 'm_122').
 74      */
 75     getNextId: function() {
 76         this.nextId = this.nextId + 1;
 77         return this.idPrefix + this.nextId;
 78     },
 79 
 80     /**
 81      * Adds the view to the viewlist array.
 82      *
 83      * @param {Object} view The view to be registered in the viewlist.
 84      */
 85     register: function(view) {
 86         this.viewList.push(view);
 87     },
 88 
 89     /**
 90      * Returns the view object from the view list array identified
 91      * by the value of its id attribute.
 92      *
 93      * @param {String} id
 94      * @returns {Object} The view object from the view list identified by id.
 95      */
 96     getViewById: function(id) {
 97         var view = _.detect(this.viewList, function(v) {
 98             return v.id === id;
 99         });
100         return view;
101     },
102 
103     /**
104      * Returns the id for a given view.
105      *
106      * @param {Object} view. The view for which the id value is wanted.
107      * @returns {String} The id of a view object.
108      */
109     getIdByView: function(view) {
110         return view.id;
111     },
112 
113     /**
114      * Returns the view object from the view list array identified by the view's
115      * name and its page. If there are multiple views with the same name on the
116      * same page, the first result is returned.
117      *
118      * Note: Try to use unique names for your views within the same page!
119      *
120      * @param {String, Object} parentView. The name of the parent view or the parent view itself.
121      * @param {String} targetView. The name of the view to be returned.
122      * @returns {Object} The view object from the view list identified by the view's name and the page where it's on.
123      */
124     getView: function(parentView, targetView) {
125         if(typeof(parentView) !== 'object') {
126             parentView = M.Application.pages[parentView];  
127         }
128         var view = null;
129 
130         /* reset previously found views before searching again */
131         this.foundView = null;
132         if(parentView) {
133             view = this.findView(parentView, targetView);
134         }
135 
136         if(!view) {
137             M.Logger.log('view \'' + targetView + '\' not found on page \'' + targetView + '\'', M.WARN);
138         }
139         return view;
140     },
141 
142     /**
143      * Searches for a certain view within a given parent view. If it is found, the result
144      * is returned. Otherwise the search algorithm checks for possible child views and then
145      * recursively searches within these child views for the target view.
146      *
147      * This method is mainly used by the getView() method to find a view within a page.
148      *
149      * @param {Object} parentView. The parent view to search in.
150      * @param {String} targetView. The name of the view to be returned.
151      * @returns {Object} The last found view.
152      */
153     findView: function(parentView, targetView) {
154         if(parentView.childViews) {
155             var childViews = $.trim(parentView.childViews).split(' ');
156             for(var i in childViews) {
157                 if(targetView === childViews[i]) {
158                     this.foundView =  parentView[targetView];
159                 } else {
160                     this.findView(parentView[childViews[i]], targetView);
161                 }
162             }
163         }
164         return this.foundView;
165     },
166 
167     /**
168      * Returns the page object from the view list array identified by its name. If
169      * there are multiple pages with the same name, the first result is returned.
170      *
171      * Note: Try to use unique names for your pages!
172      *
173      * @param {String} pageName. The name of the page to be returned.
174      * @returns {Object} M.Page object identified by its name.
175      */
176     getPage: function(pageName) {
177         var page = M.Application.pages[pageName];
178 
179         if(!page) {
180             M.Logger.log('page \'' + pageName + '\' not found', M.WARN);
181         }
182         return page;
183     },
184 
185     /**
186      * Returns the currently displayed page.
187      * @returns {Object} The currently displayed page.
188      */
189     getCurrentPage: function() {
190         return this.currentPage;
191     },
192 
193     /**
194      * Sets the currently displayed page.
195      * @param {Object} page The page to be set as current page.
196      */
197     setCurrentPage: function(page) {
198         this.currentPage = page;
199     },
200 
201     /**
202      * Debug method to print out all content from the viewlist array to the console.
203      * @private
204      */
205     dumpViewList: function() {
206       _.each(this.viewList, function(view){
207         console.log(view.id + ': '+ view.type);
208       });  
209     }
210 
211 });