Skip to content

White Label

Jump to bottom Edit New page
Ken Manheimer edited this page Mar 25, 2014 · 2 revisions

Table of Contents

Application Brand Customization

Mixing brand-specific customization into our cross-platform infrastructure involves two distinct levels of tailoring:

  1. Application package brand selection: At the top level is project configuration, in which a package of brand-specific settings is selected for the application repository clone, so that those brand settings are used when any of the platform builds are done. Use grunt brand commands to assess and select the current brand for builds of your clone.
  2. Within the brand selection is the collection of operational and appearance parameters used by the application code.
This document describes the configuration and operation of both the brand selection process and the brand-specific details.

(We'll use ./ to denote the repository clone's root directory.)

Selecting Application Package Brand

The grunt brand commands set or reveal your repository clone's currently selected brand context. That selection persists until you change with another grunt brand setting command, or you manually alter the symlink by which the setting is implemented:

  • grunt brand: indicate the currently selected brand, according to the value of the symlink ./custom/brand, and also indicate the selection of available brand configurations according to the directories present in ./custom/brands/.
  • grunt brand:<brand name>: Configure the app repositor clone so that its ./custom/brand symlink points to the desired brand packaging in the subdirectory of ./custom/brands/ named <brand name>. It's an error if there is no such subdirectory.
  • grunt brand:-: Iff the app repository clone has no currently configuration, then configure it for the default (SpiderOak) brand. If there is a valid, established brand, this informs you of that fact, and what it is. (This is command is used at the end of npm install, so that installing ensures there is some brand configuration, without disrupting the current one, if any.)
  • grunt brand:!: Reassert the current brand configuration, going through the whole process, including reconstituting the cordova platforms, etc.
If the none of the ./custom/brands subdirectories have the specified brand name, then an error is emitted, and also a listing of the subdirectories.

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 they reflect those brand-specific values.

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.

There are two primary aspects to configuring the build branding, conveyed by two specification files:

  1. Identification of the adjustments to be made to each of the platform-specific build manifests - detailed in [White-label-App-Customization#Specification_of_Customizations_for_All_Build_Manifests].
  2. The brand-specific values for each brand configuration, provided for plugging in to the platform manifests, in each brand's configuration directory - detailed in [White-label-App-Customization#PerBrand_Platform_Build_Manifest_Values].
The package manifests are synthesized when the grunt brand:<path> command is issued. The other, operational and appearance brand-specific settings are fetched from brand configuration files and applied when application builds are done. The rest of this document describes these operational and appearance brand configurations.

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 [1] is implemented using a cordova after_prepare build hook script, customize.js [2]

The content-file substitutions configuration file is json: 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: designate the directory for the custom versions
  • Items: an array of the customization candidate elements. Each element consiste of:
    • Phase - defaults to build, for standard build configurations, or package for manifest-related actions to take in preparing the package for building.
    • Either FileName or the combination of SourceFileName and TargetFileName: the name of the file as it exists in the GetCustomElementsFrom folder and the target folder. FileName is used when the name is the same in both places. If it needs to have different names, use SourceFileName and TargetFileName, respectively.
    • TargetFolder: where in the build tree, relative to the respective platform roots, the target file belongs.
    • 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
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.

Configuration Files and Formats

Brand Project Configuration

Specification of Customizations for All Build Manifests

Item 1, ./custom/brand_elements.json, is an array whose top-level elements are, themselves, arrays that specify the manifest or other build-configuration file, and the interpolations in that manifest. Specifically:

  • The path of the manifest file, relative to the repository root
  • An array of interpolations specifications, each of which identifies:
    1. The particular ./custom/brand/project_config.json field whose value will be interpolated into...
    2. The tag of the manifest file identified by this path specification. The path specification is interpreted according to the type of the manifest file - an elementtree XPath-style path for XML files, and a PList field for plist files.
    3. An optional attribute identifier, for XML manifests where the value is to be interpolated into the targeted tag attribute, rather than its text content.

Per-Brand Platform Build Manifest Values

The ./custom/brand/project_config.json fields are named by element (i.) in the ./custom/brand_elements.json, mentioned just above. They identify the particular brand-specific values to be interpolated into the manifests. Here are the fields that must be provided in this file for each brand configuration:

  • 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.

Brand Details Configuration

Add a custom footer

[[TOC]]

Clone this wiki locally