Lots more MenuModule info
This commit is contained in:
parent
1402391234
commit
fdfd64976b
|
@ -3,7 +3,7 @@ layout: page
|
|||
title: Menu Modules
|
||||
---
|
||||
## Menu Modules
|
||||
From initial connection to the screens and mods your users interact with, the entire experience is made up of menu entries — And all menu entries found within `menu.hjson` are backed by *Menu Modules*. For basic menus, a standard handler is implemented requiring no code. However, if you would like to create a menu that has custom handling, you will very likely be inheriting from from `MenuModule`. More on this below.
|
||||
From initial connection to the screens and mods your users interact with, the entire experience is made up of menu entries — And all menu entries found within [menu.hjson](../configuration/menu-hjson.md) are backed by *Menu Modules*. For basic menus, a standard handler is implemented requiring no code. However, if you would like to create a menu that has custom handling, you will very likely be inheriting from from `MenuModule`. More on this below.
|
||||
|
||||
> :information_source: Remember that ENiGMA does not impose any stucture to your system! The "flow" of all `menu.hjson` entries is up to you!
|
||||
|
||||
|
@ -43,19 +43,74 @@ initSequence() {
|
|||
}
|
||||
```
|
||||
|
||||
## ModuleInfo
|
||||
To register your module with the system, include a `ModuleInfo` declaration in your exports:
|
||||
> :bulb: Remember that *all* menus within ENiGMA are created by inheriting from `MenuModule`. Take a look at existing examples such as [WFC](/core/wfc.js), [NUA](/core/nua.js), [MRC](/core/mrc.js) and more!
|
||||
|
||||
### ModuleInfo
|
||||
To register your module with the system, include a `ModuleInfo` declaration in your exports. The following members are available:
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | :+1: | Short name of the module |
|
||||
| `desc` | :+1: | Long description of this module |
|
||||
| `author` | :+1: | Author(s) of module |
|
||||
| `packageName` | :-1: | Defines a reverse DNS style package name. Can be used in conjunction with the `getModDatabasePath()` call form [database.js](/core/database.js) to interact with a database specific to your module (See example below) |
|
||||
|
||||
**Example**:
|
||||
|
||||
```javascript
|
||||
exports.ModuleInfo = {
|
||||
name: 'Super Dope Mod',
|
||||
desc: '...a super dope mod, duh.',
|
||||
author: 'You!',
|
||||
packageName: `com.myname.foo.super-dope-mod`,
|
||||
};
|
||||
```
|
||||
|
||||
## Lifecycle
|
||||
Below is a very high level diagram showing the basic lifecycle of a menu.
|
||||
### Per-Mod Databases
|
||||
Custom mods often need their own data persistence. This can be acheived with `getModDatabsePath()` and your `ModuleInfo`'s `packageName`.
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
self.database = getTransactionDatabase(
|
||||
new sqlite3.Database(getModDatabasePath(moduleInfo), callback)
|
||||
);
|
||||
```
|
||||
|
||||
Given the `packageName` above, a database will be created at the following location:
|
||||
```bash
|
||||
$enigma-bbs/db/mods/com.myname.foo.super-dope-mod.sqlite3
|
||||
```
|
||||
|
||||
### Menu Methods
|
||||
Form handler methods specified by `@method:someName` in your `menu.hjson` entries map to those found in your module's `menuMethods` object. That is, `this.menuMethods` and have the following signature `(formData, extraArgs, cb)`. For example, consider the following `menu.hjson` fragment:
|
||||
|
||||
```hjson
|
||||
actionKeys: [
|
||||
{
|
||||
keys: [ "a", "shift + a" ]
|
||||
action: @method:toggleAvailable
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
We can handle this in our module as such:
|
||||
```javascript
|
||||
exports.getModule = class MyFancyModule extends MenuModule {
|
||||
constructor(options) {
|
||||
super(options);
|
||||
|
||||
this.menuMethods = {
|
||||
toggleAvailable: (formData, extraArgs, cb) => {
|
||||
// ...do something fancy...
|
||||
return cb(null);
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## MenuModule Lifecycle
|
||||
Below is a very high level diagram showing the basic lifecycle of a MenuModule.
|
||||
|
||||
![Basic Menu Lifecycle](../../assets/images/basic_menu_lifecycle.png)
|
||||
|
||||
|
@ -98,30 +153,8 @@ mciReady(mciData, cb) {
|
|||
|
||||
> :information_source: Search the code for the above methods to see how they are used in the base system!
|
||||
|
||||
## Menu Methods
|
||||
Form handler methods specified by `@method:someName` in your `menu.hjson` entries map to those found in your module's `menuMethods` object. That is, `this.menuMethods` and have the following signature `(formData, extraArgs, cb)`. For example, consider the following `menu.hjson` fragment:
|
||||
|
||||
```hjson
|
||||
actionKeys: [
|
||||
{
|
||||
keys: [ "a", "shift + a" ]
|
||||
action: @method:toggleAvailable
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
We can handle this in our module as such:
|
||||
```javascript
|
||||
exports.getModule = class MyFancyModule extends MenuModule {
|
||||
constructor(options) {
|
||||
super(options);
|
||||
|
||||
this.menuMethods = {
|
||||
toggleAvailable: (formData, extraArgs, cb) => {
|
||||
// ...do something fancy...
|
||||
return cb(null);
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
## Custom Mods
|
||||
Most mods will also derive from `MenuModule`. Some things to be aware of:
|
||||
* Custom mods that bring in their own dependencies must also include their own `package.json` and other Node requirements
|
||||
* Be sure to use `packageName` and `getModDatabasePath()` for any peristence needs.
|
||||
|
|
Loading…
Reference in New Issue