Skip to content

Commit 4f55dc0

Browse files
committed
update readme with direct access, header footer, and message utility
1 parent 321e917 commit 4f55dc0

1 file changed

Lines changed: 100 additions & 1 deletion

File tree

README.md

Lines changed: 100 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Flexible and robust static access configuration api.
1616
- Remove unused / unknown keys + logging
1717
- File structure and value formatting
1818
- Annotation based field modifiers
19-
- Header comment at top of config file
19+
- Automatic header and footer comments
2020
- Small and lightweight (~490kb)
2121

2222
## Support
@@ -291,6 +291,64 @@ override: true
291291
# OVERRIDE is set to true.
292292
```
293293

294+
#### @Header & @Footer
295+
296+
- @Header is used to add a header comment to the top of a config document.
297+
- @Footer is used to add a footer comment to the bottom of a config document.
298+
299+
```java
300+
@StaticConfig.Header("This is a header!")
301+
@StaticConfig.Footer({"This is a footer!", "Second line!"})
302+
public class Settings extends StaticConfig {}
303+
```
304+
305+
<details>
306+
<summary>How to I remove <code>StaticConfig.</code> from the annotation?</summary>
307+
308+
---
309+
310+
You must statically import the Header annotation from the StaticConfig class.
311+
312+
```java
313+
import static net.j4c0b3y.api.config.StaticConfig.Header;
314+
```
315+
316+
Then you can use the annotation like this instead:
317+
318+
```java
319+
@Header("This is a shorter way of using the header annotation!")
320+
public class Settings extends StaticConfig {}
321+
```
322+
323+
---
324+
</details>
325+
326+
```yaml
327+
# This is a header!
328+
329+
example: true
330+
331+
# This is a footer!
332+
# Second line!
333+
```
334+
335+
#### Dynamic Headers
336+
337+
If you would like to dynamically change the content of the header when saving,
338+
you can override the `public List<String> getHeader()/getFooter()` methods.
339+
340+
```java
341+
import java.util.Arrays;
342+
343+
public class Settings extends StaticConfig {
344+
345+
@Override
346+
public List<String> getHeader() {
347+
return Arrays.asList("Create a nice", "dynamic header!");
348+
}
349+
}
350+
```
351+
294352
### Final Members
295353

296354
If a field or class is marked final, its value is always reset in the config.
@@ -383,6 +441,47 @@ test:
383441
```
384442
</details>
385443

444+
### Message Utility
445+
446+
The config api comes with an in-built `Message` class that you can use
447+
to send single or multi-line messages with replaced placeholders and
448+
translations easily to a play or other form of user.
449+
450+
#### Usage
451+
452+
Here is an example of how it can be used, first create the default config.
453+
454+
```java
455+
public class Messages extends StaticConfig {
456+
// ...
457+
public static Message RELOAD_SUCCESS = Message.of(
458+
"&aSuccessfully reloaded in <duration>ms!"
459+
);
460+
461+
public static Message RELOAD_FAILED = Message.of(
462+
"&cAn issue occurred whilst reloading the plugin,",
463+
"&cplease check console for any errors!"
464+
);
465+
}
466+
```
467+
468+
Second, use the message from the config to send the message to the user.
469+
470+
```java
471+
Messages.RELOAD_SUCCESS
472+
.replace("<duration>", duration) // Replace custom placeholders in each line.
473+
.map(Color::translate) // Translate the message (parse papi placeholders as well).
474+
.send(player::sendMessage); // Send each of the lines to the player or user.
475+
```
476+
477+
#### Advantages
478+
479+
The message utility is very useful for the following reasons:
480+
481+
- Very clean usage and experience for the developer implementing logic.
482+
- Allows users to set the message as `[]` in the config to not send any message.
483+
- Allows users to choose whether they want single or multi line messages.
484+
386485
### Want more?
387486

388487
Each and every class in my config api has detailed javadocs explaining what

0 commit comments

Comments
 (0)