Admin Template

A JSF fully responsive admin template based on Primefaces, Admin LTE and Bootstrap.

Table of Contents

• 1. Features
• 2. Usage
• 3. Configuration
• 4. Admin Session
• 5. Snapshots

1. Features

Below is a non exhaustive list of notable features brought out of the box by this template:

• Fully responsive

  • Its based on Bootstrap and AdminLTE two well tested and solid frameworks

• Enhanced mobile experience (below features are enabled only on small screens)

  • Material design load bar

  • Ripple effect based on materialize css
    

  • Touch enabled menu to slide in/out and show navbar on scroll up
    

  • Scroll to top

• Automatically activates (highlight) menu based on current page
  

• Custom error pages

• Configurable, see Configuration

• Breadcrumb based navigation

• Back to previous screen when logging in again after session expiration (or accessing a page via url without being logged in)

ℹ️	Most of the above features can be disabled via configuration mechanism;

2. Usage

First include it in your classpath:

<dependency>
    <groupId>com.github.adminfaces</groupId>
    <artifactId>admin-template</artifactId>
    <version>version</version>
</dependency>

❗

Admin template will bring the following transitive dependencies: <dependency> <groupId>com.github.adminfaces</groupId> <artifactId>admin-theme</artifactId> <version>version</version> </dependency> <dependency> <groupId>org.primefaces</groupId> <artifactId>primefaces</artifactId> <version>6.1</version> </dependency> <dependency> <groupId>org.omnifaces</groupId> <artifactId>omnifaces</artifactId> <version>2.1</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>1.7.22</version> </dependency> Of cource you can override them in your pom.xml as needed.

Now you can use it in your JSF pages:

<?xml version="1.0" encoding="UTF-8"?>
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
                xmlns:ui="http://java.sun.com/jsf/facelets"
                xmlns:p="http://primefaces.org/ui"
                template="/admin.xhtml"> (1)

    <ui:define name="head">
        <title>Admin Starter</title>
    </ui:define>

    <ui:define name="logo-lg">
        Admin Starter
    </ui:define>

    <ui:define name="logo-mini">
        Admin
    </ui:define>

    <ui:define name="menu">
        <ul class="sidebar-menu">
            <li>
                <p:link href="/index.xhtml" onclick="clearBreadCrumbs()">
                    <i class="fa fa-home"></i>
                    <span>Home</span>
                </p:link>
            </li>
	        <li class="header">
	            General
	        </li>
	        <li>
	            <p:link href="/car-list.xhtml">
	                <i class="fa fa-car"></i>
	                <span>Cars</span>
	            </p:link>
	        </li>
        </ul>
     </ui:define>

    <ui:define name="top-menu">
        <ui:include src="/includes/top-bar.xhtml"/>
    </ui:define>

      <ui:define name="title">
        <h2 class="align-center">
            Welcome to the <span class="text-aqua"> <i><a href="https://github.com/adminfaces/admin-starter" target="_blank"
                                                          style="text-transform: none;text-decoration: none"> AdminFaces Starter</a></i></span> Project!
            <br/>
            <small>Integrating <p:link value="Primefaces" href="http://primefaces.org"/>, <p:link value="Bootstrap"
                                                                                                  href="http://getbootstrap.com/"/> and
                <p:link value="Admin LTE" href="https://almsaeedstudio.com/themes/AdminLTE/index2.html/"/> into your
                <p:link value="JSF" href="https://javaserverfaces.java.net/"/> application.
            </small>
        </h2>
    </ui:define>

    <ui:define name="description">
        A page description
    </ui:define>

    <ui:define name="body">
    	<h2>Page body</h2>
    </ui:define>


    <ui:define name="footer">
          <a target="_blank"
           href="https://github.com/adminfaces/">
            Copyright (C) 2017 - AdminFaces
        </a>

        <div class="pull-right hidden-xs" style="color: gray">
            <i>1.0.0</i>
        </div>
    </ui:define>


</ui:composition>

1. /admin.xhtml is the location of the template

The above page definition renders as follows:

There are also other regions defined in admin.xhtml template, see here.

3. Configuration

Template configuration is made through admin-config.properties file present in src/main/resources folder.

Here are the default values as well as its description:

admin.loginPage=login.xhtml (1)
admin.indexPage=index.xhtml (2)
admin.dateFormat=MM/dd/yyyy HH:mm:ss (3)
admin.templatePath=admin.xhtml (4)
admin.breadcrumbSize=5 (5)
admin.renderMessages=true (6)
admin.renderAjaxStatus=true (7)
admin.disableFilter=false (8)
admin.renderBreadCrumb=true (9)
admin.enableSlideMenu=true (10)
admin.enableRipple=true (11)
admin.rippleElements= .ripplelink,button.ui-button,.ui-selectlistbox-item,.ui-multiselectlistbox-item,.ui-selectonemenu-label,.ui-selectcheckboxmenu,\
.ui-autocomplete-dropdown, .ui-autocomplete-item ... (the list goes on) (12)
admin.skin=skin-blue (13)
admin.autoShowNavbar=true (14)
admin.ignoredResources= (15)

1. login page location (relative to webapp). It you only be used if you configure Admin Session.

2. index page location. User will be redirected to it when it access app root (contextPath/).

3. Date format used in error page (500.xhtml).

4. facelets template to be used on build in admin-template pages like 500.xhtml, 404.xhtml, viewexpired.xhtml, see [Error Pages]. By default it uses admin.xhtml but you can define any template (e.g one that extends admin.xhtml).

5. Number of breadcrumbs to queue before removing the older ones.

6. When false, p:messages defined in admin template will not be rendered.

7. When false ajaxStatus, which triggers the loading bar on every ajax request, will not be rendered.

8. Disables AdminFilter, responsible for redirecting user after session timeout, sending user to logon page when it is not logged in among other things.

9. When false, the breadCrumb component, declared in admin template, will not be rendered.

10. If true will make left menu touch enable (can be closed or opened via touch). Can be enable/disabled per page with <ui:param name="enableSlideMenu" value="false".

11. When true it will create a wave/ripple effect on elements specified by rippleElements.

12. A list of comma separated list of (jquery) selector which elements will be affected by ripple effect.

13. Default template skin

14. Automatic shows navbar when users scrolls page up (on small screens). Can be enable/disabled per page with <ui:param name="autoShowNavbar" value="false".

15. Comma separated resources (pages or urls) to be skiped by AdminFilter. Ex: /rest,/pages/car-list.xhtml

❗	You don’t need to declare all values in your admin-config.properties, you can specify only the ones you need in order to change.

4. Admin Session

AdminSession is a simple session scoped bean which controls whether user is logged in or not.

 public boolean isLoggedIn(){
        return isLoggedIn; //always true by default
    }

By default the user is always logged in and you need to override it (by using bean specialization or calling setIsLoggedIn() method) to change its value.

When isLoggedIn is false you got the following mechanisms activated:

1. Access to any page, besides the login, redirects user to login;

2. When session is expired user is redirected to logon and current page (before expiration) is saved so user is redirected back to where it was before session expiration.

ℹ️	It is up to you to decide whether the user is logged in or not.

5. Snapshots

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>