mirror of
https://github.com/dalbodeule/snap-admin.git
synced 2025-06-09 05:48:20 +00:00
WIP
This commit is contained in:
Francesco
parent
9091ba365a
commit
747f07e041
91
README.md
91
README.md
@ -6,35 +6,40 @@ Spring Boot Database Admin scans your `@Entity` classes to generate a simple but
|
||||
|
||||
[](https://i.imgur.com/Nz19f8e.png)
|
||||
|
||||
Features:
|
||||
**Features:**
|
||||
* List objects with pagination and sorting
|
||||
* Show detailed object page which also includes `@OneToMany`, `@ManyToMany`, etc... fields
|
||||
* Show object detail page, which also includes `@OneToMany`, `@ManyToMany`, etc... fields
|
||||
* Create/Edit objects
|
||||
* Action logs (i.e. see a history of all write operations done through the web UI)
|
||||
* Action logs: history of all write operations executed through the web UI
|
||||
* Search
|
||||
* Customization
|
||||
|
||||
The code is in a very early version and I'm trying to collect as much feedback as possible in order to fix the
|
||||
most common issues that will inevitably arise. If you are so kind to try the project and you find something
|
||||
broken, please report it as an issue and I will try to take a look at it.
|
||||
**Supported JPA annotations**
|
||||
* Core: @Entity, @Table, @Column, @Lob, @Id
|
||||
* Relationships: @OneToMany, @ManyToOne, @ManyToMany, @OneToOne
|
||||
|
||||
The behaviour you specify with these annotations should be applied automatically by Spring Boot Database Admin as well. Keep in mind that using non-supported annotations will not necessarily result in an error, as they are simply ignored. Depending on what the annotation actually is, this could be just fine or result in an error if it interferes with something that Spring Boot Database Admin relies on.
|
||||
|
||||
The code is still in a very early stage and it might not be robust if you use not-yet-supported JPA annotations.
|
||||
If find something broken with your configuration, please report it as an issue and I will try to take a look at it.
|
||||
|
||||
## Installation
|
||||
|
||||
1. The code is not yet distributed on Maven, so for now you need to install manually. Clone the Github repo and `mvn install` the project, then include the dependency in your `pom.xml`:
|
||||
1. The code is not yet distributed on Maven, so for now you need to install manually. Clone the Github repo and execute `mvn install -DskipTests` in the project's directory. Then, include the dependency in your `pom.xml`:
|
||||
|
||||
```
|
||||
<dependency>
|
||||
<groupId>tech.ailef</groupId>
|
||||
<artifactId>spring-boot-db-admin</artifactId>
|
||||
<version>0.0.4</version>
|
||||
<version>0.0.4</version> <!-- Make sure to put the correct version here -->
|
||||
</dependency>
|
||||
```
|
||||
|
||||
2. A few simple configuration steps are required on your end in order to integrate the library into your project. If you don't want
|
||||
to test on your own code, you can clone the [test project](https://github.com/aileftech/spring-boot-database-admin-test) which provides
|
||||
2. A few simple configuration steps are required on your end in order to integrate the library into your project.
|
||||
If you don't want to test on your own code, you can clone the [test project](https://github.com/aileftech/spring-boot-database-admin-test) which provides
|
||||
a sample database and already configured code.
|
||||
|
||||
If you wish to integrate it into your project instead, the first step is adding these to your `application.properties` file:
|
||||
Otherwise, go ahead and add these to your `application.properties` file:
|
||||
|
||||
```
|
||||
# Optional, default true
|
||||
@ -44,7 +49,7 @@ dbadmin.enabled=true
|
||||
dbadmin.baseUrl=admin
|
||||
|
||||
# The package that contains your @Entity classes
|
||||
dbadmin.modelsPackage=tech.ailef.dbadmin.test.models
|
||||
dbadmin.modelsPackage=put.your.models.package.here
|
||||
```
|
||||
|
||||
The last step is to annotate your `@SpringBootApplication` class containing the `main` method with the following:
|
||||
@ -53,67 +58,21 @@ The last step is to annotate your `@SpringBootApplication` class containing the
|
||||
@ImportAutoConfiguration(DbAdminAutoConfiguration.class)
|
||||
```
|
||||
|
||||
This will autoconfigure the various DbAdmin components when your application starts.
|
||||
This will autoconfigure Spring Boot Database Admin when your application starts. You are good to go!
|
||||
|
||||
3. At this point, when you run your application, you should be able to visit `http://localhost:$PORT/${baseUrl}` and access the web interface.
|
||||
3. At this point, when you run your application, you should be able to visit `http://localhost:${port}/${dbadmin.baseUrl}` and see the web interface.
|
||||
|
||||
## Documentation
|
||||
|
||||
For more detailed documentation, visit https://aileftech.github.io/spring-boot-database-admin/.
|
||||
Available at: https://aileftech.github.io/spring-boot-database-admin/.
|
||||
|
||||
Once you are correctly running Spring Boot Database Admin, you will be able to access the web interface. Most of the features are already available with the basic configuration. However, some customization to the interface might be applied by using appropriate annotations on your classes fields or methods.
|
||||
The following annotations are supported.
|
||||
## Issues
|
||||
|
||||
### @DisplayName
|
||||
```
|
||||
@DisplayName
|
||||
public String getName() {
|
||||
return name;
|
||||
}
|
||||
```
|
||||
|
||||
When displaying a reference to an item, by default we show its primary key. If a class has a `@DisplayName`, this method will be used in addition to the primary key whenever possible, giving the user a more readable option.
|
||||
|
||||
### @DisplayFormat
|
||||
```
|
||||
@DisplayFormat(format = "$%.2f")
|
||||
private Double price;
|
||||
```
|
||||
|
||||
Specify a format string to apply when displaying the field.
|
||||
|
||||
### @ComputedColumn
|
||||
```
|
||||
@ComputedColumn
|
||||
public double totalSpent() {
|
||||
double total = 0;
|
||||
for (Order o : orders) {
|
||||
total += o.total();
|
||||
}
|
||||
return total;
|
||||
}
|
||||
```
|
||||
|
||||
This annotation can be used to add values computed at runtime that are shown like additional columns.
|
||||
|
||||
### @Filterable
|
||||
|
||||
```
|
||||
@Filterable
|
||||
private LocalDate createdAt;
|
||||
```
|
||||
|
||||
Place on one or more fields in a class to activate the faceted search feature. This will allow you to easily combine all these filters when operating on the table. Can only be placed on fields that correspond to physical columns on the table (e.g. no `@ManyToMany`/`@OneToMany`) and that are not binary (`byte[]`).
|
||||
|
||||
### @DisplayImage
|
||||
|
||||
```
|
||||
@DisplayImage
|
||||
private byte[] image;
|
||||
```
|
||||
|
||||
This annotation can be placed on binary fields to declare they are storing an image and that we want it displayed when possible. The image will be shown as a small thumbnail.
|
||||
If you find a problem or a bug, please report it as issue. When doing so, include as much information as possible, and in particular:
|
||||
|
||||
* provide the code for the involved `@Entity` classes, if possible
|
||||
* provide the full stack trace of the error
|
||||
* specify if you are using any particular configuration either in your `application.properties` or through annotations
|
||||
|
||||
## Changelog
|
||||
|
||||
|
||||
@ -13,7 +13,7 @@
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/properties.min.js"></script>
|
||||
<script type="text/javascript">
|
||||
document.addEventListener('DOMContentLoaded', function() {
|
||||
document.querySelectorAll('h2, h3, h4, h5, h6').forEach(heading => {
|
||||
document.querySelectorAll('h2, h3, h4, h5').forEach(heading => {
|
||||
let tag = heading.tagName.replace('H', '');
|
||||
|
||||
document.getElementById('toc').innerHTML +=
|
||||
@ -63,7 +63,7 @@
|
||||
|
||||
<h2 id="introduction">1. Introduction</h2>
|
||||
|
||||
<p>The following documentation outlines how to install, configure and customize Spring Boot Database Admin panel. Refer to this document for troubleshooting and if you still encounter problems, please report it as an issue on Github.</p>
|
||||
<p>The following documentation outlines how to install, configure and customize Spring Boot Database Admin panel. Refer to this document for troubleshooting and if you still encounter problems, please <a href="https://github.com/aileftech/spring-boot-database-admin/issues" target="_blank">report it as an issue on Github</a>.</p>
|
||||
<div class="separator"></div>
|
||||
<h2 id="getting-started">2. Getting started</h2>
|
||||
<p>Getting started with Spring Boot Database Admin requires including it as a dependency and then performing a simple configuration step.</p>
|
||||
@ -145,6 +145,22 @@ private Double price;
|
||||
|
||||
|
||||
<h4 id="computed-column">3.1.3 @ComputedColumn</h4>
|
||||
<h6>Supported parameters</h6>
|
||||
<table class="table table-striped">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="fw-bold">name</td>
|
||||
<td>String</td>
|
||||
<td>false</td>
|
||||
<td>The name of this column in the web interface. The method's name is used if this value is not specified.</td>
|
||||
</tr>
|
||||
</table>
|
||||
<h6>Code example</h6>
|
||||
<pre>
|
||||
<code class="language-java">@ComputedColumn
|
||||
public double totalSpent() {
|
||||
@ -160,14 +176,35 @@ public double totalSpent() {
|
||||
<p>This annotation can be used to add values computed at runtime that are shown like additional columns.</p>
|
||||
|
||||
<h4 id="filterable">3.1.4 @Filterable</h4>
|
||||
|
||||
<h6>Supported parameters</h6>
|
||||
<table class="table table-striped">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Required</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="fw-bold">type</td>
|
||||
<td>false</td>
|
||||
<td>Enum (<code>DEFAULT</code>, <code>CATEGORICAL</code>)</td>
|
||||
<td>If <code>CATEGORICAL</code>, this changes the filter in the UI to shows all the possible values directly instead of providing a autocomplete form.</td>
|
||||
</tr>
|
||||
</table>
|
||||
<h6>Code example</h6>
|
||||
<pre>
|
||||
<code class="language-java">@Filterable
|
||||
private LocalDate createdAt;
|
||||
|
||||
@Filterable(type=FilterableType.CATEGORICAL)
|
||||
@ManyToOne
|
||||
private User user;
|
||||
</code>
|
||||
</pre>
|
||||
|
||||
<p>Place on one or more fields in a class to activate the faceted search feature. This will allow you to easily combine all these filters when operating on the table. Can only be placed on fields that correspond to physical columns on the table (e.g. no `@ManyToMany`/`@OneToMany`) and that are not binary (`byte[]`).</p>
|
||||
|
||||
|
||||
<p>Place on one or more fields in a class to activate the faceted search feature. This will allow you to easily combine all these filters when operating on the table. Can only be placed on fields that correspond to physical columns on the table (e.g. no <code>@ManyToMany</code>/<code>@OneToMany</code>) and that are not binary (<code>byte[]</code>).</p>
|
||||
|
||||
<h4 id="display-image">3.1.5 @DisplayImage</h4>
|
||||
|
||||
@ -190,6 +227,10 @@ private byte[] image;
|
||||
<h2>4. Security</h2>
|
||||
<p>Spring Boot Database Admin does not implement authentication and/or authorization mechanisms. However, you can use a standard Spring security configuration in order to limit access to the web UI or specific parts of it.</p>
|
||||
<p>All Spring Boot Database Admin routes start with the value of <code>dbadmin.baseUrl</code> property, and all write operations (edit, create, delete) are implemented as <code>POST</code> calls.</p>
|
||||
<div class="separator"></div>
|
||||
<h2>5. Troubleshooting</h2>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
@ -16,5 +16,5 @@ import java.lang.annotation.Target;
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@Target(ElementType.FIELD)
|
||||
public @interface Filterable {
|
||||
public String type() default "";
|
||||
public FilterableType type() default FilterableType.DEFAULT;
|
||||
}
|
||||
5
src/main/java/tech/ailef/dbadmin/external/annotations/FilterableType.java
vendored
Normal file
5
src/main/java/tech/ailef/dbadmin/external/annotations/FilterableType.java
vendored
Normal file
@ -0,0 +1,5 @@
|
||||
package tech.ailef.dbadmin.external.annotations;
|
||||
|
||||
public enum FilterableType {
|
||||
DEFAULT, CATEGORICAL;
|
||||
}
|
||||
@ -10,6 +10,7 @@ import com.fasterxml.jackson.annotation.JsonIgnore;
|
||||
|
||||
import tech.ailef.dbadmin.external.annotations.DisplayImage;
|
||||
import tech.ailef.dbadmin.external.annotations.Filterable;
|
||||
import tech.ailef.dbadmin.external.annotations.FilterableType;
|
||||
|
||||
public class DbField {
|
||||
protected String dbName;
|
||||
@ -139,7 +140,7 @@ public class DbField {
|
||||
|
||||
public boolean isFilterableCategorical() {
|
||||
Filterable filterable = getPrimitiveField().getAnnotation(Filterable.class);
|
||||
return filterable != null && filterable.type().equalsIgnoreCase("categorical");
|
||||
return filterable != null && filterable.type() == FilterableType.CATEGORICAL;
|
||||
}
|
||||
|
||||
public Set<DbFieldValue> getAllValues() {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user