Styling¶

Mobile Development Kit support styling with LESS (which stands for Leaner Style Sheets) to support multi-platforms styling capability. It is backwards-compatible with CSS (for NativeScript controls) and NSS (for iOS) and support Android too. With Less style file, you only need to define your styles in 1 format and it will be usable in all platforms.

More info on Less (Leaner Style Sheets) can be found here.

Variables¶

It's not uncommon to see the same value repeated dozens if not hundreds of times across your style-sheets:

a,
.link {
  color: #428bca;
}
.widget {
  color: #fff;
  background: #428bca;
}

Variables make your code easier to maintain by giving you a way to control those values from a single location:

// Variables
@link-color:        #428bca; // sea blue
@link-color-hover:  darken(@link-color, 10%);

// Usage
a,
.link {
  color: @link-color;
}
a:hover {
  color: @link-color-hover;
}
.widget {
  color: #fff;
  background: @link-color;
}

More info on Less variables feature can be found here.

By-Class Styling¶

This is the standard way to style controls dynamically (i.e. through rules).

Styles are defined in the LESS file as .SomeClass and then all controls marked to have that class (without the prefix dot ".") will use those styles.

Static Styling (via Metadata Definitions)¶

{
  // ...
  "Buttons": [{
    "Title" : "Delete",
    "Style": "SomeClass"
  }]
}

Dynamic Styling (via Rules)¶

The following APIs are available to apply styles at runtime to a NativeScript control.

export default function someRule(clientAPI) {
  control = clientAPI.getControl()
  control.setStyle('SomeClass');
  control.setStyle('SomeClass', 'SubControl');
}

If no sub control is given, the style is applied to the entire control.

By-Name Styling¶

Styles are defined in the LESS file as #SomeName and all NativeScript controls with _Name equal to SomeName in your metadata definitions will have the desired style automatically.

Note: The Toolbar doesn't have its own _Name in the metadata, so it can be accessed through its host page's name by adding _ToolBar to it, i.e. using #<PageName>_ToolBar.

By-Type Styling¶

Styles are defined in the LESS file as SomeType and all NativeScript controls of this particular type will have the desired style automatically.

Available Type	Control Type ({N})
`ActionBar`	`ActionBar`
`MDKPage`	`Page`
`ToolBar`	`ToolBar`

/* This style applies to all the ActionBars in the application*/
ActionBar {
    color: white;
    background-color: red;
}

/* This style applies to all the ToolBars in the application */
ToolBar {
    color: white;
    background-color: blue;
}

/* LogoutToolbarItem is Logout toolbar item in Main.page */
#LogoutToolbarItem  {
    color: brown;
}

/* UploadToolbarItem is  Sync toolbar item in Main.page */
#UploadToolbarItem  {
    color: green;
}

/* Styling of the toolbar on the FilterPage.page */
#FilterPage_ToolBar  {
   color: #cae4fb;
   font-family: "system";
   font-size: 16;

/* bartintcolor is non-translucent */
   bartintcolor: #455E74;
   border-top-color: #455E74;
}

/* This style applies to the backgound while navigating to a page */
MDKPage {
  background-color: red;
}

Multiple Styling Themes¶

Multiple styling themes can be supported if you create several different LESS files (.less) in 'Styles' folder in metadata. When developers define a LESS style file to the Styles of Application.app, this style is applied for application by default. Developers can dynamically change LESS file used for application via Action or Rule, by SetTheme action or ClientAPI.setTheme().

Developers can get available list of LESS files via ClientAPI.getAvailableThemes() or evaluateTargetPath("#Application/#ClientData/#Property:AvailableThemes"). The file name of LESS file (without .less extension) is the theme name. e.g. If the app have these 2 files in the Styles folder:

MyRedThemeStyles.less
MyBlueThemeStyles.less

Then the app will have MyRedThemeStyles and MyBlueThemeStyles in the available themes.

Appearance Specific LESS Styling - Starting From iOS 13 and Android 10 (API Level 30)¶

You may add appearance specific less file (Styles.light.less and Styles.dark.less) in 'Styles' folder in metadata. There is no changes on the way to define the Styles property on Application.app in metadata. No need to specify .dark or .less in the theme value or path. A .light or .dark less file is automatically selected according to current appearance in device setting if the .light.less or .dark.less file is provided.

Example combinations:

All less files are provided (appearance specific and default less files):
- Styles/MyBlueTheme.light.less <-- will load this theme file in light mode if 'MyBlueTheme' is chosen.
- Styles/MyBlueTheme.dark.less <-- will load this theme file in dark mode, if 'MyBlueTheme' is chosen.
- Styles/MyBlueTheme.less <-- This is always ignored because appearance specific less files are provided in mobile application. will load this theme for web client.
Only default less file is provided (no appearance specific less file):
- Styles/MyRedTheme.less <-- will always load this theme regardless of the appearance if 'MyRedTheme' is chosen. will also load this for web client.
Only dark and default less files are provided:
- Styles/MyGreenTheme.dark.less <-- will load this theme file in dark mode if 'MyGreenTheme' is chosen.
- Styles/MyGreenTheme.less <-- will load this theme file in light mode if 'MyGreenTheme' is chosen. will also load this for web client.
Only dark less file is provided:
- Styles/MyOrangeTheme.dark.less <-- will load this theme file in dark mode if 'MyOrangeTheme' is chosen. And no style customization will be applied in light mode as the light or default less file is not provided. No style for web client neither.

The structure of conversion from .less into .css, .nss, and .json is the same as other normal .less file. Example of converted content in the 'bundle.js':

{
  "MainPage": "/MDKDevApp/Pages/Main.page",
  "_Name": "MDKDevApp",
  "Version": "1.0.0",
  "Styles": "/MDKDevApp/Styles/Styles.less",
  "StyleSheets": {
    "Styles.dark": {
      "css": "/MDKDevApp/Styles/Styles.dark.css",     // for NativeScript controls
      "ios": "/MDKDevApp/Styles/Styles.dark.nss",      // for iOS SDK controls
      "android": "/MDKDevApp/Styles/Styles.dark.json"  // for Android SDK controls
    },
    "Styles.light": {
      "css": "/MDKDevApp/Styles/Styles.light.css",     // for NativeScript controls
      "ios": "/MDKDevApp/Styles/Styles.light.nss",      // for iOS SDK controls
      "android": "/MDKDevApp/Styles/Styles.light.json"  // for Android SDK controls
    },
    "Styles2.dark": {
      "css": "/MDKDevApp/Styles/Styles2.dark.css",     // for NativeScript controls
      "ios": "/MDKDevApp/Styles/Styles2.dark.nss",      // for iOS SDK controls
      "android": "/MDKDevApp/Styles/Styles2.dark.json"  // for Android SDK controls
    },
    "Styles2.light": {
      "css": "/MDKDevApp/Styles/Styles2.light.css",     // for NativeScript controls
      "ios": "/MDKDevApp/Styles/Styles2.light.nss",      // for iOS SDK controls
      "android": "/MDKDevApp/Styles/Styles2.light.json"  // for Android SDK controls
    }
  }
}

Standard Colors¶

The following standard color names are supported. However, there are certain color names that works only in specific platforms and each platform might render certain color names differently. We highly recommend apps to use hex color code to ensure the correct color is applied.

Color Name	iOS	Android
aqua		X
black	X	X
blue	X	X
brown	X
cyan	X	X
darkgray	X	X
darkgrey		X
fuchsia		X
gray	X	X
green	X	X
grey		X
lightgray	X	X
lightgrey		X
lime		X
magenta	X	X
maroon		X
navy		X
olive		X
orange	X
purple	X	X
red	X	X
silver		X
teal		X
white	X	X
yellow	X	X

Examples¶

Application.app¶

{
  "MainPage": "/MDKDevApp/Pages/Main.page",
  "_Name": "MDKDevApp",
  "Version": "1.0.0",
  "Styles": "/MDKDevApp/Styles/Styles.less"
}

Styles.less¶

@mdkYellow1:                  #ffbb33;
@mdkRed1:                     #ff0000;

/* By-Type style: All Pages in the application will now have a yellow background */
MDKPage {
  background-color: @mdkYellow1;
}

/* By-Name style: All Buttons with _Name == "BlueButton" will now have this style */
#BlueButton {
  color: @mdkYellow1;
  background-color: #0000FF;
}

/* By-Class style: These style classes can be referenced from rules */
.MyButton {
  color: @mdkYellow1;
  background-color: @mdkRed1;
}

Last update: August 25, 2021