Open Source Ecosystems

= Admin Theme :page-layout: base :toc: preamble :source-language: java :icons: font :linkattrs: :sectanchors: :sectlink: :numbered: :doctype: book :tip-caption: 💡 :note-caption: ℹ️ :important-caption: ❗ :caution-caption: 🔥 :warning-caption: ⚠️

[quote]

A PrimeFaces theme to admin them all!

image:https://github.com/adminfaces/admin-theme/actions/workflows/ci.yml/badge.svg[Build Status, link=https://github.com/adminfaces/admin-theme/actions/workflows/ci.yml] image:https://img.shields.io/maven-central/v/com.github.adminfaces/admin-theme.svg?label=Maven%20Central["Maven Central",link="https://search.maven.org/search?q=g:com.github.adminfaces%20AND%20a:admin-theme"] image:https://badges.gitter.im/Join%20Chat.svg[link="https://gitter.im/adminfaces?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]

This project is a http://primefaces.org/themes[Primefaces^] admin theme based on https://almsaeedstudio.com/themes/AdminLTE/index2.html[Admin LTE^] and http://getbootstrap.com[Bootstrap^].

image:messages.png[link="https://github.com/adminfaces/admin-theme/blob/master/messages.png?raw=true"]

== Introduction

This theme is a css file containing Admin LTE and Bootstrap as well as customized Primefaces components to make them look like AdminLTE and Bootstrap.

== Usage

. Just add it to your application classpath:
+
[source,xml]

TIP: If you use https://github.com/adminfaces/admin-template[Admin Template^] there is no need to add admin-theme to your classpath neither the web.xml entry.

== Architecture

The theme uses http://lesscss.org/[less^] as css pre-processor. Each PrimeFaces component has its own less file:

.src/main/resources/less

├── admin-lte
│ |
│ ├── bootstrap <1>
│ │
│ ├── skins <2>
│ │
│ └── admin lte less files
│
├── primefaces-admin
│ |
│ ├─ components <3>
│ │ |
│ │ ├── accordeon.less
│ │ │
│ │ ├── autocomplete.less
│ │ │
│ │ └── etc...
│ │
│ ├─ theme.less <4>
│ │
└─ variables.less

<1> Bootstrap variables and https://css-tricks.com/snippets/css/useful-css3-less-mixins/[mixins^] are used as reference in AdminLTE and admin theme less files <2> Built in skins <3> PrimeFaces components <4> Components and Admin-LTE less files are included in theme.less

After compilation it will generate the theme.css with Admin-LTE, Bootstrap and Primefaces components.

NOTE: Bootstrap.css (from src/META-INF/resources) is included in theme.less but can be removed via maven classifiers

NOTE: Bootstrap less is not maintained in this project only it's mixins.

== Theme classifiers

This project uses http://stackoverflow.com/questions/20909634/what-is-the-purpose-of-classifier-tag-in-maven[maven classifiers^] to offer multiple faces (pum intended) of Admin Theme. Below is the description of each classifier and how to use it.

=== Default (no classifier) The default theme comes compressed, with Bootstrap (3.3.7) embedded and uses JSF resource handling for loading images and web fonts.

.Maven usage
[source,xml]

=== Dev classifier

The dev classifier will bring a theme.css without minification.

.Maven usage
[source,xml]

=== Without Bootstrap classifier

The without-bootstrap classifier will bring a theme.css without bootstrap embedded so it's up to the developer to provide Bootstrap within the application.

.Maven usage
[source,xml]

=== Without JSF classifier

The without-jsf classifier will bring a theme.css without JSF resource handling so the theme can be used on projects (derived from PrimeFaces) without JSF like Prime React, PrimeUI or PrimeNG.

.Maven usage
[source,xml]

=== No Fonts classifier

Since v1.0.0-RC16 web fonts such as glyphicons and Source Sans Pro were embedded inside the theme instead of being queried from a https://en.wikipedia.org/wiki/Content_delivery_network[CDN^].

This makes the theme work offline or in environments with limited access to the internet but on the other hand results in a larger jar file, ~1MB against ~200kb when fonts are not in the theme.

So if you want a thinner theme you can use the no-fonts classifier:

[source,xml]

== Avoiding theme caching

Whenever the theme is updated to a new version in the project users may have to clear their browser caches to get the changes of the new theme. Sometimes a theme update even introduces conflicts and only clearing browser cache fixes them.

To solve this issues you can use a theme classifier called no-cache:

.pom.xml
[source,xml]

This classifier appends the theme version to the name of theme so you need to change the theme name in web.xml:

.web.xml
[source,xml]

TIP: There is also a no-cache-no-fonts classifier combining both approaches.

== Development

To get your hands dirty with admin theme it is recommended to use http://github.com/adminfaces/admin-designer[Admin Designer^] in combination with http://brackets.io/[Brackets] or any tool that compile less files to css on save.

Using designer, which is backed by http://wildfly-swarm.io/[Wildfly Swarm^], plus brackets will let you change the components less files and see the results instantly.

NOTE: theme.less is already brackets aware so you just need to change any component less file, save it and see the results in Admin Designer.

== Demo