Customizing Themes Using the Tooling Framework

Use the Oracle JET tooling framework to add Sass support and customize your application’s theme or specify an alternate theme.

By default, the SCSS files are not included with applications that you scaffold with the Oracle JET Yeoman generator. However, you can use tooling commands as described in the procedure below to add node-sass and skeleton theme files to your application. You can then modify the skeleton theme files while the application is running and observe the effect of the change immediately using the live reload feature.

To customize an Oracle JET theme using the tooling framework:

If needed, scaffold your application as described in Scaffold a Web Application with Yeoman or Scaffold a Hybrid Mobile Application with Yeoman.

  1. In your application’s top level directory, enter the following command at a terminal prompt to add node-sass to your application:
    yo oraclejet:add-sass
    
  2. Add the skeleton theme files to your application.
    yo oraclejet:add-theme themeName
    

    For example, enter the following command to create the skeleton theme files for a custom theme named myTheme: yo oraclejet:add-theme myTheme.

    The command creates a new folder with the custom theme name in the application’s src directory. The web folder is expanded to show the .scss files that you can modify. The myTheme.scss is the aggregating file for the given platform. The android, ios, and windows folders contain similar files with the name of the platform in the title: _myTheme.android.overrides.scss, _myTheme.android.settings.scss, and so on.

    The image is described in the surrounding text.

    You’ll find out more about modifying these files in a later step.

    The theme.json file contains the version number of the theme, starting with 0.0.1.

    Note:

    The file locations will vary if you modified your directory structure as described in Modify the Web Application’s File Structure or Modify the Hybrid Mobile Application’s File Structure.
  3. Use grunt build with the --theme option to build a development version of your application with the new theme.
    grunt build --theme=themeName[:android|ios|web|windows] [--platform=android|ios|web|windows]
    

    For example, the following command builds a web application with the myTheme custom theme.

    grunt build --theme=myTheme
    
  4. To build more than one theme, add the --themes option with the names of the desired themes separated by commas:
    grunt build --theme=myTheme --themes=myTheme,myTheme1,myTheme2
    
  5. To run your application with live reload enabled, enter grunt serve with the theme option and optional platform.
    grunt serve --theme=themeName[:android|ios|web|windows] [--platform=android|ios|web|windows]
    

    For example, the following command serves a web application with the myTheme custom theme in the default browser.

    grunt serve --theme=myTheme
    
  6. Edit the themeName.platform.settings.scss file to set variables as needed for your application.

    For detailed information about Oracle JET and SCSS variables, see SCSS Variables

    For example, to turn off tag selectors, remove the comment from the $allowTagSelectors variable if needed and set it to false.

    $allowTagSelectors: false;
    

    For information about Oracle JET's use of tag selectors, see Using Tag Selectors or Classes.

    Other high impact variables that you can modify to see their effect include:

    • Palette variables: $interaction1Color, $background1Color, and $border1Color

      These variables impact color across the application. For example, change the $interaction1Color to control the color that indicates a selected state.

    • Text variables: $fontFamily, $rootFontSize, $textColor, and $linkTextColor

      Change these variables to affect the font type, size, and color of text in your application.

    When you use grunt serve to serve your application, live reload will reload the page, and any changes you make to your theme files will display in the browser.
  7. Use the themeName.platform.overrides.scss file for your partial overrides.

    The example below shows the partial override file named _myTheme.web.overrides.scss which is overriding the height and width defaults for the Oracle JET ojProgressbar component on the web platform.

    .oj-progressbar {
      // override the JET defaults for height and width
      height: 20px;
      width: 400px;         
    }
    
  8. Modify the themeName.scss aggregating file if you add additional override files.

    The example below shows the default aggregating file for the myTheme web platform.

    // Note that the order in the aggregating file is important
    //
    // 1. custom variables file: Due to the way sass default works, 
    //    the custom variable file must be imported before the platform theme 
    //    aggregating file (where the platform variable file will be imported).
    // 2. platform theme aggregating file
    // 3. custom override file(s): In case of specificity equality 
    //    the last declaration found in the CSS file wins, so you want
    //    your overrides imported last so they have higher specificity.
    
    //import custom variable overrides
    @import "myTheme.web.settings";
    
    // import alta aggregating file
    @import "../../../../node_modules/oraclejet/dist/scss/alta/oj-alta";
    
    // import custom css overrides
    @import "myTheme.web.overrides";
    
  9. To optimize performance, consider the use of variables to include only the CSS that your application needs. For help, seeUsing Variables to Control CSS Content.

    Tip:

    You can observe the effect of any changes immediately. This can be handy if you’re not sure whether your application needs a given variable.
  10. To exit the application, save your changes, and press Ctrl+C at the terminal prompt.

    You may need to press Ctrl+C a few times for the command to take effect.

Tip:

To make working with themes easier, Oracle JET provides Theme Builder, an example application and tutorial. You can work with it online to see the effect of changes before you apply them to your own application. You can also download the sample and create your own themes offline for sharing.