Development / Models / Field types

Document available options, move item in the menu for better navigation.
2 years ago · 7691de4e9d
parent 77ace0bd4c
commit 7691de4e9d
3 changed files with 330 additions and 11 deletions
--- a/source/development/frontend.rst
+++ b/source/development/frontend.rst
@ -10,7 +10,7 @@ The OPNsense frontend is implemented with `PHP/Phalcon <https://en.wikipedia.org
   :glob:

   frontend/models
+   frontend/models_fieldtypes
   frontend/routing
   frontend/controller
   frontend/view_js_helpers
-   
--- a/source/development/frontend/models.rst
+++ b/source/development/frontend/models.rst
@ -19,7 +19,6 @@ In this chapter we will explain how models are designed and build.
   models_design
   models_example
   models_guidelines
-   models_fieldtypes
   models_customfields
   models_constraints
   models_migrations
--- a/source/development/frontend/models_fieldtypes.rst
+++ b/source/development/frontend/models_fieldtypes.rst
@ -1,6 +1,6 @@
----------------------
-Standard field types
----------------------
+=================================
+Creating Models / Field types
+=================================

 OPNsense comes with a collection of standard field types, which can be used to perform standard field type validations.
 These field types can be found in `/usr/local/opnsense/mvc/app/models/OPNsense/Base/FieldTypes/ <https://github.com/opnsense/core/tree/master/src/opnsense/mvc/app/models/OPNsense/Base/FieldTypes>`__
@ -8,6 +8,7 @@ and usually decent from the `BaseField` type.

 This paragraph aims to provide an overview of the types included by default and their use.

+
 .. Tip::

    When using lists, the :code:`Multiple` (Y/N) keyword defines if there may be more than one item selected at a time.
@ -16,6 +17,7 @@ This paragraph aims to provide an overview of the types included by default and

    The xml keyword :code:`Required` can be used to mark a field as being required.

+
 ArrayField
 ------------------------------------

@ -33,11 +35,32 @@ AuthGroupField
 Returns and validates system (user) groups (found in :menuselection:`System --> Access --> Groups`)


+.. csv-table:: AuthGroupField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+
+
 AuthenticationServerField
 ------------------------------------

 Select and validate authentication providers, maintained in :menuselection:`System --> Access --> Servers`.

+.. csv-table:: AuthenticationServerField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "Filters", "Y,N", "A structure of regex filters per atribute to exclude certain options from the list"

 AutoNumberField
 ------------------------------------
@ -45,26 +68,75 @@ AutoNumberField
 An integer sequence, which automatically increments on every new item of the same type in the same level.


+.. csv-table:: AutoNumberField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "MinimumValue", ":code:`int`", "Minimum number also starting point of the sequence"
+   "MaximumValue", ":code:`int`", "Maximum number"
+
+
 Base64Field
 ------------------------------------
 Validate if a given string contains a valid base64 decodable value.

+.. csv-table:: Base64Field
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "Mask", ":code:`regex`", "Optional validation regex"
+

 BooleanField
 ------------------------------------

 Boolean field, where 0 means :code:`false` and 1 is defined as :code:`true`

+.. csv-table:: BooleanField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+
+
+CertificateField
+------------------------------------
+
+Option list with system certificates defined in :menuselection:`System --> Trust`.
+
+.. csv-table:: CertificateField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "Type", ":code:`ca`, :code:`crl`, :code:`cert`", "Type of certificate to select, defaults to :code:`cert`"
+
 CSVListField
 ------------------------------------

 List of (comma) separated values, which can be validated using a regex.

-CertificateField
------------------------------------
+.. csv-table:: CSVListField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "Mask", ":code:`regex`", "Optional validation regex"

-Option list with system certificates defined in :menuselection:`System --> Trust`, use the `Type` keyword to distinct between the
-available options (:code:`ca`, :code:`crl`, :code:`cert`), defaults to :code:`cert`.

 ConfigdActionsField
 ------------------------------------
@ -80,27 +152,110 @@ only shows actions which have a description.
        </filters>
    </command>

+.. csv-table:: ConfigdActionsField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "Filters", "Y,N", "A structure of regex filters per atribute to exclude certain options from the list"
+
+

 CountryField
 ------------------------------------

 Select and validate countries in the world.

+.. csv-table:: CountryField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "AddInverted", "Y,N", "Add 'inverted'/excluded countries to the list, copies contry codes prefixes an :code:`!` (e.g. :code:`!NL`)"
+
+ConfigdActionsField
+------------------------------------
+
+Select available configd actions, supports filters to limit the number of choices. For example, the example below
+only shows actions which have a description.
+
+.. code-block:: xml
+
+    <command type="ConfigdActionsField">
+        <filters>
+            <description>/(.){1,255}/</description>
+        </filters>
+    </command>
+
+.. csv-table:: ConfigdActionsField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "Filters", "Y,N", "A structure of regex filters per atribute to exclude certain options from the list"
+
+
+
 EmailField
 ------------------------------------

 Validate if the input contains an email address.

+.. csv-table:: EmailField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+
+
 HostnameField
 ------------------------------------

-Check if hostnames are valid (optionally allows IP addresses as well)
+Check if hostnames are valid, includes the following options:
+
+.. csv-table:: HostnameField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "IpAllowed", "Y,N", "Allow an ip address"
+   "HostWildcardAllowed", "Y,N", "Allow :code:`*` for all hostnames"
+   "FqdnWildcardAllowed", "Y,N", "Allow partial wildcard for fully qualified domain names (e.g. :code:`*.my.top.level.domain`)"
+   "ZoneRootAllowed", "Y,N", "Allow the zone root marker (:code:`@`)"
+

 IntegerField
 ------------------------------------

 Validate if the input contains an integere value, optionally constrained by minimum and maximum values.

+.. csv-table:: EmailField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "MinimumValue", ":code:`int`", "Minimum number"
+   "MaximumValue", ":code:`int`", "Maximum number"
+
+
 InterfaceField
 ------------------------------------

@ -108,6 +263,19 @@ Option list with interfaces defined in :menuselection:`Interfaces --> Assignment
 The example below shows a list of non-dhcp active interfaces, for which multiple items may be selected, but at least one
 should be. It defaults to :code:`lan`

+.. csv-table:: InterfaceField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "Filters", "Y,N", "A structure of regex filters per atribute to exclude certain options from the list"
+   "AddParentDevices", "Y,N", "Add parent devices in the list when not assigned"
+   "AllowDynamic", "Y,N,S", "Allow dynamic (hotplug) interfaces, when set to :code:`S` hotplug interfaces without a static address are ignored"
+
 .. code-block:: xml

    <interfaces type="InterfaceField">
@ -138,6 +306,20 @@ A construct to validate against a json dataset retreived via configd, such as

 In which case :code:`syslog list applications` is called to retrieved options, which is valid for 20 seconds (TTL) before fetching again.

+.. csv-table:: JsonKeyValueStoreField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "ConfigdPopulateAct", ":code:`text`", "Configd command responsible for the data"
+   "SourceFile", ":code:`text`", "Temporary filename where results are stored"
+   "ConfigdPopulateTTL", ":code:`int`", "Time To Live in seconds"
+   "SortByValue", "Y,N", "Sort by value, default sorts by key"
+

 LegacyLinkField
 ------------------------------------
@ -178,6 +360,16 @@ Define relations to other nodes in the model, such as to point the attribute :co
        </Model>
    </pipe>

+.. csv-table:: ModelRelationField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "Model", ":code:`xml`", "structure as described in the sample above"


 NetworkAliasField
@ -198,21 +390,71 @@ Predefined special networks contain the following choices:
 All network/host type aliases (including, but not limited to GeoIP) defined in :menuselection:`Firewall -> Aliases` are
 also valid choices.

+
+
+.. csv-table:: NetworkAliasField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+
+
 NetworkField
 ------------------------------------

 Validate if the value is a valid network address (IPv4, IPv6).

+.. csv-table:: NetworkField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "Mask", ":code:`regex`", "Optional validation regex"
+   "NetMaskRequired", "Y,N", "Is a netmask required"
+   "NetMaskAllowed", "Y,N", "Is a netmask allowed"
+   "AddressFamily", ":code:`ipv4`, :code:`ipv6`", "Which address family to use, blank means ipv4+ipv6"
+   "FieldSeparator", ":code:`text`", "Separator character to use"
+   "WildcardEnabled", "Y,N", "Allow the use of the :code:`any` clause"
+   "AsList", "Y,N", "Field type should return list items"
+
 NumericField
 ------------------------------------

 Validate input to be of numeric type.

+
+.. csv-table:: NumericField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "MinimumValue", ":code:`int`", "Minimum number"
+   "MaximumValue", ":code:`int`", "Maximum number"
+
+
 OptionField
 ------------------------------------

 Validate against a static list of options.

+.. csv-table:: OptionField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "OptionValues", ":code:`xml`", "Xml structure containing keys and values, when keys should be numeric, the value tag is also supported :code:`<opt1 value='1'>option1</opt1>`"
+
 PortField
 ------------------------------------

@ -220,29 +462,107 @@ Check if the input contains a valid portnumber or (optionally) predefined servic
 :code:`EnableRanges` is set to :code:`Y`.


+.. csv-table:: PortField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options, when set the type is treated as a list"
+   "EnableWellKnown", "Y,N", "Allow the usage of well known names such as 'http' and 'ssh'"
+   "EnableRanges", "Y,N", "Allow the usa of ranges, such as :code:`80:100`"
+
+
 ProtocolField
 ------------------------------------

 List field type to validate if the provided value is a valid protocol name as defined by /etc/protocols
 (e.g. TCP, UDP) extended with the :code:`any` option.

+.. csv-table:: ProtocolField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+

 TextField
 ------------------------------------

 Validate regular text using a regex.

+.. csv-table:: TextField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "Mask", ":code:`regex`", "Optional validation regex"
+
+
 UniqueIdField
-==================================
+------------------------------------

 Generate unique id numbers.

+.. csv-table:: UniqueIdField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+
+
 UpdateOnlyTextField
 ------------------------------------

 Write only text fields, can be used to store passwords

+.. csv-table:: TextField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "Mask", ":code:`regex`", "Optional validation regex"
+
+
 UrlField
 ------------------------------------

 Validate if the input contains a valid URL.
+
+.. csv-table:: UrlField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+
+
+VirtualIPField
+------------------------------------
+
+Select a virtual address defined in :menuselection:`Interfaces -> Virtual IPs -> Settings`, use with a bit of care as
+the keys (addresses) are subjected to change.
+
+.. csv-table:: VirtualIPField
+   :header: "Parameter", "Options", "Purpose"
+   :widths: 30, 20, 40
+
+   "default", ":code:`text`", "Default value for new attributes"
+   "Required", "Y,N", "Mark field as required"
+   "ValidationMessage", ":code:`text`", "Error message on validation failure"
+   "BlankDesc", ":code:`text`", "Set a label for the empty option"
+   "Multiple", "Y,N", "Allow to select multiple options"
+   "Type", ":code:`text`", "The virtual ip type to select, :code:`*` for all (default)"