Skip to content

White label App Customization

Jump to bottom
Ken Manheimer edited this page Feb 19, 2015 · 12 revisions

Table of Contents

Introduction

Aspects of both the appearance and behavior of the SpiderOak mobile clients are specific to the commercial or categorical brand for which the client is being built. This document describes how to specify and switch between brand-specific build configurations, according to brand specification packages. There are two main sections:

The Brand specification elements provides a consolidated view of all the brand configuration components.

Operation: Select the current brand using the grunt brand commands

The grunt brand commands set or reveal your repository clone's currently selected brand configuration.

(Relative paths are with respect to the repository root.)

grunt brand
Identify the project's currently selected brand configuration, according to the custom/brand/ symlink, and also the names of the available ones, as found in custom/brands/.
grunt brand <brand name>
Configure the project build environment to use the brand configuration found in the grunt brand:<brand name> subdirectory of custom/brands/. If none have the specified brand name, then an error is emitted, along with a listing of the available brand names.
grunt brand:-
Iff the project build environment has no currently selected brand configuration, then configure it for the default (SpiderOak) brand. Otherwise, if there is a valid, established brand, this informs you of that fact, and what it is. (This is for use at the end of npm install, so that fresh project installation has a valid brand selection, while the existing selection, if any, is not disturbed in ensuing installs.)
grunt brand:!
Reassert the current brand configuration, if any, reconstituting the cordova platforms, etc, to rectify the build environment.
The brand selection is determined according to which of the subdirectories of custom/brands/ symlink custom/brand points.

If the grunt brand:... command causes changes of the brand configuration (or reasserts the current one), then the project manifests for the various platforms are synthesized from templates and interpolation of brand-specific values. Then the cordova platforms are reconstituted, so that the build environment includes those brand-specific values.

Since the grunt brand:<brand name> command looks in custom/brands/ for the specified <brand name> directory, that's the place to put your brand configurations - copy, clone, or symlink directories that contain your various brands' artifacts.

Configuration: Specifying a Brand

Configuration is divided into two phases:

  • Some configuration must be applied to the build environment, requiring reinitialization of the cordova platforms (which the grunt brand:... commands do)
  • The rest of the configuration takes effect within the course of the build process and application run.
What's configured:
  • Graphical appearance - look and feel and brand identifiers
  • Brand-specific operation
Each available brand configuration resides in the subdirectories of the custom/brands/ directory.

Brand specification elements

This chart identifies the various brand configuration elements and purpose.

Build-environment Configuration

Two primary aspects to build branding are applied by scripts/BrandPackage.js according to two files:

  1. the custom/brand_elements.json file format section identifies the systematic adjustments to be made to each of the platform-specific build manifests
  2. custom/brands/*/project_config.json is where the brand-specific values for each brand configuration are put, for plugging in to the platform manifests.
These files are used by the grunt brand:* commands to prepare the project repository to use a particular brand configuration.

custom/brand_elements.json format

Current version

custom/brand_elements.json specifies the synthesis of all the project's platform-specific build manifests. It obtains the brand-specific for the synthesized manifests current brand's project_config.json, described in the next section.

This file will need to be revised only when there are new platform build manifests to add, or the format of existing one has changed.

The json object is an array consisting of objects that each specifies transformations of a structured manifest (or other build-configuration) file. The constituents of each of these objects are:

  • subject: The path of the subject file, relative to the repository root
  • transforms: An array of interpolation specifications to be applied to the subject file. Each interpolation spec is an object with elements:
    • field: The name of the custom/brand/project_config.json field whose value will be interpolated, into...
    • tagPath: The path specifier of the tag to receive the interpolation. The path is interpreted according to the type of the manifest file - an elementtree XPath-style path for XML files, and a PList field name for plist files.
    • attribute: An optional attribute identifier, for XML manifests where the value is to be interpolated into the targeted tag attribute, rather than its text content.

custom/brands/*/project_config.json format

Default version - SpiderOak brand

custom/brands/*/project_config.json identifies the brand-specific project identifiers necessary for the various platform-specific manifests files synthesized in the previous section, custom/brand_elements.json.

An instance of this file is necessary for each brand. It dictates the brand-specific values for production of the various platform manifests, and also identifies the brand-specific plugins that should be situated when the brand is established and removed when switching away from this brand configuration.

If a new platform requires new manifest fields, that will require changing existing project_config.json files. This should be very rare.

Here are the fields that must be provided in each brand-specific copy of this file:

  • whatsthis - Informal description of the file, for human readers
  • projectName - The single-word label for the project - no white-space or punctuation.
  • description - Very brief, one-sentence description of the software.
  • identifier - The reverse-domain notation, globally-unique software identifier. This identifier will be used for all platform builds except Android and iOS, which, for legacy reasons, have their own, distinct identifier fields.
  • androidIdentifier - the reverse-domain notation identifier specifically for Android platform builds.
  • iosIdentifier - The reverse-domain notation identifier specifically for iOS platform builds.
  • customPlugins - A list of lists specifying the paired cordova plugin add - and cordova plugin remove ... values for any plugins that are specific to this brand.

Build- and run-time settings

The following brand-specific configurations are obtained by the application code when the application is built for a particular platform.

Application text substitutions

src/helpers/customStrings.js implements a facility for substituting custom strings for standard ones. It provides a function, abbreviated as window.s(), by which the strings to be replaced are expressed in code and templates. The subject strings are compared against the collections dictated by some json configuration files, in decreasing order of precedence:

  • www/customAppStrings.json
  • www/appStrings.json
Subject strings not found in either file are returned as is.
To commission a particular string for customization:
Include the default string text and its presentation in www/appStrings.json. That file thereby serves as a comprehensive repertoire of the all the available customizable strings.
Refer to the string in program and template text by using a call to the s function, passing the default form of the string as the parameter.
  • E.g., in regular js code: s("SpiderOak Hive")
    • or in a template: {{= s("SpiderOak Hive") }}
To provide a version of the string's presentation for a particular custom build:
Provide an entry for that string in custom/brand/customAppStrings.json.
NOTE WELL: Do not customize app strings by making changes to www/customAppStrings.json, but instead make changes to a copy that you put in custom/brands/<brand name>/customAppStrings.json. Then the content-file substitutions facility, described [White-label-App-Customization#application-content-file-substitutions], will substitute the custom copy for the default www/customAppStrings.json in the build, at build time.

Application content-file substitutions

This customization facility replaces application settings and media files with ones having particular names found in a particular directory, set aside for the purpose.

Specifically, the eligible substitutions are described by a configuration file, such that:

  • any files in a particular directory
  • with names matching one of the configuration file entries
  • will be copied to platform build locations as designated in the configuration entry
  • at the end of the build preparations phase.
The facility is implemented using a cordova after_prepare build hook script: .cordova/hooks/after_prepare/customize.js

The content-file substitutions configuration file is custom/elements.json:

The customization repertoire is extended by adding new entries.

The facility is used by including items with file names (and content) matching one of the entries, in the folder specified by the GetCustomElementsFrom field, and doing a build.

Here's the format of the custom/elements.json configuration file:

  • Purpose - describe the file
  • GetCustomElementsFrom - the path of the brand configuration directory. This can be overridden for a specific brand item by its own GetCustomElementsFrom entry.
  • Items - an array of the customization candidate elements. Each element consiste of:
    • SourceFileName - the name of the file as it exists in the GetCustomElementsFrom folder and the target folder. ** TargetFileName *optional* - used when the target file name differens from the SourceFileName.
      • If SourceFileName starts with a "^" caret, then the string is used as a regular expression, with the item action being iterated across files in the source directory with names that the expression matches.
    • TargetFolder - where in the build tree, relative to the respective platform roots, the target file belongs. TargetFolder is used exclusive to TargetAction.
    • TargetAction - action, implemented in customize.js, to process the source file. TargetAction is used exclusive to TargetFolder.
      • Currently, iOSaddCertificate is the only TargetAction - it adds the source file as a resource in the iOS bundle.
    • Format - Description of the file content medium, for the integrator (the facility doesn't check)
    • Purpose - More info for the integrator
    • Platforms - To which platforms the custom content belongs
    • GetCustomElementsFrom *optional* - item-specific path for the current item, overriding the general setting.
custom_config.js overrides default application configuration. It replaces the standard custom_config.js file, which in turn is used to extend the default www/config.js file. Thus, it replaces any settings in the standard custom_config.js, and overrides only those settings from the standard config.js.
Clone this wiki locally