====== Display interactive form ======

===== Synopsis =====

    present [--form <menu>] [--keep]

===== Examples =====

=== Create and display a simple form ===

    form                Configure IPv4 networking on ${netX/mac}
    item netX/ip        IPv4 address
    item netX/netmask   Subnet mask
    item netX/gateway   Gateway address
    item dns            DNS server address
    present

=== Create and display a custom login screen ===

    form                    Login details
    item          email     Email address
    item --secret password  Password
    present

===== Description =====

Display an interactive form and store the resulting value in the specified [[:settings|setting]] for each form item.

{{ :screenshots:form_graphic.png?400x300 |A sample form}}

If no form is specified, the default (unnamed) form will be used.  The form will be automatically deleted unless the ''%%--keep%%'' option is specified.

===== Command status =====

^ Success   | Settings were edited successfully           |
^ Failure   | Settings were not edited successfully       |

===== See also =====

  * ''[[:cmd:form]]''
  * ''[[:cmd:item]]''
  * iPXE [[:scripting|scripting]] guide
  * [[:cmd|List of all iPXE commands]]

===== Notes =====

The user is able to use Ctrl-C (or Escape) to exit the form without making a selection.  You may therefore wish to always handle failures of the ''present'' command.  For example:

    present || goto error

You can use any valid setting name, including a scope and type. For example:

  set dest:ipv4 8.8.8.8
  set count:uint8 1
  
  form                        Test network connectivity via ping
  item           count:uint8  Ping count
  item --default dest:ipv4    Destination IPv4 address
  present
  
  ping --count ${count} ${dest}

You can add a background picture to enhance the appearance of your form using the ''[[:cmd:console]]'' command.