Sass Files, Variables, and Tools

SCSS File Organization and Naming Convention

Oracle JET follows the Sass underscore naming convention. Files that start with an underscore are called partials and are not compiled independently with Sass. Instead, the partials are imported into an aggregating file. There is one partial file per module, for example, _oj.table.scss, _oj.formcontrol.inputnumber.scss, and so on.

The following table lists the directory structure for the files contained within the alta directory.

File	Description
`widgets/_oj.alta.formcontrol.inputnumber.scss` `widgets/_oj.alta.table.scss` etc.	Alta widget partial files
`_oj.alta.variables.scss`	Contains the SCSS variables
`_oj.alta.settings.scss`	Contains a commented version of the variables file that you can remove the comments from and modify
`_oj.alta.widgets.scss`	Imports widget partial files
`oj-alta.scss`	Generates the `oj-alta.css` and `oj-alta-min.css` files
`oj-alta-notag.scss`	Generates the `oj-alta-notag.css` and `oj-alta-notag-min.css` files

SCSS Variables

The SCSS variables that Oracle JET uses to generate the application use the same naming convention and are grouped together according to function. Oracle JET also uses SCSS variables to default some component options, such as the ojButton’s chroming option.

Variable Naming Convention

Oracle JET variables names use a camel case naming structure: <widgetName><Element><Property><State>.

Type	Description	Examples
widgetName	Component or pattern name	`dataGrid`, `button`
Element (Optional)	Component subsection	`Cell`, `Header`
Property	Property affected	`BgColor`, `BorderColor`, `TextColor`
State (Optional)	Widget’s state when applied	`Hover`, `Active`, `Focus`, `Selected`, `Disabled`

Using this convention, the following are all valid Oracle JET SCSS variables: $buttonHeight, $sliderThumbWidth, $dataGridCellBgColorHover, $treeNodeBorderColorSelected

Variable Documentation

Variable names are typically self-documenting. In cases where additional documentation is needed, the SCSS file will contain comments above the variable definition.

Variable Categories

The following table lists the high level variable categories.

Category	Description
Logistical	Affects logistics, such as the path to an image directory or text direction.
Performance	Set these variables to include only the CSS your application uses.
Palette	Application’s color palette. Examples include `$interaction1Color`, `$background1Color`, and `$border1Color`.
Text	Controls text appearance. Widget files use these variables extensively. Examples include `$fontFamily`, `$rootFontSize`, `$textColor`, and `$linkTextColor`.
General	Sets general theme properties such as drag and drop colors, border radius defaults, and animation duration defaults.
Widget	Affects specific widgets or widget groups, such as button or form control variables. Some component default options are included here. For example, you can change the `ojButton` component’s chroming option using `$buttonChromingOptionDefault`.

Using Variables to Control CSS Content

You can use the $includeAllClasses variable in your SCSS settings file to control content for the entire application. By default, the variable is set to true as shown below.

// by default everything is included, but you can also start by setting
// $includeAllClasses to false and then just add in what you want.
$includeAllClasses: true !default;

Some partials also allow you to control their content with a variable. For example, the ojButton component has the $includeButtonClasses variable near the top of the settings file.

$includeButtonClasses: $includeAllClasses !default;

To exclude the ojButton style classes, you can set $includeButtonClasses to false as shown below.

$includeButtonClasses: false;

Oracle JET also uses several higher level groupings that let you control the CSS for a logical group of components. The table lists the groups that are available for your use.

Group SCSS Variable File Names

Group	SCSS Variable	File Names
Tags (headers, links, and so on)	`$includeTagClasses: $includeAllClasses !default;`	Files with `tag` in name, as in: `_oj.alta.tags.typography`
Data visualizations (charts, gauges, and so on)	`$includeDvtClasses: $includeAllClasses !default;`	Files with `dvt` in name, as in: `_oj.alta.dvt.char`t
Form controls (labels, combo box, and so on)	`$includeFormControlClasses: $includeAllClasses !default;`	Files with `formcontrol` in name, as in: `_oj.alta.formcontrol.label`

Tags (headers, links, and so on)

$includeTagClasses: $includeAllClasses !default;

Files with tag in name, as in:

_oj.alta.tags.typography

Data visualizations (charts, gauges, and so on)

$includeDvtClasses: $includeAllClasses !default;

Files with dvt in name, as in:

_oj.alta.dvt.chart

Form controls (labels, combo box, and so on)

$includeFormControlClasses: $includeAllClasses !default;

Files with formcontrol in name, as in:

_oj.alta.formcontrol.label

You can include or exclude classes and groups as shown in the following examples.

// Example: Exclude the dvt classes
$includeDvtClasses: false;

// Example: Include only the dvt classes, exclude everything else
$includeAllClasses: false;
$includeDvtClasses: true;

// Example: Include the chart and sunburst classes, exclude everything else
$includeAllClasses:      false;
$includeChartClasses:    true;
$includeSunburstClasses: true;

Note:

Some components depend on others. For example, the ojInputNumber uses ojButton internally, so if you include the ojInputNumber classes, you will also get the ojButton classes automatically.

Understanding Right-to-Left Behavior

By default, the same CSS file is used for right-to-left behavior when you set dir=rtl on the HTML element as described in Enabling Bidirectional (BiDi) Support in Oracle JET. 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 Theming For Compatibility

There may be cases where you do not want to use aspects of the default theming because it causes compatibility issues. For example, you may be embedding JET components or regions in a page controlled by another technology, such as Oracle ADF. Oracle JET provides several options for controlling use of tag selectors, REM, and normalize.css.

Topics:

Using Tag Selectors or Classes

By default, Oracle JET applies styles directly to HTML tag elements such as a, h1, h2, and so on. This feature makes it easier to code a page since you do not have to apply selectors to each occurrence of the element.

The following code shows a portion of a custom SCSS file that defines styles for link and header tags. When the CSS file is generated, the styles will be applied directly to the link and header tags.

/* links */
a {
    color: $linkTextColor;
    line-height: inherit;
    text-decoration: none;
}
 
a:visited {
    color: $linkTextColorVisited;
}
 
/* headers */
h1, h2, h3, h4 {
    color: $headerTextColor;
    font-family: inherit;
    font-style: normal;
    font-weight: $headerFontWeight;
    margin: 10px 0;
}

If you do not want to apply styles directly to the tags, you can specify that Oracle JET use classes instead of tag selectors in your custom.scss file:

$allowTagSelectors: false;

// theme import
@import "../oj.alta/oj-alta";

The code below shows the classes that Oracle JET will use for the Alta theme's links and headers when you set $allowTagSelectors to false. To use the class on your page, specify the class in the tag element on your page (<a class=oj-link>).

/* links */
.oj-link {
    color: $linkTextColor;
    line-height: inherit;
    text-decoration: none;
}
 
.oj-link:visited {
    color: $linkTextColorVisited;
}
 
/* headers */
.oj-header {
    color: $headerTextColor;
    font-family: inherit;
    font-style: normal;
    font-weight: $headerFontWeight;
    margin: 10px 0;
}

The following table lists the HTML tags with default Oracle JET tag styles and the corresponding Oracle JET class.

HTML Tag	Oracle JET Style Class
`html`	`oj-html`
`body`	`oj-body`
`a`	`oj-link`
`h1`, `h2`, `h3`, `h4`	`oj-header`
`hr`	`oj-hr`
`p`	`oj-p`
`ul`, `ol`	`oj-ul`, `oj-ol`

If you also do not want to use the Oracle JET tag classes, you can set $includeTagClasses to false in your custom.scss file as shown below.

$includeTagClasses:false;

Using REM

By default, Oracle JET uses REM (root em) for font sizing. This means that a specific font size is set on the root (html) element, and other font sizes are defined relative to that root size. The following example shows the default font sizing for the Alta theme.

// The browser usually uses 16px and the Alta default is 14px. 
// Therefore set $rootFontValue to .875em to get 14px;
$rootFontSize:     .875em !default;   // 14px

$fontSize:         1rem !default;     // 14px
$smallestFontSize: .7857rem !default; // 11px when root 14px
$smallFontSize:    .857rem !default;  // 12px when root 14px
$mediumFontSize:   1.143rem !default; // 16px when root 14px
$largeFontSize:    1.286rem !default; // 18px when root 14px
$largestFontSize:  1.429rem !default; // 20px when root 14px

To use REM, the font size must be set on the html element. If you want to use REM but do not want to set a style directly on the html tag, you can reference the oj-html class as described in Using Tag Selectors or Classes.

If you do not want to use REM, you can specify an alternate font size by modifying a custom.scss file to use the units your application requires. The code sample below shows how you could use pixels instead of rems to set font sizes.

// use px instead of rem for fonts
$rootFontSize:     12px;
$fontSize:         $rootFontSize;
$smallestFontSize: $rootFontSize - 2px;
$smallFontSize:    $rootFontSize - 1px;
$mediumFontSize:   $rootFontSize + 2px;
$largeFontSize:    $rootFontSize + 4px;
$largestFontSize:  $rootFontSize + 6px;

For additional information about REM, see http://snook.ca/archives/html_and_css/font-size-with-rem.

Using Normalize

By default, Oracle JET uses normalize.css to promote consistency when rendering across browsers. If your application also uses normalize.css, add the import in your custom.scss:

@import "../3rdparty/normalize/normalize";

If you do not want to use normalize, you can set the following variable to false in your custom.scss:

$includeNormalize: false;

Alternatively, you can set $allowTagSelectors to false as described in Using Tag Selectors or Classes.

For additional information about normalize.css, see http://necolas.github.io/normalize.css.

SCSS Tools

Oracle JET provides its own Sass mixins and doesn’t use Sass tools such as Autoprefixer or Compass. This reduces the number of third-party tools required to work with Oracle JET’s SCSS.

However, Oracle JET does support Sass source maps which can make it easier to work with a large number of partial files. The toolkit includes source maps for the default and no tag selector versions of the generated CSS for the Alta theme: oj-alta.css.map, and oj-alta-notag.css.map.

For additional information about source maps, see https://developers.google.com/chrome-developer-tools/docs/css-preprocessors.