Customizing Oracle JET Themes

You can use the Oracle JET SCSS files to customize themes. At build time, Oracle JET uses Sass to convert the alta/oj.alta.scss aggregating files to CSS. You can also use Sass to generate your own themes.

Topics:

Customizing an Oracle JET Theme Using Sass

You can use Sass to customize an Oracle JET theme.

To customize an Oracle JET theme using Sass:

Install Sass and Ruby as needed. For details, see http://sass-lang.com/install. Once you have Ruby, type the following command to install Sass:
```
gem install sass
```
If you normally use a proxy to connect to the internet, issue the following command instead:
```
gem install sass --http-proxy proxyurl
```
Create a custom settings file using the naming convention:_filename.scss. You can either:
- Create an empty file and add the variables you need, or
- Copy the theme's settings file to a new file
For example, create an empty file named _myCustomSettings.scss, or copy _oj.alta.settings.scss into a file named _myCustomSettings.scss.
In your custom settings file, set variables as needed for your application. If you copied the settings file, remove the comment from the variable before setting it.
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.
Create partial override files to customize your CSS as needed. Be sure to follow the underscore naming convention used by Sass and Oracle JET for your partials.
The example below shows a partial override file named _myCustomProgressBar.scss that overrides the height and width defaults for the Oracle JET ojProgressbar component.
```
.oj-progressbar {
  // override the JET defaults for height and width
  height: 20px;
  width: 400px;         
}
```

Create an aggregating SCSS file and import the partial override files.

The example below shows a custom aggregating file that imports a custom settings file, the Alta files, and the custom overrides.

//IMPORT CUSTOM SETTINGS
@import "myCustomSettings";
 
//IMPORT THE ALTA FILES
@import "../oj/alta/oj-alta";
 
//IMPORT CUSTOM FILES (after alta files)
@import
  "myCustomProgressBar",
  [... etc. all the custom overrides ...];

To control what content gets included in your CSS, see Controlling CSS Content.

Working with Framework Images in an Oracle JET Application

Oracle JET uses icon fonts whenever possible to render images provided by the Alta theme. When icon fonts are not possible, Oracle JET uses image files. In either case, framework images support high contrast mode. Oracle JET also provides CSS classes for most framework images.

Topics:

For examples of framework images, see Framework Images.

Image Considerations

There are a variety of ways to load icons, such as sprites, data URIs, icon fonts, and so on. Factors to consider when choosing an image strategy include:

Themable: Can you use CSS to change the image? Can you replace a single image easily?
High contrast mode: Does the image render properly in high contrast mode for accessibility?
High resolution support: Does the image look acceptable on high resolution (retina) displays?
Browser support: Do you require support for all browsers? Some browsers may not support certain image formats, such as SVG.
Image limitations: Are there limitations that impact your use case? For example, icon fonts are a single color, and small SVG images often do not render well.
Performance: Is image size a factor? Do you need alternate versions of an image for different resolutions or states such as disabled, enabled, hover, and active?

Icon Fonts

Oracle JET uses icon fonts whenever possible because icon fonts have certain advantages over other formats.

Themable: You can use style classes to change their color instead of having to replace the image, making them very easy to theme.
High contrast mode: Icon fonts are optimal for high contrast mode as they are considered text. However, keep in mind that you can't rely on color in high contrast mode, and you may need to indicate state (active, hover, and so on) using another visual indicator. For example, you can add a border or change the icon font's size. For additional information about Oracle JET and high contrast mode, see Configuring High Contrast Mode.
High resolution: Icon fonts look good on a high resolution (retina) display without providing alternate icons.
Performance: You can change icon font colors using CSS so alternate icons are not required to indicate state changes. Alternate images are also not required for high resolution displays.

Icon fonts also have disadvantages. It can be difficult to replace a single image, and they only show one color. You can use text shadows to provide some depth to the icon font.

Oracle JET supports two generic classes for setting the icon font colors in the $iconColorDefault, $iconColorHover, $iconColorActive, $iconColorSelected, and $iconColorDisabled variables.

oj-clickable-icon
oj-clickable-icon-nocontext

These classes, when used in conjunction with an anchor tag and/or marker classes like oj-default, oj-hover, oj-focus, oj-active, oj-selected, and oj-disabled, will use the $iconColor* variables.

The oj-clickable-icon class is optionally contextual, meaning the anchor or marker style can be on an ancestor as shown in the example below. The example assumes that a JavaScript method is replacing oj-default as needed with oj-hover, oj-focus, oj-active, oj-selected, and oj-disabled.

<div class="oj-default">
  <span class="oj-clickable-icon demo-icon-font demo-icon-gear"></span>
</div>
<a href="http://www.oracle.com">
  <span class="oj-clickable-icon demo-icon-font demo-icon-gear"></span>
</a>

The oj-clickable-icon-nocontext class is not contextual and must be placed on the same tag as shown in the example below. oj-clickable-icon would also work in this example.

<span class="oj-default oj-clickable-icon-nocontext demo-icon-font demo-icon-gear">
</span>
<a href="http://www.oracle.com"
   class="oj-clickable-icon-nocontext demo-icon-font demo-icon-gear">
</a>

For an example that illustrates icon font classes on a link, see Icon Fonts.

Image Files

Oracle JET uses images when icon fonts can't be used. Informational images must appear in high contrast mode for accessibility, as described in Configuring High Contrast Mode.

Oracle JET provides Sass mixins that you can use to create CSS for your own icons. For examples, see CSS Images.

Understanding Oracle JET Marker Styles

Oracle JET provides marker styles that can be used instead of CSS3 and CSS4 pseudo classes. For example, the oj-hover class can be used instead of the :hover pseudo class typically used in CSS3. The advantage of using a marker style is that you can use the same style on any DOM element.

The following table lists the Oracle JET marker styles and their CSS3 and jQuery UI equivalent.

Oracle JET Marker Style	CSS3 Inspiration	jQuery UI Equivalent	Description
Accessibility:
`oj-hicontrast`			This marker is placed on the body tag by either a script or the application. For details, see Configuring High Contrast Mode.
Component:
`oj-component`		`ui-widget`	Marks the root DOM element of a widget.
`oj-component`-initmode			Mark the `init` DOM element of a widget. This can be different than the root DOM element if the `init` node was wrapped by other DOM. For example, in an `ojInputNumber` component, the `init` node is an input element, but this is wrapped by other DOM when the component is created.
Link:
`oj-visited`	:visited		Applied when user visits the link or item.
Input:
`oj-disabled`	:disabled
`oj-enabled`	:enabled	`ui-state-default`
`oj-read-only`
`oj-invalid`
`oj-warning`
`oj-required`
`oj-indeterminate`	:indeterminate
User Action:
`oj-active`	:active	`ui-state-active` jQuery UI uses `ui-state-activ`e for both active and selected states. Oracle JET provides separate styling markers for active and selected/checked/toggled states so that you can style these states separately.
`oj-selected`		`ui-state-active` See previous explanation.	Used when something is selected, checked, or toggled on.
`oj-hover`	:hover	`ui-state-hover`	`:hover` works on any DOM element but only on the closest DOM element currently hovered over. `:oj-hover` can be placed on an element which is an ancestor of the element being hovered over. For example if you're hovered over an icon in a button, `oj-hover` may be placed on the button tag, which is the ancestor of the tag with the icon.
`oj-focus`	:focus	`ui-state-focus`
`oj-focus-only`			Used when something is focused, but you only want to set the style when `oj-selected`, `oj-hover`, `oj-active` are not set.
`oj-default`			Used when something is clickable, but you only want to set the style when `oj-selected`, `oj-hover`, `oj-focus`, and `oj-active` are not set. For example, the following code will render the text white only when the button is not in a selected, hover, focus, or active state. .demo-appheader-toolbar .oj-button.oj-default .oj-button-text { color: white; }
Collapsible:
`oj-expanded`			Used when something expandable is expanded.
`oj-collapsed`			Used when something expandable is collapsed, meaning that it's not expanded.
Alignment:
`oj-right` `oj-center` `oj-left` `oj-start` `oj-end`			Indicates the horizontal position, such as the tail of a popup.
`oj-top` `oj-middle` `oj-bottom`			Indicates the vertical position, such as the tail of a popup.

Oracle JET also provides the following marker styles that can be used instead of CSS4 pseudo classes.

Oracle JET Marker Style	CSS4 Inspiration	Description
Drag and Drop:
`oj-draggable`		Used on draggable elements.
`oj-drag`		Used on element when dragged.
`oj-drop`	:drop	Applies to all elements that are drop targets during a drag.
`oj-active-drop`	:drop (active)	Used on element that will receive the item currently being dragged.
`oj-valid-drop`	:drop (valid)	Used on elements that can receive the item currently being dragged.
`oj-invalid-drop`	:drop (invalid)	Used on elements that can't receive the item currently being dragged.

Internally, Oracle JET follows these rules for clickable elements:

Oracle JET Marker Style	Used if Widget is Disabled?
`oj-enabled` or `oj-disabled`	`oj-enabled`: no `oj-disabled`: yes
`oj-selected`	Yes
`oj-active`	No
`oj-hover`	No
`oj-focus`	No
`oj-focus-only`	No
`oj-default`	No

For additional information about the CSS3 selectors, see http://www.w3.org/TR/css3-selectors/. For more information about the CSS4 selectors, see http://dev.w3.org/csswg/selectors4/.

Controlling Initial Visibility with CSS

You can set an Oracle JET component's CSS visibility property to hidden on the DOM until the component is initialized using the $initialVisibility variable. The component will still occupy space on the page, but the user will not see the component during page load.

// when $initialVisiblity is hidden then visibility: hidden is set on the DOM until the
// component is initialized. This reduces the unstyled DOM seen by the user during page load.
$initialVisibility: hidden !default

In addition to using this variable, you may also want to inline the following CSS into the head section of the first page so that uninitialized DOM is hidden even before the CSS file is downloaded and cached.

<style>
  [data-bind*="ojComponent"]:not(.oj-component-initnode) {
    visibility: hidden;
  } 
</style>

For more information about the CSS visibility property, see http://www.w3.org/wiki/CSS/Properties/visibility.

Understanding Right-to-Left Behavior

By default, the same CSS is used for right-to-left and left-to-right behavior, even if you set dir=rtl on the HTML tag. If you prefer to generate one CSS file for each direction, you can set the $textDirection variable to rtl or ltr.

Oracle JET does not support multiple directions on a page. The reason this is not supported is that the proximity of elements in the document tree has no effect on the CSS specificity, so switching directions multiple times in the page may not work the way you might expect. The code sample below shows an example.

<style>
  [dir=ltr] .foo {color: blue}
  [dir=rtl] .foo {color: red}
</style>
<span dir="rtl">
  <span dir="ltr">
    <span class="foo">You might think I will be blue because dir=ltr is on,
                      a closer ancestor than dir=rtl. But css doesn't care
                      about proximity, so instead I am red
                      (because [dir=rtl] .foo {color: red} was defined last).
                      Isn't that surprising?
    </span>
  </span>
</span>

For additional information about Oracle JET and bidirectional support, see Enabling Bidirectional (BiDi) Support in Oracle JET. For more information about CSS specificity, see https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity.

Understanding Oracle JET and Browser Degradation

Certain browsers that Oracle JET supports may not support CSS properties such as animations, box shadows, and so on. This is considered acceptable as long as it degrades in a reasonable fashion. For example you may not get any animations on that browser, and you will just get a border instead of a box shadow.

On other browsers, for performance reasons, Oracle JET will not render a border radius, box shadow, or gradient, even if the browser supports it. For example, on Internet Explorer, Oracle JET sets the border radius to 0, as shown in the following example.

.oj-button {
    border-radius: 2px;
}
 
.oj-slow-borderradius .oj-button {
    border-radius: 0;
}

Internet Explorer has two rendering modes, GPU and software rendering. Performance for these CSS properties can be very slow in software rendering mode, and even GPU rendering has been slow in many cases. Also, Oracle JET has no way to determine which rendering mode is being used. Therefore, in Oracle JET the oj-slow-* classes are used in all supported versions of Internet Explorer.

You can control the behavior of the border radius, gradient, and box shadow by setting the following variables:

$borderRadiusGeneration
$gradientGeneration
$boxShadowGeneration

Valid options for these variables include:

slowOverride (default): Generate the regular value but also generate overrides for slow browsers to remove the border radius, gradient, and box shadow on slow browsers.
on: Generate only the regular value. Do not generate overrides.
off: Do not generate a regular or override value. This setting is useful if you want to design style sheets specifically for Internet Explorer only.

Printing Oracle JET Pages

Oracle JET includes styles that implement responsive printing through print media queries.

In general, printing should look reasonable on most screens. However, you may need to require the end user to turn on background colors and images before printing, which are off by default for most browsers. For example, in the Chrome Print dialog, your end user may need to select the Background colors and images checkbox.

Also, Oracle JET removes some background images in high contrast mode. For more information about high contrast mode and workarounds for displaying images even when background images are disabled, see Configuring High Contrast Mode.

For additional information about responsive classes and printing, see Oracle JET and Responsive Web Design.