externalize application name and other theming

Fixes #353

Author: starpit

app/.gitignore

@@ -3,4 +3,6 @@
 # sometimes, `@openwhisk/composer` appears at the top level `app/plugins/node_modules/@openwhisk/composer`,
 # and other times it appears in `app/plugins/node_modules/wskng-composer-plugins/node_modules/@openwhisk/composer`
 package-lock.json
-plugins/package-lock.json
+plugins/package-lock.json
+
+build

app/README.md

@@ -0,0 +1,19 @@
+# Cloud Shell Developer Help
+
+This document is intended to assist developers of the Shell.
+
+## Theming and Customization
+
+You may choose to customize the branding and look of the Shell. A
+custom theme starts with a settings file. An example is provided in
+`config/envs/ibm.json`. This file indicates:
+
+- The name of your product, via the `productName` field. The header of the Shell breaks this down into a `companyName`, a `productSubName`, and a name for the tool itself, `shellName`. You will probably choose to define productName as the concatenation of these three sub-fields, but are free to choose otherwise.
+
+- The application icon: `appIcon`
+
+- A large format icon that will appear in the About window: `largeIcon`
+
+- The css theme file to use, `cssTheme`. Define this as the name of a file in `content/css/themes`, but specify only the base name, not the full path to this CSS theme file.
+
+- Optionally, you may set the User-Agent header that will be communicated to the OpenWhisk backend: `userAgent`

app/bin/build.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+/*
+ * Copyright 2018 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const debug = require('debug')('build'),
+      color = require('colors'),
+      path = require('path'),
+      fs = require('fs'),
+      { parseOptions } = require(path.join(__dirname, '../config/options')),
+      { parseConfig } = require(path.join(__dirname, '../config/config'))
+
+/**
+ * Tell the user where we're at
+ *
+ */
+const task = taskName => console.log('task: '.dim + taskName)
+
+/**
+ * Read in index.html
+ *
+ */
+const readIndex = options => new Promise((resolve, reject) => {
+    const { templateDir } = options
+
+    debug('read template', templateDir)
+    task('read index.html template')
+
+    fs.readFile(path.join(templateDir, 'index.html'), (err, data) => {
+        if (err) {
+            reject(err)
+        } else {
+            resolve(data.toString())
+        }
+    })
+})
+
+/**
+ * Evaluate macros in the given string, using the given setting of configurations
+ *
+ */
+const evaluateMacros = settings => str => {
+    debug('settings', settings)
+    task('evaluate macros')
+
+    for (let key in settings) {
+        str = str.replace(new RegExp('\\$\\{' + key + '\\}', 'g'), settings[key])
+    }
+
+    return str
+}
+
+/**
+ * Ensure that the buildDir exists
+ *
+ */
+const makeBuildDir = options => new Promise((resolve, reject) => {
+    const { buildDir } = options
+
+    fs.mkdir(buildDir, err => {
+        if (err && err.code !== 'EEXIST') {
+            reject(err)
+        } else {
+            resolve()
+        }
+    })
+})
+
+/**
+ * Write the updated index.html
+ *
+ */
+const writeIndex = options => str => new Promise((resolve, reject) => {
+    const { appName, buildDir } = options
+
+    task('write index.html')
+
+    fs.writeFile(path.join(buildDir, 'index.html'), str, err => {
+        if (err) {
+            reject(err)
+        } else {
+            resolve()
+        }
+    })
+})
+
+/**
+ * Stash the chosen configuration settings to the buildDir, and update
+ * the app/package.json so that the productName field reflects the
+ * chosen setting
+ *
+ */
+const writeConfig = (options, settings) => new Promise((resolve, reject) => {
+    const { buildDir } = options
+
+    task('write config')
+
+    fs.writeFile(path.join(buildDir, 'config.json'), JSON.stringify(settings, undefined, 4), err => {
+        if (err) {
+            reject(err)
+        } else {
+            task('write package.json')
+
+            const topLevel = require(path.join(__dirname, '../package.json')),
+                  packageJson = Object.assign({}, topLevel, settings)
+
+            fs.writeFile(path.join(buildDir, 'package.json'), JSON.stringify(packageJson, undefined, 4), err => {
+                if (err) {
+                    reject(err)
+                } else {
+                    resolve()
+                }
+            })
+        }
+    })
+})
+
+/**
+ * Do a build
+ *
+ */
+const doBuild = (options, settings) => () => Promise.all([ writeConfig(options, settings),
+                                                           readIndex(options)
+                                                           .then(evaluateMacros(settings))
+                                                           .then(writeIndex(options))
+                                                         ])
+
+/**
+ * Either project out a field of the configuration settings, or do a build
+ *
+ */
+const doWork = (options, settings) => {
+    if (options.get) {
+        if (settings[options.get]) {
+            // we were asked only to respond with a projection of the config settings
+            debug('projecting', options.get, settings[options.get])
+            return Promise.resolve(settings[options.get])
+        }
+
+        return Promise.reject('error: '.red + 'requested field ' + options.get.blue + ' not found in config file')
+    }
+
+    return makeBuildDir(options)
+        .then(doBuild(options, settings))
+        .then(() => 'ok:'.green + ' build successful')
+}
+
+/**
+ * Build index.html
+ *
+ */
+const buildIndex = parseOptions()                          // read options
+      .then(options => parseConfig(options)                // read chosen configuration settings
+            .then(settings => doWork(options, settings)))  // either project out a setting, or do a build
+
+      .then(console.log)
+      .catch(err => {
+          console.error(err)
+          process.exit(1)
+      })

app/bin/seticon.sh

@@ -19,11 +19,16 @@
 # TODO this only handles MacOS right now
 
 #ICON=../assets/icons/png/OpenWhisk-512x512.png
-ICON=../assets/icons/png/blue-dolphin-transparent.png
+ICON=`cat ./build/config.json | jq --raw-output .appIcon`
 
-APPNAME="IBM Cloud Functions Shell"
+APPNAME=`cat ./build/config.json | jq --raw-output .productName`
 
-if [ ! -x ./node_modules/.bin/fileicon ]; then exit; fi
+echo "Using appName=${APPNAME} and appIcon=${ICON}"
+
+if [ ! -x ./node_modules/.bin/fileicon ]; then
+    echo "Not setting icon, as fileicon npm not installed"
+    exit;
+fi
 
 if [ $? == 0 ]; then
     ./node_modules/.bin/fileicon set ./node_modules/electron/dist/Electron.app/ $ICON >& /dev/null

app/config/config.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2018 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const debug = require('debug')('config parser'),
+      path = require('path')
+
+/**
+ * Default options
+ *
+ */
+const defaultOptions = () => {
+    debug('using default options')
+
+    const { parseOptions } = require('./options')
+    return parseOptions()
+}
+
+/**
+ * Parse the variable mapping file
+ *
+ */
+exports.parseConfig = (options=defaultOptions()) => new Promise((resolve, reject) => {
+    if (!options.config) {
+        reject('Please specify a config file, either via a CONFIG env var or a --config command line option')
+    } else {
+        resolve(require(path.join(__dirname, './envs/', options.config)))
+    }
+})

app/config/envs/ibm.json

@@ -0,0 +1,10 @@
+{
+    "productName": "IBM Cloud Shell",
+    "companyName": "IBM",
+    "productSubName": "Cloud",
+    "shellName": "Shell",
+    "userAgent": "IBM Cloud Functions Shell",
+    "cssTheme": "ibm.css",
+    "appIcon": "../assets/icons/png/blue-dolphin-transparent.png",
+    "largeIcon": "content/icons/svg/blue-dolphin.svg"
+}

app/config/options.js

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2018 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const debug = require('debug')('options parser'),
+      minimist = require('yargs-parser'),
+      path = require('path')
+
+/**
+ * Remove undefined mappings from the given map
+ *
+ */
+const nix = map => {
+    const nixed = {}
+
+    for (let key in map) {
+        if (map[key] !== undefined) {
+            nixed[key] = map[key]
+        }
+    }
+
+    return nixed
+}
+
+/**
+ * Parse options
+ *
+ */
+exports.parseOptions = () => new Promise((resolve, reject) => {
+    debug('parsing options')
+
+    // options from environment variables
+    const envOptions = nix({
+        config: process.env.CONFIG
+    })
+
+    // default value assignments for options
+    const defaultOptions = {
+        config: 'ibm.json',
+        templateDir: path.join(__dirname, '../templates'),
+        buildDir: path.join(__dirname, '../build')
+    }
+
+    // options from command line flags
+    const cliOptions = minimist(process.argv.slice(2))
+
+    // union the three
+    const options = Object.assign(defaultOptions, envOptions, cliOptions)
+    debug('options', options)
+
+    resolve(options)
+})

app/content/css/themes/ibm.css

@@ -50,6 +50,7 @@ body a:hover:not(.plain-anchor) {
 .header {
     background: var(--color-stripe-01);
     color: var(--color-ui-01);
+    border-bottom-color: var(--color-ui-05);
     outline-color: var(--color-ui-05); /* outline, rather than border-bottom-color, to allow minimized sidecar to stay on top */
     box-shadow: 0 1px 2px rgba(0,0,0,0.1);;
 }

app/content/css/ui.css

@@ -45,9 +45,13 @@ body a:hover:not(.plain-anchor) {
     padding-right: 3em;
     font-weight: 300;
     font-size: 1rem;
-    outline: 1px solid; /* outline rather than border-bottom, to allow minimized sidecar to stay on top */
+    border-bottom: 1px solid; /* outline rather than border-bottom, to allow minimized sidecar to stay on top */
     -webkit-font-smoothing: antialiased;  /* chrome, you suck */
 }
+body.sidecar-is-minimized .header {
+    outline: 1px solid; /* outline rather than border-bottom, to allow minimized sidecar to stay on top */
+    border-bottom: none;
+}
 .header .deemphasize {
     font-size: 55%;
     letter-spacing: 1px;
@@ -1289,11 +1293,18 @@ body.os-darwin:not(.fullscreen) .header {
 body .header .application-icon {
     position: absolute;
     top: 0.4em;
-    right: 0; /*0.5em;*/
+    right: 0.5em;
     width: 1.8em;
     height: 1.8em;
     margin: 0;
     z-index: 20;
+    transition: all 150ms ease-in-out;
+}
+body.sidecar-is-minimized .header .application-icon {
+    /* scoot the icon to be flush right when the sidecar is minimized, so
+   that the icon will be horizontally centered on the vertical stripe
+   that represents the minimized sidecar */
+    right: 0;
 }
 body.subwindow.still-loading .header .application-icon {
     transition: all 150ms ease-in-out;