File base doc updates

This commit is contained in:
Bryan Ashby 2018-12-04 16:56:05 -07:00
parent 9c835af000
commit 1520d46763
1 changed files with 35 additions and 23 deletions

View File

@ -2,34 +2,38 @@
layout: page
title: Configuring a File Base
---
## Configuring a File Base
ENiGMA½ offers a powerful and flexible file base. Configuration of file the file base and areas is handled via the `fileBase` section of `config.hjson`.
## ENiGMA½ File Base Key Concepts
Like many things in ENiGMA½, configuration of file base(s) is handled via `config.hjson` — specifically
in the `fileBase` section. First, there are a couple of concepts you should understand:
First, there are some core concepts you should understand:
* Storage Tags
* Areas (and Area Tags)
### Storage Tags
*Storage Tags* define paths to physical (file) storage locations that are referenced in a file *Area* entry. Each entry may be either a fully qualified path or a relative path. Relative paths are relative to the value set by the `areaStoragePrefix` key (defaults to `/path/to/enigma-bbs/file_base`).
### Storage tags
**Storage Tags** define paths to physical (file) storage locations that are referenced in a
file *Area* entry. Each entry may be either a fully qualified path or a relative path. Relative paths
are relative to the value set by the `areaStoragePrefix` key (defaults to `<enigma_install_dir/file_base`).
Below is an example defining a both a relative and fully qualified path each attached to a storage tag:
Below is an example defining some storage tags using the relative and fully qualified forms:
```hjson
storageTags: {
retro_pc: "retro_pc" // relative
retro_pc_bbs: "retro_pc/bbs" // still relative!
retro_pc_dos: "dos" // relative
retro_pc_bbs: "pc/bbs" // still relative!
bbs_stuff: "/path/to/bbs_stuff_storage" // fully qualified
}
```
Note that on their own, storage tags don't do anything — they are simply pointers to storage locations on your system.
:information_source: On their own, storage tags don't do anything — they are simply pointers to storage locations on your system.
### Areas
File base *Areas* are configured using the `fileBase::areas` configuration block in `config.hjson`. Valid members for an area are as follows:
File base **Areas** are configured using the `fileBase::areas` configuration block in `config.hjson`.
Each entry within `areas` must contain a `name`, `desc`, and `storageTags`. Remember that in ENiGMA½
while areas are important, they should generally be used less than in tradditional BBS software. It is
recommended to favor the use of more **tags** over more areas.
| Item | Required | Description |
|--------|---------------|------------------|
| `name` | :+1: | Friendly area name. |
| `desc` | :-1: | Friendly area description. |
| `storageTags` : | :+1: | An array of storage tags for physical storage backing of the files in this area. If uploads are enabled for this area, **first ** storage tag location is utilized!** |
| `sort` | :-1: | If present, provides the sort key for ordering. `name` is used otherwise. |
Example areas section:
@ -38,31 +42,39 @@ areas: {
retro_pc: {
name: Retro PC
desc: Oldschool PC/DOS
storageTags: [ "retro_pc", "retro_pc_bbs" ]
storageTags: [ "retro_pc_dos", "retro_pc_bbs" ]
}
}
```
The above example defines an area called "Retro PC" which is referenced via the *area tag* of `retro_pc`. Two storage tags are used: `retro_pc_dos`, and `retro_pc_bbs`. These storage tags can be seen in the Storage Tags example above.
## Example Configuration
This combines the two concepts described above. When viewing the file areas from ENiGMA½ a user will
only see the "Retro PC" area, but the files in the area are stored in the two locations defined in the
`storageTags` section.
This combines the two concepts described above. When viewing the file areas from ENiGMA½ a user will only see the "Retro PC" area, but the files in the area are stored in the two locations defined in the `storageTags` section. We also show a uploads area. Uploads are allowed do to the [ACS](acs.md) block. See [Uploads](uploads.md) for more information.
```hjson
fileBase: {
areaStoragePrefix: /enigma-bbs/file_base
storageTags: {
retro_pc: "retro_pc"
retro_pc_bbs: "retro_pc/bbs"
retro_pc_dos: "dos"
retro_pc_bbs: "pc/bbs"
}
areas: {
retro_pc: {
name: Retro PC
desc: Oldschool PC/DOS
storageTags: [ "retro_pc", "retro_pc_bbs" ]
storageTags: [ "retro_pc_dos", "retro_pc_bbs" ]
}
uploads: {
name: Uploads
desc: User uploads
acs: {
// allow any user to upload here
write: GM[users]
}
storageTags: [ "user_uploads" ]
}
}
}