PFSense Package Writing: Controls

The previous article described the process of creating a simple GUI package for pfSense. The package contained one single field with a checkbox control described in the fields XML section of the package file.

Before proceeding, it is necessary to give some explanations on the structure of the fields section. This section describes the form fields of the current GUI page. Each field is described in the field node and contains the elements:

• fielddescr - field name, displayed in the left part of the form in front of the control;
• fieldname - the name of the field under which it will be available in the system when processing the entered data;
• description - a comment describing this field is displayed under the control;
• type - the type of control used in this field.

The figure below shows the correspondence between the XML elements of the package structure and the GUI elements.
')

Controls

Consider simple pfSense GUI controls:

• checkbox
• input
• password
• textarea
• select
• interfaces_selection

CHECKBOX Element
It is a simple “check box” that allows the user to make a yes / no choice.

<field> <fielddescr>Enable</fielddescr> <fieldname>enable</fieldname> <description>Check this for enable package.</description> <type>checkbox</type> </field> 

INPUT element
It is a simple text field for entering single-line text information. The size parameter allows you to set the width of the window of this element.

  <field> <fielddescr>Login</fielddescr> <fieldname>pkglogin</fieldname> <description>Enter package login.</description> <type>input</type> <size>30</size> </field> 

PASSWORD item
It is a kind of input element and serves to enter a password in the WEB form of a package. But the entered data is displayed here as asterisks.

  <field> <fielddescr>Password</fielddescr> <fieldname>pkgpass</fieldname> <description>Enter package password.</description> <type>password</type> <size>30</size> </field> 

TEXTAREA element
Represents a multi-line text field. In addition to the standard XML options, the field contains in the description the cols and rows parameters that define the dimensions of the element in columns and rows, respectively. There is also an encoding parameter that indicates in which encoding to save the data entered by the user. This is usually Base64 encoding.

  <field> <fielddescr>Comments</fielddescr> <fieldname>pkgcomments</fieldname> <description> Enter you coments here. </description> <type>textarea</type> <cols>60</cols> <rows>3</rows> <encoding>base64</encoding> </field> 

SELECT element
It is a drop-down list of values ​​in the form of a combo box , specified in the options section. The multiple modifier turns an ordinary combo box into a list box element, allowing you to select multiple values ​​at the same time (by pressing Control + Left-click). The default_value parameter sets the default value from the list in the options section.

  <field> <fielddescr>Age</fielddescr> <fieldname>pkgage</fieldname> <description>Choose your age.</description> <type>select</type> <default_value>adl</default_value> <options> <option><value>chd</value><name>children</name></option> <option><value>tng</value><name>teenager</name></option> <option><value>adl</value><name>adult</name></option> </options> <multiple/> </field> 

INTERFACES_SELECTION element
This is a special kind of select element. This list lists all of the major pfSense network interfaces. As well as in the select element, the additional options multiple and default_value are available here .

  <field> <fielddescr>Interface</fielddescr> <fieldname>pkginterface</fieldname> <description> Select interface(s) for using in the package. Use 'Ctrl' + L_click for multiple selection. </description> <type>interfaces_selection</type> <default_value>lan</default_value> <multiple/> </field> 

By collecting the above descriptions of controls into one XML file, we obtain the following form of the Web interface:


In order for this form to perform any actions, you must specify event handlers and write the appropriate PHP code. This will be discussed in the next article.


PS: I apologize to my colleagues for such crushing the material, but I do not want to make long articles.