      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 });