Primefaces admin theme based on Admin LTE and Bootstrap
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github update issue template Apr 3, 2018
src/main/resources fixes #213 Oct 17, 2018
.gitignore adds .gitignore and removes /target Jan 8, 2017
.travis.yml do not deploy artifacts when build is triggered by pull requests Oct 17, 2018
LICENSE.txt license update Feb 19, 2018
README.adoc readme update Oct 17, 2018
maven-install-local.sh refs #183, #184 Jul 17, 2018
maven-install.sh refs #183, #184 Jul 17, 2018
messages.png readme update Jul 3, 2017
nb-configuration.xml refs #141 Apr 13, 2018
pom.xml fixes #213 Oct 17, 2018
settings.xml travis config Jan 19, 2017

README.adoc

Admin Theme

1. 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.

2. Usage

  1. Just add it to your application classpath:

    <dependency>
        <groupId>com.github.adminfaces</groupId>
        <artifactId>admin-theme</artifactId>
        <version>1.0.0-RC19</version>
    <!--<classifier>dev</classifier> uncompressed theme.css-->
    </dependency>
  2. Add this context-param in your web.xml:

<context-param>
    <param-name>primefaces.THEME</param-name>
    <param-value>admin</param-value>
</context-param>
💡
If you use Admin Template there is no need to add this project to your classpath neither the web.xml entry.

3. Architecture

The theme uses 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 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.

ℹ️
Bootstrap.css (from src/META-INF/resources) is included in theme.less but can be removed via maven classifiers
ℹ️
Bootstrap less is not maintained in this project only it’s mixins.

4. Theme classifiers

This project uses maven classifiers to offer multiple faces (pum intended) of Admin Theme. Below is the description of each classifier and how to use it.

4.1. 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
<dependency>
    <groupId>com.github.adminfaces</groupId>
    <artifactId>admin-theme</artifactId>
    <version>1.0.0-RC19</version>
</dependency>

4.2. Dev classifier

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

Maven usage
<dependency>
    <groupId>com.github.adminfaces</groupId>
    <artifactId>admin-theme</artifactId>
    <version>1.0.0-RC19</version>
    <classifier>dev</classifier>
</dependency>

4.3. 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
<dependency>
    <groupId>com.github.adminfaces</groupId>
    <artifactId>admin-theme</artifactId>
    <version>1.0.0-RC19</version>
    <classifier>without-bootstrap</classifier>
</dependency>

4.4. 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
<dependency>
    <groupId>com.github.adminfaces</groupId>
    <artifactId>admin-theme</artifactId>
    <version>1.0.0-RC19</version>
    <classifier>without-jsf</classifier>
</dependency>

4.5. No Fonts classifier

Since v1.0.0-RC16 web fonts such as glyphicons and Source Sans Pro are embedded inside the theme instead of being queried from a 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:

<dependency>
    <groupId>com.github.adminfaces</groupId>
    <artifactId>admin-theme</artifactId>
    <version>1.0.0-RC19</version>
    <classifier>no-fonts</classifier>
</dependency>

5. 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
<dependency>
    <groupId>com.github.adminfaces</groupId>
    <artifactId>admin-theme</artifactId>
    <version>1.0.0-RC19</version>
    <classifier>no-cache</classifier>
</dependency>

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

web.xml
<context-param>
    <param-name>primefaces.THEME</param-name>
    <param-value>admin-1.0.0-RC19</param-value>
</context-param>
💡
There is also a no-cache-no-fonts classifier combining both approaches.

6. Development

To get your hands dirty with admin theme it is recommended to use Admin Designer in combination with Brackets or any tool that compile less files to css on save.

Using designer, which is backed by Wildfly Swarm, plus brackets will let you change the components less files and see the results instantly.

ℹ️
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.

9. Snapshot

Snapshots are published to maven central on each commit, to use it just declare the repository below on your pom.xml:

<repositories>
    <repository>
        <snapshots/>
        <id>snapshots</id>
        <name>libs-snapshot</name>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
</repositories>