Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/adminfaces/admin-template
JSF responsive admin template based on Bootstrap and AdminLTE
https://github.com/adminfaces/admin-template
adminlte bootstrap3 jsf material-design responsive
Last synced: 6 days ago
JSON representation
JSF responsive admin template based on Bootstrap and AdminLTE
- Host: GitHub
- URL: https://github.com/adminfaces/admin-template
- Owner: adminfaces
- License: mit
- Created: 2017-01-08T11:29:05.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2023-05-07T12:16:07.000Z (over 1 year ago)
- Last Synced: 2024-12-21T10:14:26.950Z (13 days ago)
- Topics: adminlte, bootstrap3, jsf, material-design, responsive
- Language: Java
- Homepage: https://adminfaces.github.io/docs/latest/#admin_template
- Size: 1.25 MB
- Stars: 212
- Watchers: 19
- Forks: 102
- Open Issues: 11
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE.txt
Awesome Lists containing this project
README
= Admin Template
:page-layout: base
:source-language: java
:icons: font
:linkattrs:
:sectanchors:
:sectlink:
:numbered:
:doctype: book
:toc: preamble
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
[quote]
____
The `admin` of JSF templates!
____
image:https://github.com/adminfaces/admin-template/actions/workflows/ci.yml/badge.svg[Build Status, link=https://github.com/adminfaces/admin-template/actions/workflows/ci.yml]
image:https://img.shields.io/maven-central/v/com.github.adminfaces/admin-template.svg?label=Maven%20Central["Maven Central",link="https://search.maven.org/search?q=g:com.github.adminfaces%20AND%20a:admin-template"]
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"]
A https://javaserverfaces.java.net/[JSF^] *fully responsive* `admin template` based on http://primefaces.org/themes[Primefaces^], https://almsaeedstudio.com/themes/AdminLTE/index2.html[Admin LTE^] and http://getbootstrap.com[Bootstrap^].
== 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
** Material design load bar
** Material design http://admin-showcase-admin-showcase.7e14.starter-us-west-2.openshiftapps.com/showcase/pages/components/buttons.xhtml?material=true[flat buttons^]
** Ripple effect based on http://materializecss.com/waves.html[materialize css^] +
image:https://user-images.githubusercontent.com/1592273/27104868-d9bfb33e-5063-11e7-83be-2201a3f8cda5.gif[]
** Touch enabled menu to slide in/out and show navbar on scroll up +
image:https://cloud.githubusercontent.com/assets/1592273/25071807/dd37121e-2296-11e7-855c-8f20b59dcf5f.gif[]
** Auto show and hide navbar based on page scroll
** Scroll to top
* Automatically activates (highlight) menu based on current page +
image:https://github.com/adminfaces/admin-docs/raw/master/src/docs/images/menu-highlight.png[link="https://github.com/adminfaces/admin-docs/blob/master/src/docs/images/menu-highlight.png?raw=true"]
* Custom <>
* Two menu modes, left and horizontal based menu
* Configurable, see <>
* http://admin-showcase-admin-showcase.7e14.starter-us-west-2.openshiftapps.com/showcase/pages/layout/breadcrumb.xhtml[Breadcrumb^] based navigation
* Layout customization via <>
* High resolution and responsible icons based on Glyphycons and FontAwesome
* Menu items search +
image:https://github.com/adminfaces/admin-docs/raw/master/src/docs/images/menu-search.png[link="https://github.com/adminfaces/admin-docs/blob/master/src/docs/images/menu-search.png?raw=true"]
* Builtin `dark` and `light` skins
* Back to previous screen when logging in again after session expiration (or accessing a page via url without being logged in)
NOTE: Most of the above features can be enabled/disabled via <> mechanism.
== Usage
First include it in your classpath:
----
com.github.adminfaces
admin-template
version
----
[WARNING]
====
Admin template will bring the following transitive dependencies:
----
com.github.adminfaces
admin-theme
version
org.primefaces
primefaces
12.0
org.omnifaces
omnifaces
4.1
----
Which you can override in your pom.xml as needed.
====
With the template dependency in classpath now you can use `admin` facelets template into your JSF pages.
=== Example
Consider the following sample page:
[source,html]
----
<1>
Admin Starter
Admin Starter
Admin
Welcome to the AdminFaces Starter Project!
Integrating , and
into your
application.
A page description
Page body
Copyright (C) 2017 - AdminFaces
----
<1> /admin.xhtml is the location of the template
The above page definition renders as follows:
image:template-example.png[]
There are also other regions defined in admin.xhtml template, https://github.com/adminfaces/admin-template/blob/master/src/main/resources/META-INF/resources/admin.xhtml[see here^].
[TIP]
====
A good practice is to define a template on your application which extends the admin template, see https://github.com/adminfaces/admin-starter/blob/master/src/main/webapp/WEB-INF/templates/template.xhtml[admin-starter application template here^].
So in your pages you use your template instead of admin.
====
== Application template
Instead of repeating sections like *menu*, *logo*, *head* and *footer* on every page we can create a template inside our application which uses `admin.xhtml` as template:
./WEB-INF/templates/template.xhtml
[source,html]
----
Admin Starter
Admin Starter
Admin
Copyright (C) 2017 - AdminFaces
----
And now the page can just define its content and title:
./webapp/mypage.xhtml
[source,xml]
----
A page title
A page description
Page body
----
=== Switching between *left menu* and *top menu* templates
AdminFaces supports two layout modes, one is *left based menu* and the other is *top based menu*.
The user can change layout modes via <> but to make it work you have to use *LayoutMB* to define page template:
./webapp/mypage.xhtml
[source,xml]
----
----
As a *convention over configuration* LayoutMB will load templates from the following locations:
* `webapp/WEB-INF/templates/template.xhtml` and `resources/META-INF/resources/templates/template.xhtml` for the `left menu` based template
* `webapp/WEB-INF/templates/template-top.xhtml` and `resources/META-INF/resources/templates/template-top.xhtml` for horizontal menu layout.
NOTE: If you don't provide a <> then built in `admin.xhtml` and `admin-top.xhtml` templates will be used.
See admin-starer templates for a reference: https://github.com/adminfaces/admin-starter/tree/master/src/main/webapp/WEB-INF/templates
== 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= <3>
admin.breadcrumbSize=5 <4>
admin.renderMessages=true <5>
admin.renderAjaxStatus=true <6>
admin.disableFilter=false <7>
admin.renderBreadCrumb=true <8>
admin.enableSlideMenu=true <9>
admin.enableRipple=true <10>
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) <11>
admin.skin=skin-blue <12>
admin.autoShowNavbar=true <13>
admin.ignoredResources= <14>
admin.loadingImage=ajaxloadingbar.gif <15>
admin.extensionLessUrls=false <16>
admin.renderControlSidebar=false <17>
admin.controlSidebar.showOnMobile=false <18>
admin.controlSidebar.leftMenuTemplate=true <19>
admin.controlSidebar.fixedLayout=false <20>
admin.controlSidebar.boxedLayout=false <21>
admin.controlSidebar.sidebarCollapsed=false <22>
admin.controlSidebar.expandOnHover=false <23>
admin.controlSidebar.fixed=false <24>
admin.controlSidebar.darkSkin=true <25>
admin.rippleMobileOnly=true <26>
admin.renderMenuSearch=true <27>
admin.autoHideMessages=true <28>
admin.messagesHideTimeout=2500 <29>
admin.iconsEffect=true <30>
----
<1> login page location (relative to webapp). It you only be used if you configure <>.
<2> index page location. User will be redirected to it when it access app root (contextPath/).
<3> Date format used in error page (http://admin-showcase-admin-showcase.7e14.starter-us-west-2.openshiftapps.com/showcase/500.xhtml[500.xhtml^]), by default it is JVM default format.
<4> Number of breadcrumbs to queue before removing the older ones.
<5> When false, p:messages defined in admin template will not be rendered.
<6> When false ajaxStatus, which triggers the loading bar on every ajax request, will not be rendered.
<7> Disables AdminFilter, responsible for redirecting user after session timeout, sending user to logon page when it is not logged in among other things.
<8> When false, the breadCrumb component, declared in admin template, will not be rendered.
<9> If true will make left menu touch enable (can be closed or opened via touch). Can be enable/disabled per page with When true it will create a http://materializecss.com/waves.html#![wave/ripple effect^] on elements specified by `rippleElements`.
<11> A list of comma separated list of (jquery) selector which elements will be affected by ripple effect.
<12> Default template skin.
<13> Automatic shows navbar when users scrolls page up `on small screens`. Can be enable/disabled per page with Comma separated resources (pages or urls) to be skiped by AdminFilter. Ex: /rest, /pages/car-list. Note that by default the filter skips pages under *CONTEXT/public/* folder.
<15> image used for the loading popup. It must be under `webapp/resources/images` folder.
<16> Removes extension suffix from breadCrumb links.
<17> When true it will activate <> component.
<18> When true control sidebar will be also rendered on mobile devices.
<19> Switches layout between left (default) and top menu.
<20> Toggles fixed layout where navbar is fixed on the page.
<21> Toggles boxed layout which is helpful when working on large screens because it prevents the site from stretching very wide.
<22> When true left sidebar will be collapsed.
<23> When true left sidebar will expand on mouse hover.
<24> When true control sidebar will be fixed on the page.
<25> Changes control sidebar skin between `dark` and `light`.
<26> When true the ripple effect will be enabled only on mobile (small) screens.
<27> Enables or disables menu search.
<28> If true PrimeFaces *info* messages will be hidden after a certain timeout.
<29> Timeout to hide info messages. Note that the timeout is composed by `configured timeout + number of words` in message.
<30> Enables material effect when icons (e.g modal close, calendar) are clicked.
IMPORTANT: You don't need to declare all values in your admin-config.properties, you can specify only the ones you need to change.
TIP: Since vRC16 config properties can be passed as Java `system properties`.
NOTE: Controlsidebar entries (admin.controlSidebar.xxx) will be used only for initial/default values because they will be stored on browser local storage as soon as user changes them.
== 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 https://github.com/adminfaces/admin-starter/blob/2659e762271f9e1864bd2290f3dbf5018087eccd/src/main/java/com/github/adminfaces/starter/infra/security/LogonMB.java#L28[bean specialization^] or via injection and calling `setIsLoggedIn()` method) to change its value, see <>.
When isLoggedIn is `false` you got the following mechanisms activated:
. Access to any page, besides the login, redirects user to login;
. 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.
NOTE: It is up to you to decide whether the user is logged in or not.
=== Overriding AdminSession
There are two ways to override AdminSession default value which is <> and <>.
==== AdminSession Specialization
A simple way to change AdminSession logged in value is by extending it:
[source,java]
----
import jakarta.enterprise.context.SessionScoped;
import jakarta.enterprise.inject.Specializes;
import com.github.adminfaces.template.session.AdminSession;
import org.omnifaces.util.Faces;
import java.io.Serializable;
@SessionScoped
@Specializes
public class LogonMB extends AdminSession implements Serializable {
private String currentUser;
private String email;
private String password;
private boolean remember;
public void login() throws IOException {
currentUser = email;
addDetailMessage("Logged in successfully as " + email + "");
Faces.getExternalContext().getFlash().setKeepMessages(true);
Faces.redirect("index.xhtml");
}
@Override
public boolean isLoggedIn() {
return currentUser != null;
}
//getters&setters
}
----
=== AdminSession Injection
Another way is to inject it into your security authentication logic:
[source,java]
----
import com.github.adminfaces.template.session.AdminSession;
import org.omnifaces.util.Messages;
import org.omnifaces.util.Faces;
@SessionScoped
@Named("authorizer")
public class CustomAuthorizer implements Serializable {
private String currentUser;
@Inject
AdminSession adminSession;
public void login(String username) {
currentUser = username;
adminSession.setIsLoggedIn(true);
Messages.addInfo(null,"Logged in sucessfully as "+username+"");
Faces.redirect("index.xhtml");
}
}
----
IMPORTANT: As isLoggedIn is `true by default` you need to set it to false on application startup so user is redirected to login page. This step is not needed when <>.
== Error Pages
The template comes with custom error pages like `403`, `404`, `500`, `ViewExpired` and `OptimisticLock`.
.500
User is going to be redirected to http://admin-showcase-admin-showcase.7e14.starter-us-west-2.openshiftapps.com/showcase/500.xhtml[*500.xhtml*^] whenever a _500_ response code is returned in a request.
The page will also be triggered when a `Throwable` is raised (and not catch).
Here is how 500 page look like:
image::https://raw.githubusercontent.com/adminfaces/admin-docs/master/src/docs/images/500.png[]
.403
User is redirected to http://admin-showcase-admin-showcase.7e14.starter-us-west-2.openshiftapps.com/showcase/403.xhtml[403.xhtml^] whenever a _403_ response code is returned in a request. The page will also be triggered when a `com.github.adminfaces.template.exception.AccessDeniedException` is raised.
image::https://raw.githubusercontent.com/adminfaces/admin-docs/master/src/docs/images/403.png[]
.404
User will be redirected to http://admin-showcase-admin-showcase.7e14.starter-us-west-2.openshiftapps.com/showcase/non-existing.xhtml[404.xhtml^] whenever a 404 response code is returned from a request.
image::https://raw.githubusercontent.com/adminfaces/admin-docs/master/src/docs/images/404.png[]
.ViewExpired
When a JSF `javax.faces.application.ViewExpiredException` is raised user will be redirected to http://admin-showcase-admin-showcase.7e14.starter-us-west-2.openshiftapps.com/showcase/expired.xhtml[expired.xhtml^].
image::https://raw.githubusercontent.com/adminfaces/admin-docs/master/src/docs/images/expired.png[]
.OptimisticLock
When a JPA `javax.persistence.OptimisticLockException` is thrown user will be redirected to http://admin-showcase-admin-showcase.7e14.starter-us-west-2.openshiftapps.com/showcase/optimistic.xhtml[optimistic.xhtml^].
image::https://raw.githubusercontent.com/adminfaces/admin-docs/master/src/docs/images/optimistic.png[]
=== Providing custom error pages
You can provide your own custom pages (and other status codes) by configuring them in web.xml, example:
[source,xml]
----
404
/404.xhtml
500
/500.xhtml
java.lang.Throwable
/500.xhtml
----
=== Overriding error pages
You can also override error pages by placing the pages (with same name) described in <> section on the root of your application (`webapp/`).
== Internationalization
Labels in <> and <> are provided via http://docs.oracle.com/javaee/6/tutorial/doc/bnaxw.html#bnaxy[JSF resource bundle] mechanism.
Following are the default labels in admin resource bundle:
.src/main/resources/admin.properties
----
#general
admin.version=${project.version}
label.home=Home
label.go-back=Go back to
label.or-to=or to
label.previous-page=previous page
#403
label.403.header=403
label.403.message=Access denied! You do not have access to the requested page.
#404
label.404.header=404
label.404.message=Oops! Page not found
#500
label.500.header=500
label.500.message=Oops! Something went wrong
label.500.title=Unexpected error
label.500.detail=Details
#expired
label.expired.title=View expired
label.expired.message= The requested page could not be recovered.
label.expired.click-here= Click here to reload the page.
#optimistic
label.optimistic.title=Record already updated
label.optimistic.message= The requested record has been already updated by another user.
label.optimistic.click-here= Click here to reload the updated record from database.
#controlsidebar
controlsidebar.header=Layout Options
controlsidebar.label.restore-defaults=Restore defaults
controlsidebar.label.menu-horientation=Left menu layout
controlsidebar.txt.menu-horientation=Toggle menu orientation between left and top menu.
controlsidebar.label.fixed-layout=Fixed Layout
controlsidebar.txt.fixed-layout=Activate the fixed layout, if checked the top bar will be fixed on the page.
controlsidebar.label.boxed-layout=Boxed Layout
controlsidebar.txt.boxed-layout=Activate the boxed layout.
controlsidebar.label.sidebar-collapsed=Collapsed Sidebar
controlsidebar.txt.sidebar-collapsed=If checked the sidebar menu will be collapsed.
controlsidebar.label.sidebar-expand-hover=Sidebar Expand on Hover
controlsidebar.txt.sidebar-expand-hover=If checked the left sidebar will expand on hover.
controlsidebar.label.sidebar-slide=Control Sidebar fixed
controlsidebar.txt.sidebar-slide=If checked control sidebar will be fixed on the page.
controlsidebar.label.sidebar-skin=Dark Sidebar Skin
controlsidebar.txt.sidebar-skin=If checked dark skin will be used for control sidebar, otherwise light skin will be used.
controlsidebar.header.skins=Skins
#menu search
menu.search.placeholder=Search menu items...
----
[TIP]
====
You can provide your own language bundle adding a file named _admin_YOUR_LANGUAGE.properties_ in your application `resources` folder.
Don't forget to add it as `supported locale` in *faces-config*, see https://github.com/adminfaces/admin-template/blob/02c0db5d9ff567c803e7e83f336f8a7308e9d4ec/src/main/resources/META-INF/faces-config.xml#L9[example here^].
====
IMPORTANT: You can contribute your language locale to AdminFaces, https://github.com/adminfaces/admin-template/tree/master/src/main/resources[check here^] the current supported locales.
== Control Sidebar
ControlSidebar is a component which provides a panel so user can `customize` the template layout:
image::https://raw.githubusercontent.com/adminfaces/admin-docs/master/src/docs/images/controlsidebar.png[]
Options selected by user are stored on `browser local storage` so they are remembered no matter the user logs off the application.
=== Usage
To enable the control sidebar you need to add the following entry in `src/main/resources/admin-config.properties`:
----
admin.renderControlSidebar=true
----
And then add a link or button on your page which opens the sidebar. The link or button must use `data-toggle` attribute:
----
----
On admin-starter the link is located on https://github.com/adminfaces/admin-starter/blob/c8adbe5e692171b144b93292e14ea203b654a13b/src/main/webapp/includes/top-bar.xhtml#L58[top-bar.xhtml^].
{link-admin-showcase-openshift}/pages/layout/controlsidebar.xhtml[Click here^] to see controlsidebar in action on admin showcase.
By default the control sidebar comes only with the configuration tab but you can define additional tabs by defining `controlsidebar-tabs` and `controlsidebar-content` on your template. An example can be found on https://github.com/adminfaces/admin-starter/blob/c8adbe5e692171b144b93292e14ea203b654a13b/src/main/webapp/WEB-INF/templates/template.xhtml#L38[admin-starter template^].
[TIP]
====
ControlSidebar is hidden on mobile devices by default. You can change this on `admin-config.properties`:
-----
admin.controlSidebar.showOnMobile=true
-----
Also don't forget to remove the `hidden-sm hidden-xs` classes from the button/link that opens the sidebar:
====
== JakartaEE migration
Since version `1.6.0` admin-template supports jakartaEE by default, https://github.com/adminfaces/admin-starter/blob/dda0a159fe9d604cbccecb9beab2b60f958569d0/pom.xml#L18-L34[see admin-starter^] for a sample project.
== Docs
https://adminfaces.github.io/docs/latest/#admin_template
== Snapshots
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
----