LightAdmin - [PoC] Pluggable CRUD UI library for Java web applications

The primary goal of this PoC project is to speed up application development by bringing pluggable fully operational data management back-end for JPA based applications and to relieve your codebase for more important stuff.

Features

• DSL configurations: Allows developers to easily configure their administration user interface
• Displaying persistent entities: Customizable Listing & Quick Views with paging & sorting capabilities
• CRUD operations: Complete entities manipulation support (including their associations)
• Automatic Validation: JSR-303 annotation-based validation rules support
• Search: Allows users to search entities by text fields, dates, numeric values & associations
• Filtering Scopes: Use scopes to filter data by predefined criteria
• Pluggable Security: Authentication based on Spring Security
• REST API: Enriching your application with REST API based on Spring Data REST
• Easy integration: Servlet 2.5/3.0 web applications supported

Integration examples

• LightAdmin and Spring Boot
• LightAdmin and JHipster
• LightAdmin running on Heroku

Documentation & Support

• Web site: lightadmin.org
• Documentation & Guides: lightadmin.org/getting-started/
• Wiki: github.com/la-team/light-admin/wiki
• Live demo: lightadmin.org/demo
• CI Server: lightadmin.org/jenkins
• Use Google Groups for posting questions: groups.google.com/group/lightadmin
• Use Stack Overflow for posting questions with lightadmin tag
• Contact LightAdmin Team directly on Twitter: @lightadm_team

Bug Reports

• Bug Reports: github.com/la-team/light-admin/issues

License

• LightAdmin is released under version 2.0 of the Apache License.

Contribute

You're interested in contributing to LightAdmin? AWESOME. Here are the basic steps:

• Fork LightAdmin from here: http://github.com/la-team/light-admin
• Clone your fork
• Hack away
• If necessary, rebase your commits into logical chunks, without errors
• Verify your code by running the test suite, and adding additional tests if able
• Push the branch up to GitHub
• Send a pull request to the la-team/light-admin project

We'll do our best to get your changes in!

Getting started

Declare maven dependency for using with Spring 4.0.X directly from Maven Central

<dependency>
  <groupId>org.lightadmin</groupId>
  <artifactId>lightadmin</artifactId>
  <version>1.2.0.RC1</version>
</dependency> 

or

<dependency>
  <groupId>org.lightadmin</groupId>
  <artifactId>lightadmin</artifactId>
  <version>1.2.0.BUILD-SNAPSHOT</version>
</dependency> 

For snapshots and LightAdmin compatible with Spring 3.2.X, please declare LA Nexus repositories:

<repositories>
  <repository>
    <id>lightadmin-nexus-releases</id>
    <url>http://lightadmin.org/nexus/content/repositories/releases</url>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </releases>
  </repository>
  <repository>
    <id>lightadmin-nexus-snapshots</id>
    <url>http://lightadmin.org/nexus/content/repositories/snapshots</url>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>  
</repositories>

And dependency

<dependency>
  <groupId>org.lightadmin</groupId>
  <artifactId>lightadmin</artifactId>
  <version>1.0.0.M2</version>
</dependency> 

Enable LightAdmin web-module in your web.xml if you have one:

<context-param>
  <param-name>light:administration:base-url</param-name>
  <param-value>/admin</param-value>
</context-param>

<context-param>
  <param-name>light:administration:security</param-name>
  <param-value>true</param-value>
</context-param>

<context-param>
  <param-name>light:administration:base-package</param-name>
  <param-value>[package with @Administration configurations, ex.: org.lightadmin.demo.config]</param-value>
</context-param>

Or enable LightAdmin web-module in your WebApplicationInitializer:

@Override
public void onStartup(ServletContext servletContext) throws ServletException {
  servletContext.setInitParameter(LIGHT_ADMINISTRATION_BASE_URL, "/admin");
  servletContext.setInitParameter(LIGHT_ADMINISTRATION_BACK_TO_SITE_URL, "http://lightadmin.org");
  servletContext.setInitParameter(LIGHT_ADMINISTRATION_BASE_PACKAGE, "org.lightadmin.administration");

  super.onStartup(servletContext);
}

Include your JPA persistence provider of choice (Hibernate, EclipseLink, OpenJpa) and setup basic Spring JPA configuration.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jdbc="http://www.springframework.org/schema/jdbc"
       xmlns:jpa="http://www.springframework.org/schema/data/jpa"
       xsi:schemaLocation="http://www.springframework.org/schema/jdbc 
                           http://www.springframework.org/schema/jdbc/spring-jdbc.xsd
                           http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/data/jpa
                           http://www.springframework.org/schema/data/jpa/spring-jpa.xsd">
  
  <bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
    <property name="dataSource" ref="dataSource" />
    <property name="jpaVendorAdapter">
      <bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter" />
    </property>
  </bean>

  <bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
    <property name="entityManagerFactory" ref="entityManagerFactory" />
  </bean>

</beans>

Create an entity:

@Entity
public class User {

  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private Integer id;
  private String firstname;
  private String lastname;
       
  // Getters and setters
}

Create an @Administration configuration in the package defined in web.xml previously:

public class UserAdministration extends AdministrationConfiguration<User> {

  public EntityMetadataConfigurationUnit configuration( EntityMetadataConfigurationUnitBuilder configurationBuilder ) {
    return configurationBuilder.nameField( "firstname" ).build();
  }

  public ScreenContextConfigurationUnit screenContext( ScreenContextConfigurationUnitBuilder screenContextBuilder ) {
    return screenContextBuilder
      .screenName( "Users Administration" )
      .menuName( "Users" )
      .build();
  }

  public FieldSetConfigurationUnit listView( final FieldSetConfigurationUnitBuilder fragmentBuilder ) {
    return fragmentBuilder
      .field( "firstname" ).caption( "First Name" )
      .field( "lastname" ).caption( "Last Name" )
      .build();
  }

Voila! You have a brand new LightAdmin back-end configured.

Check Out and Build from Source

1. Clone the repository from GitHub:

    $ git clone git://github.com/la-team/light-admin.git
   

2. Navigate into the cloned repository directory:

    $ cd light-admin
   

3. The project uses Maven to build:

    $ mvn clean install
   

Running from the Command Line

By default, the app will run in 'embedded' mode which does not require any external setup. The Tomcat 7 Maven plugin is configured for you in the POM file.

1. Navigate into demo application directory:

    $ cd lightadmin-sandbox
   

2. Launch Tomcat from the command line:

    $ mvn tomcat7:run
   

3. Access the deployed webapp at

    http://localhost:8080/lightadmin-sandbox
   

LightAdmin integration example

We prepared an example how easily you can integrate LightAdmin back-end to existing web application.

It's based on Spring Travel reference application.

1. Clone the repository from GitHub:

    $ git clone git://github.com/la-team/lightadmin-spring-travel.git
   

2. Navigate into the cloned repository directory:

    $ cd lightadmin-spring-travel
   

3. The project uses Maven to build:

    $ mvn clean install
   

4. Launch Tomcat from the command line:

    $ mvn tomcat7:run
   

5. Access the deployed webapp at

    http://localhost:8080/booking-mvc
   

Screenshots

Login to LightAdmin:

Dashboard:

List of persistent entities configured:

Search entities by criteria:

Quick view for particular entity:

Editing entity:

Show entity with all fields: