Skip to content

Commit c1eadf5

Browse files
Zayden-GabiaZayden-Gabia
committedMar 25, 2024
Update README.md
1 parent 01f516b commit c1eadf5

File tree

1 file changed

+53
-14
lines changed

1 file changed

+53
-14
lines changed
 

‎README.md

+53-14
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,77 @@
11
# Spring Sheet Ease
2-
In services run on the Spring web framework, sometimes data must be offered in Excel instead of JSON. This library simplifies the process, allowing the conversion of JSON data to Excel files for download with just one annotation, bypassing the complexity of using tools like Apache POI
3-
# Usage
2+
3+
Spring Sheet Ease is a powerful library designed to bridge the gap between JSON data and Excel files within applications built on the Spring web framework. It offers a straightforward solution for services requiring data presentation in Excel format, simplifying the conversion process by eliminating the need for direct interaction with complex libraries like Apache POI. With just one annotation, developers can easily convert JSON data into downloadable Excel files, enhancing data portability and user experience.
4+
5+
## Features
6+
7+
- **Simplified Excel File Creation:** Generate Excel files from JSON data with a single annotation.
8+
- **Customizable Options:** Control file naming, password protection, and data flattening to suit your needs.
9+
- **No Direct Apache POI Dependency:** Avoid the complexity of directly using Apache POI for Excel file generation.
10+
11+
## Getting Started
12+
13+
### Prerequisites
14+
15+
Ensure you have a Spring-based project ready for integrating Spring Sheet Ease.
16+
17+
### Installation
18+
19+
Add the following dependency to your project's `pom.xml` file to include Spring Sheet Ease:
20+
421
```xml
522
<dependency>
623
<groupId>com.beoks</groupId>
724
<artifactId>spring-web-excel</artifactId>
825
<version>0.0.1-SNAPSHOT</version>
926
</dependency>
1027
```
11-
You need only append `@ExcelDownload` annotation to Controller Method.
28+
29+
### Usage
30+
31+
To enable Excel file download functionality, append the `@ExcelDownload` annotation to a controller method as demonstrated below:
32+
1233
```java
1334
@RestController
1435
@RequestMapping("/pet")
1536
public class PetController {
1637

17-
//this will response JSON
38+
// Responds with JSON data
1839
@GetMapping
1940
List<Pet> get(){
2041
return Pet.getDummy();
2142
}
2243

23-
//this will response test.xlsx file
44+
// Responds with an Excel file named 'test.xlsx'
2445
@GetMapping("/excel")
25-
@ExcelDownload(fileName = "test.xlsx",password = "excelFilePassword", useFlatten = false)
46+
@ExcelDownload(fileName = "test.xlsx", password = "password123!", useFlatten = false)
2647
List<Pet> getExcel(){
2748
return Pet.getDummy();
2849
}
2950
}
3051
```
31-
You can see the result in [resource](./src/test/resources) directory
32-
33-
## Option
34-
| Option | Description |
35-
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36-
| filename | Excel Filename, suffix must be .xlsx |
37-
| password | Excel file password, if use empty string encryption not applied, default is empty string |
38-
| useFlatten | An option to either flatten nested JSON data to place each item in a separate cell or to display nested data as a JSON string<br><br>When useFlatten is False<br>"Max" "2018-01-01" "DOG" {"name":"John","address":"123 Street","friends":[{"name":"Sarah","address":"456 Avenue","friends":null},{"name":"Robert","address":"789 Road","friends":null}]} <br><br>When useFlatten is True<br>Max 2018-01-01 DOG John 123 Street Sarah 456 Avenue null Robert 789 Road null <br>Bella 2019-01-01 CAT John 123 Street Sarah 456 Avenue null Robert 789 Road null <br>Charlie 2017-01-01 DOG Sarah 456 Avenue null<br> |
52+
53+
### Examples
54+
55+
Explore the provided examples in the [resource directory](./src/test/resources) for insights on implementation and output.
56+
57+
## Configuration Options
58+
59+
Customize the behavior of your Excel file generation with the following options:
60+
61+
| Option | Description |
62+
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
63+
| `filename` | Sets the Excel file name (must have a `.xlsx` suffix). |
64+
| `password` | Secures the Excel file with a password. Leave as an empty string (`""`) for no encryption. Default is an empty string. |
65+
| `useFlatten`| Determines the structure of nested JSON data in the Excel file. <br>**False:** Displays nested data as a JSON string.<br>**True:** Flattens nested data, placing each item in a separate cell. |
66+
67+
## Contributing
68+
69+
Contributions to Spring Sheet Ease are welcome! Please refer to our contributing guidelines for detailed information on how you can contribute to the project.
70+
71+
## License
72+
73+
Spring Sheet Ease is open-source software licensed under the [MIT license](LICENSE).
74+
75+
---
76+
77+
This revised README provides a more structured approach to presenting the information, making it easier for users to understand the library's purpose, setup, and configuration. Including sections like "Getting Started," "Configuration Options," and "Contributing" can also encourage community engagement and provide clear guidance on how to use the library effectively.

0 commit comments

Comments
 (0)