Macrame allows the creation of interactive menus that the user navigates with arrow and tab keys and selects with return. Menus can have a standard, vertical layout or a more compact horizontal layout. There is also a dynamic datepicker.

#Quickref

$macrame = new Macrame();

$header = "Choose a Linux distro";

$options = [
    'Yggdrasil',
    'Hannah Montana Linux',
    'Elfstone',
];

// interactive vertical menu
$selected = $macrame->menu()->interactive($options, $header);

// interactive horizontal menu
$selected = $macrame->menu()->horizontal($options, $header);

// interactive date picker
$selected = $macrame->menu()->datePicker('1990-04-19', 'select a date');

// style and colour highlighted option
$macrame->menu()->styleSelected('bold');  // style of highlighted option
$macrame->menu()->colourSelected('red');  // colour of highlighted option
$macrame->menu()->colorSelected('red');   // synonym for colourSelected()

// style and colour non-highlighted options
$macrame->menu()->styleOption('italic');  // style of non-highlighted option
$macrame->menu()->colourOption('blue');   // colour of non-highlighted option
$macrame->menu()->colorOption('blue');    // synonym for colourOption()

// align items inside the menu
$macrame->menu()->optionLeft();
$macrame->menu()->optionRight();
$macrame->menu()->optionCentre();
$macrame->menu()->optionCenter();

// align the menu inside the terminal
$macrame->menu()->menuLeft();
$macrame->menu()->menuRight();
$macrame->menu()->menuCentre();
$macrame->menu()->menuCenter();

// erase menu after selection
$macrame->menu()->erase();

#Creating an interactive menu

Vertical, interactive menus can be created and displayed using MacrameMenu’s interactive() method.

The interactive() method accepts an array of strings as a list of options to display, and an optional header.

$macrame = new Macrame();

$header = "Choose a Linux distro";

$options = [
    'Yggdrasil',
    'Hannah Montana Linux',
    'Elfstone',
];

// display menu of options. user selection is returned.
$selected = $macrame->menu()->interactive($options, $header);

Interactive menus are navigated by the user using the up and down arrow keys to highlight an option, and the <RETURN> key to select it. The <TAB> key functions as a down arrow key. Additionally, pressing any other key acts as a ‘leader’ key, highlighting the first option that starts with that character.

The selected option is returned by interactive() as a string.

#Headers for interactive menus

Headers can be any text. If the header text is styled with MacrameText‘s style and colour methods, this styling will be displayed. If the header contains line breaks, ie. from php’s PHP_EOL, they will be preserved.

// this will be displayed with styling and line breaks
$header = 'choose <!ITALIC!>your<!CLOSE!> favourite'.
    PHP_EOL.
    $macrame->text("distribution")->colour("green")->get();

#Options for interactive menus

Options can be any text and can include line breaks, ie. from php’s PHP_EOL.

All styling applied to options is removed before display. To apply styling to options see ‘Styling menu options’ below.

#Creating a horizontal menu

Horizontal, interactive menus can be created and displayed using MacrameMenu’s horizontal() method.

The horizontal() method accepts an array of strings as a list of options to display, and an optional header.

$macrame = new Macrame();

$header = "Choose a Linux distro";

$options = [
    'Yggdrasil',
    'Hannah Montana Linux',
    'Elfstone',
];

// display menu of options. user selection is returned.
$selected = $macrame->menu()->horizontal($options, $header);

#Headers for horizontal menus

Headers can be any text. If the header text is styled with MacrameText‘s style and colour methods, this styling will be displayed. If the header contains line breaks, ie. from php’s PHP_EOL, they will be preserved.

// this will be displayed with styling and line breaks
$header = 'choose <!ITALIC!>your<!CLOSE!> favourite'.
    PHP_EOL.
    $macrame->text("distribution")->colour("green")->get();

#Options for horizontal menus

Options can be any text but should not contain any line breaks.

All styling applied to options is removed before display. To apply styling to options see ‘Styling menu options’ below.

#Creating a datepicker

A datepicker menu can be created and displayed using MacrameMenu’s datePicker() method.

The datePicker() method accepts a starting date as a string, and an optional header.

// interactive date picker
$selected = $macrame->menu()->datePicker('1990-04-19', 'select a date');

The starting date argument can be in any format that php’s DateTime can parse.

Datepickers are navigated by using the left and right arrows to select the year, month or day columns. The <TAB> key functions as a right-arrow key. The year, month and day values can be incremented or decremented using the down and up arrow keys. Additionally, literal values can by typed using leader keys, ie. in the month column, typing ‘a’ will select ‘Apr’. Typing ‘au’ will select ‘Aug’.

#Styling menu options

The default behaviour of MacrameMenu is for options to be displayed in plain text, with the currently selected option being highlighted in reverse. This can be changed using styling methods.

Unselected options can be given a style and colour using:

Selected, highlighted options can be give a style and colour using:

#Aligning menus

Macrame allows for options and headers to be aligned within a menu, and menus themselves to be aligned in the terminal, by using the alignment methods:

For example, to centre align a menu’s options and align the menu in the center of the terminal:

$macrame->menu()->optionCentre()->menuCentre()->interactive($options, $header);

#Erasing menus

All menus can be set to erase after the user has made a selection by calling the erase() method.

$selected = $macrame->menu()->erase()->interactive($options, $header);