Configurable Layout/UI Refactor

Gruntfile.js

@@ -76,7 +76,7 @@ module.exports = function (grunt) {
         stylus: {
             minerva: {
                 files: [{
-                    src: ['<%= plugin.minerva.external %>/stylesheets/**/*.styl'],
+                    src: ['<%= plugin.minerva.external %>/stylesheets/main.styl'],
                     dest: '<%= plugin.minerva.static %>/minerva.min.css'
                 }]
             }
@@ -99,6 +99,7 @@ module.exports = function (grunt) {
                             '<%= plugin.minerva.source %>/models/SourceModel.js',
                             '<%= plugin.minerva.source %>/models/**/*.js',
                             '<%= plugin.minerva.source %>/collections/**/*.js',
+                            '<%= plugin.minerva.source %>/views/body/Panel.js',
                             '<%= plugin.minerva.source %>/views/**/*.js'
                         ],
                         dest: '<%= plugin.minerva.static %>/minerva.min.js'
@@ -269,7 +270,6 @@ module.exports = function (grunt) {
             '/clients/web/static/built/libs.min.js',
             '/' + staticDir + '/geo.ext.min.js',
             // '/' + rootStaticDir + '/libs.min.js', // libs included in jade template
-            '/' + staticDir + '/jquery.gridster.js',
             '/' + staticDir + '/jquery-ui.min.js',
             '/' + staticDir + '/geo.min.js',
             '/' + rootStaticDir + '/app.min.js'
@@ -306,7 +306,6 @@ module.exports = function (grunt) {
             '/' + rootStaticLibDir + '/bootstrap/css/bootstrap.min.css',
             '/' + rootStaticLibDir + '/fontello/css/fontello.css',
             '/' + rootStaticLibDir + '/fontello/css/animation.css',
-            '/' + staticDir + '/jquery.gridster.min.css',
             '/' + staticDir + '/jquery-ui.min.css',
             '/' + rootStaticDir + '/app.min.css'
         ];

docs/developer-documentation.rst

@@ -6,5 +6,6 @@ Developer Documentation
 
    installation
    api-documentation
+   extending-minerva
    creating-a-source
 

docs/extending-minerva.rst

@@ -0,0 +1,67 @@
+Extending Minerva
+=================
+
+Creating a Minerva Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Minerva plugins are **identical** to Girder plugins with the exception that they have a hard dependency on Minerva. This ensures that Minerva will be loaded before your plugin is.
+
+Minerva utilizes the Girder plugin system, so it will be worthwhile to familiarize yourself with their section on `Plugin Development <http://girder.readthedocs.org/en/latest/plugin-development.html>`_.
+
+
+Below is an example configuration for a Minerva plugin, note the dependency on Minerva:
+
+.. code-block:: python
+
+   {
+       "name": "My Minerva Plugin",
+       "dependencies": ["minerva"]
+   }
+
+Your new Minerva plugin should provide no new functionality at this point, and `can be enabled through the administration console <http://girder.readthedocs.org/en/latest/installation.html#initial-setup>`_.
+
+
+Extending the look and feel of Minerva
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While Minerva plugins follow the guidelines provided by Girder's client side, there are additional concerns when writing for Minerva.
+
+.. note:: Girder has documentation on `extending the client-side application <http://girder.readthedocs.org/en/latest/plugin-development.html#extending-the-client-side-application>`_ which also applies to Minerva.
+
+Minerva Panel Views
+-------------------
+Minerva renders panels in a particular way, as a result there are some guidelines that need be followed when creating your own Panels:
+
+- Panels should never call render within their initialize function
+- Panel views must extend the base Panel view
+- Panel views need to extend their events to take advantage of collapsible, removable, configurable panels
+
+
+Configure Minerva's layout
+--------------------------
+Taking our example plugin from before, we can alter how Minerva displays different panels.
+
+Let's pretend our use case of Minerva deems the Jobs Panel useless, and is more focused on the datasets available. In this case one might want to disable the Jobs Panel entirely, and move the datasets panel to the top.
+
+From your plugin root, create a JavaScript file at ``web_client/js/some-file.js`` and add the following code:
+
+.. code-block:: javascript
+
+   girder.events.once('m:pre-render-panel-groups', function (sessionView) {
+       var leftPanelGroup = sessionView.getPanelGroup('m-left-panel-group');
+
+       // Disable/remove the jobs panel
+       sessionView.disablePanel('m-jobs-panel');
+
+       // Move the 'Available Datasets' panel to the top
+       leftPanelGroup.panelViews.sort(function (a, b) {
+           if (a.id === 'm-data-panel') {
+               return -1;
+           } else if (b.id === 'm-data-panel') {
+               return 1;
+           } else {
+               return 0;
+           }
+       });
+   });
+
+Above we utilize the ``m:pre-render-panel-groups`` event to hook into Minerva before any panels are actually rendered, this gives full control over what the final layout looks like.

plugin_tests/minervaSpec.js

@@ -11,8 +11,8 @@ describe('a test for the minerva plugin application', function () {
 
     it('displays the minerva app', function () {
         waitsFor(function () {
-            return $('a.m-maps-link:visible').length === 1;
-        }, 'the maps button to be visible');
+            return $('.m-sessions-search-container:visible').length === 1;
+        }, 'the main panel to be visible');
     });
 
 });

server/minerva.mako

@@ -18,14 +18,15 @@
           href="${staticRoot}/built/plugins/minerva/jquery-ui.min.css">
     <link rel="stylesheet"
           href="${staticRoot}/built/app.min.css">
+    <link rel="stylesheet"
+          href="${staticRoot}/built/plugins/minerva/minerva.min.css">
     % for plugin in pluginCss:
         % if plugin != 'minerva':
             <link rel="stylesheet"
             href="${staticRoot}/built/plugins/${plugin}/plugin.min.css">
         % endif
     % endfor
-    <link rel="stylesheet"
-          href="${staticRoot}/built/plugins/minerva/minerva.min.css">
+
     <link rel="icon"
           type="image/png"
           href="${staticRoot}/img/Girder_Favicon.png">

server/rest/geocode.py

@@ -14,7 +14,6 @@
 
 
 class Geonames(Resource):
-
     """API Endpoint for managing Geonames database."""
 
     _geonames_folder = None

web_external/js/models/SessionModel.js

@@ -25,6 +25,18 @@ minerva.models.SessionModel = girder.models.ItemModel.extend({
         return _.some(this.sessionJsonContents.features, datasetFinder);
     },
 
+    addLayoutAttributes: function (panelView, attributes) {
+        if (!_.has(this.sessionJsonContents, 'layout')) {
+            this.sessionJsonContents.layout = {};
+        }
+
+        if (!_.has(_.keys(this.sessionJsonContents.layout, panelView))) {
+            this.sessionJsonContents.layout[panelView] = attributes;
+        } else {
+            _.extend(this.sessionJsonContents.layout[panelView], attributes);
+        }
+    },
+
     addDataset: function (dataset) {
         // for now just add them to a list
         // may want to unify caching of geojson file id

web_external/js/views/body/AnalysisPanel.js

@@ -10,7 +10,7 @@
         return name  + 'Widget';
     };
 
-    minerva.views.AnalysisPanel = minerva.View.extend({
+    minerva.views.AnalysisPanel = minerva.views.Panel.extend({
 
         events: {
             'click .m-attempt-analysis': 'attemptAnalysis'
@@ -57,9 +57,10 @@
         },
 
         initialize: function (settings) {
-            this.collection = settings.collection;
-            this.datasetCollection = settings.datasetCollection;
-            this.sourceCollection = settings.sourceCollection;
+            _.extend(this.events, minerva.views.Panel.prototype.events);
+            this.collection = settings.session.analysisCollection;
+            this.datasetCollection = settings.session.datasetsCollection;
+            this.sourceCollection = settings.session.sourceCollection;
             this.listenTo(this.collection, 'g:changed', function () {
                 console.log('AP g:changed');
                 this.render();

web_external/js/views/body/DataPanel.js

@@ -1,4 +1,4 @@
-minerva.views.DataPanel = minerva.View.extend({
+minerva.views.DataPanel = minerva.views.Panel.extend({
     events: {
         'click .add-dataset-to-session': 'addDatasetToSessionEvent',
         'click .delete-dataset': 'deleteDatasetEvent',
@@ -82,7 +82,8 @@ minerva.views.DataPanel = minerva.View.extend({
     },
 
     initialize: function (settings) {
-        this.collection = settings.collection;
+        _.extend(this.events, minerva.views.Panel.prototype.events);
+        this.collection = settings.session.datasetsCollection;
         this.listenTo(this.collection, 'g:changed', function () {
             this.render();
         }, this).listenTo(this.collection, 'change', function () {

web_external/js/views/body/JobsPanel.js

@@ -1,6 +1,7 @@
-minerva.views.JobsPanel = minerva.View.extend({
+minerva.views.JobsPanel = minerva.views.Panel.extend({
 
     initialize: function () {
+        _.extend(this.events, minerva.views.Panel.prototype.events);
         var columnEnum = girder.views.jobs_JobListWidget.prototype.columnEnum;
         var columns = columnEnum.COLUMN_STATUS_ICON |
                       columnEnum.COLUMN_TITLE;

web_external/js/views/body/LayersPanel.js

@@ -1,4 +1,4 @@
-minerva.views.LayersPanel = minerva.View.extend({
+minerva.views.LayersPanel = minerva.views.Panel.extend({
 
     events: {
         'click .m-remove-dataset-from-layer': 'removeDatasetEvent',
@@ -80,8 +80,9 @@ minerva.views.LayersPanel = minerva.View.extend({
     },
 
     initialize: function (settings) {
+        _.extend(this.events, minerva.views.Panel.prototype.events);
         settings = settings || {};
-        this.collection = settings.collection;
+        this.collection = settings.session.datasetsCollection;
         this.layersOrderOptions = [
             {'title': 'move up', 'method': 'moveUp', 'class': 'up'},
             {'title': 'move down', 'method': 'moveDown', 'class': 'down'},

web_external/js/views/body/MapPanel.js

@@ -1,4 +1,4 @@
-minerva.views.MapPanel = minerva.View.extend({
+minerva.views.MapPanel = minerva.views.Panel.extend({
 
     events: {
         'click .m-save-current-baselayer': function () {
@@ -110,6 +110,7 @@ minerva.views.MapPanel = minerva.View.extend({
                         this.featureInfoWidget.callInfo(0, evt.geo);
                     });
                 }
+                this.uiLayer = this.map.createLayer('ui');
                 this.map.draw();
             } else {
                 // Assume the dataset provides a reader, so load the data
@@ -127,7 +128,6 @@ minerva.views.MapPanel = minerva.View.extend({
                     reader.read(dataset.fileData, _.bind(function () {
                         // Add the UI slider back
                         this.uiLayer = this.map.createLayer('ui');
-                        this.uiLayer.createWidget('slider');
                         this.map.draw();
                     }, this));
                 }, this);
@@ -161,7 +161,8 @@ minerva.views.MapPanel = minerva.View.extend({
     },
 
     initialize: function (settings) {
-        this.session = settings.session;
+        _.extend(this.events, minerva.views.Panel.prototype.events);
+        this.session = settings.session.model;
         this.listenTo(this.session, 'm:mapUpdated', function () {
             // TODO for now only dealing with center
             if (this.map) {
@@ -172,7 +173,7 @@ minerva.views.MapPanel = minerva.View.extend({
         this.datasetLayers = {};
         this.legendWidget = {};
 
-        this.collection = settings.collection;
+        this.collection = settings.session.datasetsCollection;
         this.listenTo(this.collection, 'change:displayed', function (dataset) {
             // There is a slight danger of a user trying to add a dataset
             // to a session while the map is not yet created.  If the map isn't
@@ -214,9 +215,10 @@ minerva.views.MapPanel = minerva.View.extend({
                     }
                 })
             });
-            this.map.createLayer(this.session.sessionJsonContents.basemap);
+            this.map.createLayer(this.session.sessionJsonContents.basemap,
+                                 _.has(this.session.sessionJsonContents, 'basemap_args') ?
+                                 this.session.sessionJsonContents.basemap_args : {});
             this.uiLayer = this.map.createLayer('ui');
-            this.uiLayer.createWidget('slider');
             this.mapCreated = true;
             _.each(this.collection.models, function (dataset) {
                 if (dataset.get('displayed')) {

web_external/js/views/body/Panel.js

@@ -0,0 +1,53 @@
+minerva.views.Panel = minerva.View.extend({
+    /**
+     * The panel view isn't meant to be instantiated on it's own.
+     **/
+    events: {
+        'click .icon-cancel': 'removePanel',
+        'show.bs.collapse': 'expandPanel',
+        'hide.bs.collapse': 'collapsePanel'
+    },
+
+    getSessionView: function () {
+        return this.parentView.parentView;
+    },
+
+    getSessionModel: function () {
+        return this.getSessionView().model;
+    },
+
+    /**
+     * Upon confirmation, physically removes the DOM element while
+     * storing the change in the session attributes. This also
+     * enables the save button.
+     **/
+    removePanel: function () {
+        if (confirm('Are you sure you want to remove this panel?')) {
+            this.getSessionView().disablePanel(this.el.id);
+            this.getSessionView()._enableSave();
+            this.remove();
+            minerva.View.prototype.remove.call(this);
+        }
+    },
+
+    /**
+     * Handles the aftermath of a panel being expanded. Meaning it changes the
+     * expand/collapse icon, marks the state of the panel in the session attributes,
+     * and enables the user to save the change.
+     **/
+    expandPanel: function (e) {
+        $(e.currentTarget).find('i.icon-down-open').attr('class', 'icon-up-open');
+        this.getSessionModel().addLayoutAttributes(this.el.id, {
+            collapsed: false
+        });
+        this.getSessionView()._enableSave();
+    },
+
+    collapsePanel: function (e) {
+        $(e.currentTarget).find('i.icon-up-open').attr('class', 'icon-down-open');
+        this.getSessionModel().addLayoutAttributes(this.el.id, {
+            collapsed: true
+        });
+        this.getSessionView()._enableSave();
+    }
+});

web_external/js/views/body/PanelGroup.js

@@ -0,0 +1,21 @@
+minerva.views.PanelGroup = minerva.View.extend({
+    initialize: function (settings) {
+        this.id = settings.id;
+        this.panelViews = settings.panelViews || [];
+    },
+
+    render: function () {
+        // Render each of our panels
+        _.each(this.panelViews, function (panelViewSpec) {
+            var panelView = new panelViewSpec.view({
+                parentView: this,
+                session: this.parentView
+            });
+
+            this.$el.append('<div id="' + panelViewSpec.id + '"></div>');
+            panelView.setElement(this.$('#' + panelViewSpec.id)).render();
+        }, this);
+
+        return this;
+    }
+});