Structure

General

Menus is RetroNAS are driven from a JSON config stored in config/retronas.json, it is intended to back both a Text User Interface (TUI) and Web User Interface (WUI). This document is intended to outline the implementation.

This is evolving so check back regularly if something isn't working as expected.

Menus are where feasible autogenerated based on input from the JSON, top level menus always are expected to have the menu type

RetroNAS

Retronas is written in BASH, it is a compilation of scripts combined with other tools (See Installers) that achieves the desired result.

Installers

RetroNAS installers are stored in Ansible playbooks as a series of Tasks, there has been some interest in migrating these to roles, while promising we are not there yet.

An installer runs ansible-playbook which will configure the system and install various jinja templates on the filesystem (where applicable) with the appropriate permissions to run actions and/or services.

3rd Party Tools

We install and configure a number of 3rd party tools in RetroNAS, see Installers, sometimes issues will need to be upstreamed to the appropriate project.

Structures

JSON

Menu structure

a dict object, basic menu structure is

Menu

"menu-name": 
{
	"title": "",
	"description": "",
	"id":"",
	"prompt": "",
	"type": "menu",
	"items": []
}

Term	Description
menu-name	an unique name for the menu, it can be used with type dialog to load the menu data
title	Menu title, it is a H2 in the WUI and resides at the top of TUI dialog
description	Freeform text to display at the top of a dialog before the menu elements, newlines represented by |
id	item id, used as an element id in the WUI, may be used for dialog type in TUI in the future
prompt	(WUI only) a generic term to use to display on button elements
type	See Types
items	a list of dicts for each menu item and its function

Items

{
	"index":"",
	"title": "",
	"description": "",
	"id":"",
	"prompt": "",
	"type": "",
	"group":"",
	"command": ""
},

Term	Description
index	TUI only, the numeric index for the TUI element e.g. 06
title	Item title displays before the dash character in the TUI, also used in WUI
description	Freeform text to display at the top of a dialog before the menu elements, newlines represented by |
id	item id, used as an element id in the WUI, may be used for dialog type in TUI in the future
prompt	(WUI only) overwrride the global button element text for this item
type	See Types
group	Used to group similar commands together, WUI only, not yet implemented
command	the execution params for the item, dependant on type, colon seperated, dependant on runner support

Prefix

This are pre-pended automatically based on type

Term	Description
d-	Dialog prefix, a standard menu
s-	Script prefix
m-	Modal prefix
i-	input dialog
f-	form dialog
y-	yes/no dialog

Types

More types are probably required but this is what we have at the moment

Type	Description
menu	Menu navigation and top level menus have this type
dialog	Loads another menu by passing command to menu.sh based on type
modal	A dialog that is service specifc and launch from another, in the WUI shows as modal
script	A script type, that executes script_runner.sh based on input type executing
install	This is an installer type that executes ansible_runner.sh
script-static	A script of type static exists in scripts/static and execute with elevated privs
input:[type]	This is a WIP, expected to be used for form generation
dialog_yn	A Yes/No dialog
dialog_input	A dialog with an input field, used input.sh
service_status	Query a systemd service
form	form based dialog (theoretical)

TUI

The TUI Is driven from functions in common.sh and a standard menu file based on type of dialog requested for menus this menu.sh

The TUI leverages the program jq to query the JSON data to generate the menus

menu.sh

A generic placehoder menu that will take a menu object name as an arguement, read the data from JSON and display the content as selectable dialog

WUI

Written as a javascript driven cockpit plugin and managed in a seperate repo, it will be documented there but will confirm to the JSON layout detailed in this document