Skip to content

Latest commit

 

History

History
125 lines (87 loc) · 6.49 KB

how_clay_arrives_to_dxp.md

File metadata and controls

125 lines (87 loc) · 6.49 KB
Raw

How does Clay arrive at DXP?

In Liferay DXP, there are 2 main methods to import Clay in our project.

  • as a Theme Inheritance
  • as a Node Dependency

The Theme Inheritance is present in those themes generated by the liferay-js-themes-toolkit that have an existing Liferay theme as a base.

The Node Dependency can usually be found in other DXP modules where it is imported directly into the package and doesn't follow the build process of the themes.

How is Clay imported as a Theme Inheritance?

In the complex infrastructure of themes, Clay is imported automatically if you set styled, classic or admin, as a base for your theme, from the generator.

This automatization is possible thanks to the top_head.jsp file in our common module that imports Clay in our themes just before the main.css.

If you are using unstyled as a base, you will have access to Clay but it won't be automatically imported in your theme.

Let's say we created a theme named my-theme, we used the generator and we set unstyled as a base.

Since unstyled is the most basic theme of the chain, you'll have a simple build process:

clay > unstyled > my-theme

But, this process will change depending on the base you've chosen:

Base Process
unstyled clay > unstyled > my-theme
styled clay > unstyled > styled > my-theme
classic clay > unstyled > styled > classic > my-theme
admin clay > unstyled > styled > admin > my-theme

Keep in mind that each base has its properties and are defined for specific scopes

unstyled styled classic admin
Clay ✅ ✅ ✅ ✅
Bourbon (deprecated) ✅ ✅ ✅ ✅
Mixins (deprecated) ✅ ✅ ✅ ✅
Legacy Liferay components (now in Clay) ✅ ✅ ✅
Common Liferay components (Portlets) ✅ ✅ ✅
Liferay customizations of Clay components ✅ ✅ ✅
Compat Layer: compatibility layer for Bootstrap 2 and 3 ✅ ✅ ✅
Main CSS of the Liferay websites and pages ✅
CSS Custom Properties Layer: Modern customization of Clay ✅
Hello World Widget: Front Page Banner ✅
Main CSS of the Liferay administration panels ✅

From a more technical point of view, setting the base through the generator will create a setting named liferayTheme in the package.json file of the theme folder.

{
	"name": "my-liferay-theme",
	"version": "1.0.0",
	"main": "package.json",
	"keywords": ["liferay-theme"],
	"liferayTheme": {
		"baseTheme": "styled",
		"templateLanguage": "ftl",
		"version": "7.0"
	},
	"devDependencies": {
		"gulp": "^3.8.10",
		"liferay-theme-deps-7.1": "*",
		"liferay-theme-tasks": "*"
	}
}

package.json example

How is Clay imported as a Node Dependency?

Another scenario of Clay usage happens with DXP modules, that imports the framework through a different, yet similar, process.

As for the previous method, we won't need to install Clay as a dependency in a module inside Liferay Portal. Thanks to our rich environment, we already have it included and we just need to enable it.

To do so, we just need to define the new import into our dedicated buildCSS process, we can do that by copying the following code into the build.gradle file of our module.

buildCSS {
	imports = [
		new File(npmInstall.nodeModulesDir, "@clayui/css/src/scss")
	]
}

buildCSS example

On the other hand, if you are working on a custom-theme or module outside DXP, we recommend to read our "how to use clay" page in the Clay's website

How to use Clay once imported?

And finally we arrive at the section where we explain what to do with Clay once imported, in order to have Clay available in our CSS we'll need to import it in our primary SCSS file.

In DXP we use the main.scss file but feel free to use whatever file you need for your module or theme.

It's important to know that it should be considered more like an activation since the real importation happens before as explained in the previous sections.

To enable Clay in our file, we need a really simple line of code:

@import 'atlas-variables';

Once imported, we will be able to use many variables, mixins and functions from Clay's library.

Variables worth of mention:

  • Color variables: $primary, $secondary, $success, $success-l1, ...
  • Spacing variables: $spacers, $grid-breakpoints, $container-max-widths, ...
  • Typography variables $font-family-serif, $h1-font-size, $display1-size, ...

Sources: BS, Base, Atlas

Useful mixins and functions: