Bootstrap conversion notes

Steve_B

The attached file contains my notes for converting the pfSense user interface to use Bootstrap. It may be of some help to others, particularly pfSense package maintainers needing to convert their package web pages.

Please feel free to ask for help or clarification.
[pfSense Bootstrap conversion.pdf.zip](/public/imported_attachments/1/pfSense Bootstrap conversion.pdf.zip)

Steve_B

New feature

The Form_Section class is used on almost every page:


$form = new Form();
$section = new Form_Section("Module settings");

It accepts two arguments, the title and (optionally) an ID.

I have extended the class to take a third argument, and added some defines to make its use more simple.

So this statement:

$section = new Form_Section("Module settings", "modsettings", COLLAPSIBLE|SEC_CLOSED);

will make the section collapsible, and will add a plus icon to the title bar (just like a dashboard widget). The initial state will be collapsed. Had I used SEC_OPEN, the initial state would have been open (not collapsed)

There are still a couple of things to work out in the styling so consider it experimental at this point.
You can currently see it in use on the diag_logs_filter.php page

Steve_B

New feature (2)

When composing XML files to be interpreted by pkg_edit.php, the textarea type now correctly processes rows and cols tags
In rowhelpers, select and input elements respect the <width>tag. Note that the width specifies the number of bootstrap grid positions (not columns). Total number of width units must not exceed 10 on any row. The "Delete" button takes up two, so that leaves eight for the other row elements</width>

Steve_B

New feature 3

A new method has been introduced to the Form_Section class. addPassword() works the same as addInput() except that:

It automatically adds a second password field for confirmation to the password element you specify
The confirmation element will be named the same as the field you specify, but with "_confirm" appended
If not blank, the value of the element is replaced by DMYPWD, which is defined as "********"

In the validation section of each page, the code will now be something like:


if ($_POST['password'] != $_POST['password_confirm']) {
    $input_errors[] = gettext("The Password and its confirmation must match");
}

And in the section where we write the new config:


if (!$input_errors) {
    if ($_POST['password'] != DMYPWD) {
        $config['password'] = $_POST['password']);
    } else {
        // Sometimes it will be necessary to get the current setting and write it back out. Look at the config write
        // section to see how it is handled there.
        $config['password'] = $a_config['password'];
    }
}

Or something like that. You get the idea.

These are the files that now make use of this scheme:

firewall_virtual_ip_edit.php
interfaces.php
interfaces_ppps_edit.php
services_captiveportal_vouchers.php
services_dyndns_edit.php
services_pppoe_edit.php
system_advanced_misc.php
system_advanced_notifications.php
system_hasync.php
vpn_l2tp.php
vpn_l2tp_users_edit.php
vpn_openvpn_client.php

Testing has been completed on these files. Other files may be converted later.

Steve_B

setIsRequired()

The methodsetIsRequired()adds the attribute "required" to any input to facilitate browser validation of that element. It is just a shortcut for```
setAttribute("required", true)

Steve_B

Making panels collapsible in a package UI page

Packages that create UI pages via XML and pkg_edit.php may now make a panel collapsible by adding the new <collapse>tag to the listtopic field definition. e.g.:

<field><name>Package Settings</name>
<type>listtopic</type>
<collapse>closed</collapse></field>

<collapse>closed</collapse> Creates a panel that is collapsible and initially closed
<collapse>open</collapse> Creates a panel that is collapsible and initially open</collapse>

Steve_B

Improvement to infoblock mechanism

The infoblock mechanism now works slightly differently. Here is an example:

Notice the 'false' at the end of the print_info_box? That is a new argument that suppresses the 'X' close button that is normally present in a text box.


is exactly the same, except that the information block is initially open.

It is now possible to have more than one infoblock on a page. A numerical suffix is automatically added to the infoblock class for you, ensuring that the correct block is toggled.