1.33.0 release

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 1.33.0 (06/23/2016)
+
+## Features
+
+ - JavaScript API for hiding/showing Widgets: Added API for changing the visibility of Widgets at runtime. Changes to Widget visibility is remembered across sessions by the user's browser.
+
 # 1.32.0 (06/09/2016)
 
 ## Features

cyclotron-site/app/partials/dashboard.jade

@@ -12,6 +12,7 @@ div.dashboard
         i.fa.fa-chevron-right(ng-click='moveForward()', ng-class='{ disabled: !canMoveForward() }', title='Go to the next page')
 
     .dashboard-pages
-        div(dashboard-page, dashboard='dashboard', page='page', page-number='{{ currentPageIndex }}', 
+        div(dashboard-page, dashboard='dashboard', 
+            page='page', page-number='{{ currentPageIndex }}', page-overrides='dashboardOverrides.pages[currentPageIndex]',
             ng-repeat='page in currentPage')
 

cyclotron-site/app/partials/help/javascriptApi.jade

@@ -0,0 +1,117 @@
+h3 JavaScript API
+
+p.
+    Cyclotron provides a JavaScript API that Dashboards can leverage. They make it easier to extend Cyclotron with custom functionality and add additional interactivity to a Dashboard. Basically, it exposes various actions in the Dashboard (e.g. execute a Data Source, show/hide a Widget), or to provide information about the Dashboard.
+
+p
+    | In addition to the Cyclotron API, there are a handful of 3rd party JavaScript libraries which are bundled with Cyclotron. Theese are the libraries that Cyclotron itself is built on, making them available for use by Dashboards as well. More information about these libraries can be found at 
+    a(ng-click='findItem("3rd Party Libraries")', href='?q=3rd Party Libraries') 3rd Party Libraries
+
+h4 Dashboard Information
+
+table
+    tr
+        th Method/Property
+        th Description
+    tr
+        td Cyclotron.version
+        td Property that returns the current version of Cyclotron
+    tr
+        td Cyclotron.dashboard
+        td Property that returns the current Dashboard as an object
+    tr
+        td Cyclotron.dashboardOverrides
+        td Property that returns an object of user-specific overrides for the current Dashboard
+    tr
+        td Cyclotron.dashboardName
+        td Property that returns the name of the current Dashboard
+    tr
+        td Cyclotron.pageName
+        td Property that returns the name of the currently-displayed Page
+    tr
+        td Cyclotron.goToPage(pageNumber)
+        td Navigates to a specific page in the Dashboard (starting with page 1)
+    tr
+        td Cyclotron.getDeeplink()
+        td Returns a deeplink URL to the current Dashboard, including the values of all Parameters
+
+h4 Built-In Parameters
+
+p These Parameters are built-in to every Dashboard, and appear in the URL when set. They don't have to be configured manually in the Parameters section of the Dashboard, but they can be added there in order to change the default value.
+
+table
+    tr
+        th Parameter
+        th Description
+    tr
+        td Cyclotron.parameters.page
+        td Set to the current page number (as an integer)
+    tr
+        td Cyclotron.parameters.rev
+        td Set to the Dashboard's revision number (as a string); this will be undefined when viewing the latest revision
+    tr
+        td Cyclotron.parameters.live
+        td If true, causes the Dashboard to check for new Revisions more frequently. This Parameter can be set via URL only, when the Dashboard is loaded.
+    tr
+        td Cyclotron.parameters.autoRotate
+        td True/false value that enables/disables rotation in the Dashboard, overriding the Dashboard's setting. This Parameter can be set via URL only, when the Dashboard is loaded.
+
+h4 Data Sources
+
+p These functions allow interaction with the Data Sources in the Dashboard. The 
+    em  Cyclotron.dataSource
+    |  object contains each Data Source name as a key, with an object of functions as the value.
+
+table
+    tr
+        th Method
+        th Description
+    tr
+        td Cyclotron.dataSources['dataSourceName'].execute([showSpinners])
+        td Manually executes a Data Source.  If showSpinners is true, it will triggers Widgets to show a loading spinner while the Data Source is executing
+    tr
+        td Cyclotron.dataSources['dataSourceName'].getPromise()
+        td Returns the latest execution promise (may be completed).  The returned promise has two functions, promise.then(function) and promise.catch(function).  If the Data Source has already completed, then() will execute the given function immediately. This function returns an object of resultsets, each containing columns (optional) and data.
+    tr
+        td Cyclotron.dataSources['dataSourceName'].getCachedDataSet([resultSetName])
+        td Returns the latest resultset for the Data Source if it exists, else null. If no resultSet argument is provided, the default resultset name of '0' will be used. This function returns the result set data directly.
+    tr
+        td Cyclotron.dataSources['dataSourceName'].getData()
+        td Deprecated; do not use
+    tr
+        td Cyclotron.dataSources['dataSourceName'].init()
+        td Initializes the Data Source and starts automatic refresh if configured. This method is used internally by Widgets; execute() is probably better suited to custom JavaScript scripting.
+
+h4 Widgets
+
+p These functions apply overrides to Widgets in the Dashboard. In order to use these functions, the Widget needs to have the
+    em  name
+    |  property configured; the 
+    em  Cyclotron.currentPage.widgets 
+    |  object contains each Widget name as a key, with an object of functions as the value.
+
+table
+    tr
+        th Method
+        th Description
+    tr
+        td Cyclotron.currentPage.widgets['widgetName'].show()
+        td Shows a Widget; overrides the Widget's 
+            em hidden
+            |  property
+    tr
+        td Cyclotron.currentPage.widgets['widgetName'].hide()
+        td Hides a Widget; overrides the Widget's 
+            em hidden
+            |  property
+    tr
+        td Cyclotron.currentPage.widgets['widgetName'].toggleVisibility()
+        td Toggles the visibility of a Widget; overrides the Widget's 
+            em hidden
+            |  property
+
+h4 CyclotronData
+
+p CyclotronData has a JavaScript API for reading/writing data. This is documented separately on the 
+    a(ng-click='findItem("CyclotronData")', href='?q=CyclotronData')  CyclotronData
+    |  page.

cyclotron-site/app/partials/widgetError.jade

@@ -1,8 +1,8 @@
 
 .widget-error-container
-    .fa.fa-exclamation(title='{{ dataSourceErrorMessage }}')
+    .fa.fa-exclamation(title='{{ errorMessage }}')
     .widget-reload(ng-click='reload()')
         i.fa.fa-refresh 
         |  Reload
-    .widget-error-message(title='{{ dataSourceErrorMessage }}')
+    .widget-error-message(title='{{ errorMessage }}')
         | {{ shortErrorMessage }}

cyclotron-site/app/scripts/common/app.coffee

@@ -59,6 +59,9 @@ cyclotronServices = angular.module 'cyclotronApp.services', ['ngResource']
 
 cyclotronApp.config ($stateProvider, $urlRouterProvider, $locationProvider, $controllerProvider, $compileProvider, $provide, uiSelectConfig) ->
 
+    # Improve performance
+    $compileProvider.debugInfoEnabled false
+
     uiSelectConfig.theme = 'select2'
 
     # Save some providers for later

cyclotron-site/app/scripts/common/services/services.commonConfigService.coffee

@@ -26,7 +26,7 @@ cyclotronServices.factory 'commonConfigService', ->
 
     exports = {
 
-        version: '1.32.0'
+        version: '1.33.0'
 
         logging: 
             enableDebug: false
@@ -1088,6 +1088,11 @@ cyclotronServices.factory 'commonConfigService', ->
                         path: '/partials/help/examples.html' 
                         tags: ['examples', 'cyclotron-examples']
                     }
+                    {
+                        name: 'Browser Compatibility'
+                        path: '/partials/help/browserCompat.html' 
+                        tags: ['browser', 'compatibility', 'firefox', 'chrome', 'internet explorer', 'ie', 'safari', 'browsercheck']
+                    }
                     {
                         name: 'Permissions'
                         path: '/partials/help/permissions.html' 
@@ -1098,16 +1103,16 @@ cyclotronServices.factory 'commonConfigService', ->
                         path: '/partials/help/encryptedStrings.html' 
                         tags: ['encryption', 'encrypted', '!{', 'decrypt', 'encrypt']
                     }
+                    {
+                        name: 'JavaScript API'
+                        path: '/partials/help/javascriptApi.html' 
+                        tags: ['javascript', 'api', 'scripting']
+                    }
                     {
                         name: 'CyclotronData'
                         path: '/partials/help/cyclotrondata.html' 
                         tags: ['cyclotrondata', 'data', 'storage', 'bucket', 'api']
                     }
-                    {
-                        name: 'Browser Compatibility'
-                        path: '/partials/help/browserCompat.html' 
-                        tags: ['browser', 'compatibility', 'firefox', 'chrome', 'internet explorer', 'ie', 'safari', 'browsercheck']
-                    }
                     {
                         name: '3rd Party Libraries'
                         path: '/partials/help/3rdparty.html' 

cyclotron-site/app/scripts/dashboards/controller.dashboard.coffee

@@ -17,7 +17,7 @@
 #
 # Home controller.
 #
-cyclotronApp.controller 'DashboardController', ($scope, $stateParams, $location, $timeout, $window, $q, $uibModal, analyticsService, configService, cyclotronDataService, dashboardService, dataService, loadService, logService, parameterService, userService) ->
+cyclotronApp.controller 'DashboardController', ($scope, $stateParams, $localForage, $location, $timeout, $window, $q, $uibModal, analyticsService, configService, cyclotronDataService, dashboardService, dataService, loadService, logService, parameterService, userService) ->
 
     preloadTimer = null
     rotateTimer = null
@@ -101,6 +101,9 @@ cyclotronApp.controller 'DashboardController', ($scope, $stateParams, $location,
 
         $scope.updateUrl()
 
+        $window.Cyclotron.currentPage =
+            widgets: {}
+
         # Track analytics
         analyticsService.recordPageView $scope.dashboardWrapper, $scope.currentPageIndex, $scope.firstLoad
 
@@ -285,18 +288,32 @@ cyclotronApp.controller 'DashboardController', ($scope, $stateParams, $location,
             dashboardService.setDashboardDefaults(dashboard)
             $scope.dashboard = dashboard
 
+            # Initialize dashboard overrides
+            $scope.dashboardOverrides.pages ?= []
+            _.each dashboard.pages, (page, index) ->
+                if !$scope.dashboardOverrides.pages[index]?
+                    $scope.dashboardOverrides.pages.push { widgets: [] }
+                $scope.dashboardOverrides.pages[index].widgets ?= []
+                _.each page.widgets, (widget, widgetIndex) ->
+                    if !$scope.dashboardOverrides.pages[index].widgets[widgetIndex]?
+                        $scope.dashboardOverrides.pages[index].widgets.push {}
+
             # Optionally disable analytics
             if dashboard.disableAnalytics == true
                 configService.enableAnalytics = false
 
             dependenciesLoaded = -> 
-                # Update current page if needed
-                if $scope.currentPage?
+                # Check if a new revision of the Dashboard has been loaded
+                if $scope.latestRevision and $scope.latestRevision < $scope.dashboardWrapper.rev
+                    # Update current page if needed
                     originalPage = $scope.currentPage[$scope.currentPage.length-1]
                     newPage = $scope.dashboard.pages[$scope.currentPageIndex]
                     if !angular.equals(originalPage, newPage)
+                        logService.debug 'Replacing the current page with a new revision'
                         $scope.currentPage[$scope.currentPage.length-1] = newPage
 
+                $scope.latestRevision = $scope.dashboardWrapper.rev
+
                 # Resolve promise
                 deferred.resolve()
 
@@ -389,7 +406,7 @@ cyclotronApp.controller 'DashboardController', ($scope, $stateParams, $location,
         _.each themes, (theme) ->
             loadService.loadCssUrl('/css/app.themes.' + theme + '.css', true)
 
-        # Intialize parameters
+        # Initialize parameters
         parameterService.initializeParameters($scope.dashboard).then ->
 
             # Watch querystring for changes
@@ -449,7 +466,14 @@ cyclotronApp.controller 'DashboardController', ($scope, $stateParams, $location,
             .search $scope.deeplinkOptions
             .toString()
 
-    $scope.loadDashboard().then $scope.initialLoad
+    # Load Overrides, then the dashboard
+    $localForage.bind($scope, {
+        key: 'dashboardOverrides'
+        defaultValue: { pages: [] }
+    }).then ->
+        $window.Cyclotron.dashboardOverrides = $scope.dashboardOverrides
+        logService.debug 'Dashboard Overrides: ' + JSON.stringify($scope.dashboardOverrides)
+        $scope.loadDashboard().then $scope.initialLoad
 
     #
     # Hot Key Bindings

cyclotron-site/app/scripts/dashboards/directives/directives.dashboardPage.coffee

@@ -1,5 +1,5 @@
 ###
-# Copyright (c) 2013-2015 the original author or authors.
+# Copyright (c) 2013-2016 the original author or authors.
 #
 # Licensed under the MIT License (the "License");
 # you may not use this file except in compliance with the License. 
@@ -14,18 +14,31 @@
 # language governing permissions and limitations under the License. 
 ###
 
+#
+# Top-level Page directive
+# 
+# Renders a series of Widgets and manages page-level interactivity.  Expects the following
+# scope variables:
+#     page: Page to render
+#     pageOverrides: Overrides for the current page
+#     pageNumber: Index of the Page in the Dashboard (zero-indexed)
+#     dashboard: Entire Dashboard object
+#
 cyclotronDirectives.directive 'dashboardPage', ($compile, $window, $timeout, configService, layoutService, logService) ->
     {
         replace: true
         restrict: 'A'
 
         scope:
             page: '='
+            pageOverrides: '='
+            pageNumber: '@'
             dashboard: '='
 
         template: '<div class="dashboard-page dashboard-{{page.theme}} {{page.style}}">' +
             '<div class="dashboard-page-inner">' +
-                '<div widget="widget" class="dashboard-widgetwrapper dashboard-{{widget.theme}}" ng-repeat="widget in page.widgets"></div>' + 
+                '<div class="dashboard-widgetwrapper dashboard-{{widget.theme}}" ng-repeat="widget in page.widgets"' +
+                ' widget="widget" page-overrides="pageOverrides" widget-index="$index" layout="layout" dashboard="dashboard" post-layout="postLayout()"></div>' + 
             '</div></div>'
 
         link: (scope, element, attrs) ->
@@ -107,21 +120,18 @@ cyclotronDirectives.directive 'dashboardPage', ($compile, $window, $timeout, con
                     scope.postLayout = _.after newValue.widgets.length, ->
                         if (newValue.enableMasonry != false)
                             masonry(element, scope.layout)
+                        return
 
-                    newLayout = layoutService.getLayout(newValue, $($window).width(), $($window).height())
-
-                    # Optional persistent widget area of layout
-                    newLayout.widget = scope.layout?.widget || {}
-                    scope.layout = newLayout
+                    scope.layout = layoutService.getLayout(newValue, $($window).width(), $($window).height())
 
                     # Set page margin if defined
                     if !_.isNullOrUndefined(scope.layout.margin)
-                        $element.css('padding', scope.layout.margin + 'px')
+                        $element.css 'padding', scope.layout.margin + 'px'
 
-                    $dashboardPageInner.css({ 
+                    $dashboardPageInner.css { 
                         marginRight: '-' + scope.layout.gutter + 'px'
                         marginBottom: '-' + scope.layout.gutter + 'px'
-                    })
+                    }
 
                     # Enable/disable scrolling of the dashboard page
                     if !scope.layout.scrolling
@@ -172,4 +182,5 @@ cyclotronDirectives.directive 'dashboardPage', ($compile, $window, $timeout, con
                     $dashboardPageInner.masonry('destroy')
 
             return
+
     }

cyclotron-site/app/scripts/dashboards/directives/directives.dashboardWidget.coffee

@@ -24,9 +24,6 @@ cyclotronDirectives.directive 'dashboardWidget', (layoutService) ->
 
             scope.$watch 'widget', (widget) ->
 
-                # Ignore the widget if hidden is set
-                return if widget.hidden == true
-
                 # Wire-up fullscreen button if available
                 if widget.allowFullscreen
                     $parent.find('.widget-fullscreen').click ->