adminfaces/admin-theme

= 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]

com.github.adminfaces admin-theme   1.0.0 ---- + . Add this context-param in your web.xml:

---

primefaces.THEME admin ----

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]

com.github.adminfaces admin-theme 1.0.0 ----

=== Dev classifier

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

.Maven usage
[source,xml]

com.github.adminfaces admin-theme 1.0.0 dev ----

=== 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]

com.github.adminfaces admin-theme 1.0.0 without-bootstrap ----

=== 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]

com.github.adminfaces admin-theme 1.0.0 without-jsf ----

=== 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]

com.github.adminfaces admin-theme 1.0.0 no-fonts ----

== 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]

com.github.adminfaces admin-theme 1.0.0 no-cache ----

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]

primefaces.THEME admin-1.0.0 ----

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

• https://github.com/adminfaces/admin-showcase[Admin Showcase^]

• https://github.com/adminfaces/admin-starter[Admin Starter^]

== Docs

https://adminfaces.github.io/site/docs/latest/#admin_theme

== Snapshot

Snapshots are published to https://oss.sonatype.org/content/repositories/snapshots/com/github/adminfaces/[maven central^] on each commit, to use it just declare the repository below on your pom.xml:

[source,xml]

snapshots libs-snapshot https://oss.sonatype.org/content/repositories/snapshots ----