| 1 |
50a93b16
|
SjonHortensius
|
pfSense on bootstrap (<a href="https://github.com/SjonHortensius/pfsense/blob/bootstrap/PROGRESS.md#php-file-status">progress</a>)
|
| 2 |
1180e4f0
|
Sjon Hortensius
|
====================
|
| 3 |
|
|
|
| 4 |
|
|
We are migrating pfSense to Bootstrap. You can help! Please respect these code-guidelines:
|
| 5 |
|
|
|
| 6 |
84c2d088
|
SjonHortensius
|
* use tabs (tabstop=4) for indenting (except the license-header which contains 3 lines that are indented with ```\t<SP><SP><SP>```)
|
| 7 |
d50b4c30
|
Sjon Hortensius
|
* no trailing whitespace
|
| 8 |
1180e4f0
|
Sjon Hortensius
|
* limited echoing of HTML from php, please use proper templating syntax instead (eg. foreach/endforeach)
|
| 9 |
84c2d088
|
SjonHortensius
|
* limited attributes on elements; so _**no** style/align/width attributes_
|
| 10 |
66de8653
|
SjonHortensius
|
* no inline javascript, no ``` ```, no tables for layout (replace them with [panels](getbootstrap.com/components/#panels) where necessary)
|
| 11 |
d50b4c30
|
Sjon Hortensius
|
* html attributes should be using double-quoted attribute-values. This means your php-code should probably use single-quoted strings
|
| 12 |
7c804c69
|
Sjon Hortensius
|
* we use icons for status-indication and buttons for actions
|
| 13 |
84c2d088
|
SjonHortensius
|
* **do not** refactor any of the 'backend' code that is on top of each file. Only changes necessary after updating are acceptable; any other changes will be rejected (including changes that were done upstream)
|
| 14 |
f3f98e97
|
Phil Davis
|
* we accept both [K&R](https://en.wikipedia.org/wiki/Indent_style#K.26R_style) and [ZF](http://framework.zend.com/manual/1.12/en/coding-standard.html) styled code, the above guidelines have a higher precedence
|
| 15 |
1180e4f0
|
Sjon Hortensius
|
|
| 16 |
f180fe1a
|
Sander van Leeuwen
|
If you feel adventurous you can sometimes rewrite some PHP & javascript code as well; but try to keep this to a minimum.
|
| 17 |
|
|
|
| 18 |
64c0004e
|
Sjon Hortensius
|
# Development setup
|
| 19 |
|
|
|
| 20 |
f3f98e97
|
Phil Davis
|
We suggest you setup a development environment for testing your changes. This can be done with either Virtualbox or Qemu.
|
| 21 |
64c0004e
|
Sjon Hortensius
|
|
| 22 |
|
|
## Qemu
|
| 23 |
|
|
|
| 24 |
|
|
Use libvirt to setup a FreeBSD-10 machine with 2 NICs. Boot the latest pfSense.iso and install it. I've attached both NICs to the virbr0 that libvirt offers by default. One interface can be used as WAN (where pfSense will use dhcp and should get a NATted ip on your local network), the other as a LAN interface with a fixed IP address.
|
| 25 |
|
|
|
| 26 |
|
|
## Virtualbox
|
| 27 |
|
|
|
| 28 |
88d0577b
|
Sander van Leeuwen
|
Create a new virtual machine (FreeBSD 64 bit) and follow the wizard to configure the amount of RAM (512MB) and create a virtual HDD (8GB will do). When finished, don't start the machine but open the settings dialog and configure two network adapters. Both should be configured as 'Bridged Adapter', attached to your active network connection.
|
| 29 |
|
|
|
| 30 |
|
|
Once saved, you can start the machine. Virtualbox will ask you to configure a bootable medium. Use the latest available .iso, follow the standard installation steps and set up the configuration as described in the Qemu instructions.
|
| 31 |
64c0004e
|
Sjon Hortensius
|
|
| 32 |
6c6ff9ad
|
Sander van Leeuwen
|
When finished, don't forget to remove the installation disk from your machine. Otherwise, it'll keep booting the installer instead of your installation.
|
| 33 |
|
|
|
| 34 |
64c0004e
|
Sjon Hortensius
|
## Post install tasks
|
| 35 |
|
|
|
| 36 |
|
|
Disable the dhcp server (on the LAN interface) of your pfSense install and you're good to go. Start the ssh-daemon, login and setup public-key authentication (for the root user). Execute `pkg install rsync` and create a script to upload your changes from your development environment to your pfSense install:
|
| 37 |
|
|
|
| 38 |
|
|
```bash
|
| 39 |
|
|
#!/bin/sh
|
| 40 |
|
|
|
| 41 |
c3dafdb2
|
Sjon Hortensius
|
HOST=192.168.122.100
|
| 42 |
|
|
|
| 43 |
|
|
rsync -xav --delete `dirname $0`/usr/local/www/ root@$HOST:/usr/local/www/
|
| 44 |
|
|
rsync -xav --delete `dirname $0`/etc/inc/ root@$HOST:/etc/inc/
|
| 45 |
64c0004e
|
Sjon Hortensius
|
```
|
| 46 |
|
|
|
| 47 |
f180fe1a
|
Sander van Leeuwen
|
# Cleaner
|
| 48 |
|
|
|
| 49 |
f997432b
|
SjonHortensius
|
Before diving into a file, clean it with the supplied cleaner (`clean.sh`). This script tries to remove most of the unnecessary element attributes and does a bunch of other replaces which have to be done in every file.
|
| 50 |
f180fe1a
|
Sander van Leeuwen
|
|
| 51 |
511b099d
|
SjonHortensius
|
# Migration conventions
|
| 52 |
f180fe1a
|
Sander van Leeuwen
|
|
| 53 |
511b099d
|
SjonHortensius
|
All migrated files (in usr/local/www) are formatted with default [Bootstrap](http://getbootstrap.com/) components. Custom CSS goes into `usr/www/bootstrap/css/pfSense.css`, but try to keep this to a minimum.
|
| 54 |
f180fe1a
|
Sander van Leeuwen
|
|
| 55 |
|
|
The Bootstrap grid system is used for defining columns. We've chosen the 'small' breakpoint as the default breakpoint to collapse from a horizontal to vertical layout. You should define your column widths with `.col-sm-*`, unless there's a good (and documented ;) ) reason to deviate from this default.
|
| 56 |
|
|
|
| 57 |
|
|
## Forms
|
| 58 |
|
|
|
| 59 |
079becf2
|
Sander van Leeuwen
|
We're following a few conventions for a clean and consistent form layout:
|
| 60 |
|
|
|
| 61 |
|
|
* Every form should have at least one 'panel' which contains the form fields. If certain fields can be grouped together, you can add multiple panels to a form.
|
| 62 |
|
|
* A field consists of an outer wrapper `.form-group` which contains a `label` and the `input`
|
| 63 |
|
|
* The submit button should be placed outside of the panels to prevent confusion (e.g., the save button saves the whole form and not just the last panel).
|
| 64 |
|
|
* Checkboxes are placed within a label (see example below). The wrapping div needs an additional `.checkbox` class
|
| 65 |
|
|
* Additional field descriptions can be placed in the `.help-block` `span`
|
| 66 |
|
|
|
| 67 |
01a84fcf
|
Sjon Hortensius
|
After determining the proper layout for forms we decided to create wrappers in PHP to create all forms. This de-duplicates all of the current HTML, making this migration a bit harder but any future updates infinitely easier (since all forms can be updated centrally). This is what the form-code should look like:
|
| 68 |
f180fe1a
|
Sander van Leeuwen
|
|
| 69 |
01a84fcf
|
Sjon Hortensius
|
```php
|
| 70 |
|
|
require('classes/Form.class.php');
|
| 71 |
|
|
$form = new Form;
|
| 72 |
f180fe1a
|
Sander van Leeuwen
|
|
| 73 |
10322913
|
Sander van Leeuwen
|
$section = new Form_Section('System');
|
| 74 |
01a84fcf
|
Sjon Hortensius
|
|
| 75 |
|
|
$section->addInput(new Form_Input(
|
| 76 |
c3dafdb2
|
Sjon Hortensius
|
'hostname',
|
| 77 |
|
|
'Hostname',
|
| 78 |
|
|
'text',
|
| 79 |
|
|
$pconfig['hostname'],
|
| 80 |
|
|
['placeholder' => 'pfSense']
|
| 81 |
01a84fcf
|
Sjon Hortensius
|
))->setHelp('Name of the firewall host, without domain part');
|
| 82 |
|
|
|
| 83 |
|
|
$section->addInput(new Form_Input(
|
| 84 |
c3dafdb2
|
Sjon Hortensius
|
'domain',
|
| 85 |
|
|
'Domain',
|
| 86 |
|
|
'text',
|
| 87 |
|
|
$pconfig['domain'],
|
| 88 |
|
|
['placeholder' => 'mycorp.com, home, office, private, etc.']
|
| 89 |
01a84fcf
|
Sjon Hortensius
|
))->setHelp('Do not use \'local\' as a domain name. It will cause local '.
|
| 90 |
c3dafdb2
|
Sjon Hortensius
|
'hosts running mDNS (avahi, bonjour, etc.) to be unable to resolve '.
|
| 91 |
|
|
'local hosts not running mDNS.');
|
| 92 |
01a84fcf
|
Sjon Hortensius
|
|
| 93 |
|
|
$form->add($section);
|
| 94 |
|
|
|
| 95 |
|
|
print $form;
|
| 96 |
f180fe1a
|
Sander van Leeuwen
|
```
|
| 97 |
|
|
|
| 98 |
01a84fcf
|
Sjon Hortensius
|
Please make sure the referenced $_POST fields in the php-code above this code are also updated since they are automatically generated
|
| 99 |
|
|
|
| 100 |
10322913
|
Sander van Leeuwen
|
The PHP code will output HTML something like this (with everything but relevant Bootstrap classes omitted for this example):
|
| 101 |
079becf2
|
Sander van Leeuwen
|
|
| 102 |
|
|
```html
|
| 103 |
|
|
<form class="form-horizontal">
|
| 104 |
|
|
<div class="panel panel-default">
|
| 105 |
|
|
<div class="panel-heading">
|
| 106 |
|
|
<h2 class="panel-title">Form or panel heading</h2>
|
| 107 |
|
|
</div>
|
| 108 |
|
|
<div class="panel-body">
|
| 109 |
|
|
<div class="form-group">
|
| 110 |
|
|
<label for="input" class="col-sm-2 control-label">An input</label>
|
| 111 |
|
|
<div class="col-sm-10">
|
| 112 |
|
|
<input class="form-control" id="input" />
|
| 113 |
|
|
</div>
|
| 114 |
|
|
</div>
|
| 115 |
|
|
<div class="form-group">
|
| 116 |
|
|
<label for="second-input" class="col-sm-2 control-label">Second label</label>
|
| 117 |
|
|
<div class="col-sm-10">
|
| 118 |
|
|
<input class="form-control" id="second-input" />
|
| 119 |
|
|
<span class="help-block">What's this all about?</span>
|
| 120 |
|
|
</div>
|
| 121 |
|
|
</div>
|
| 122 |
|
|
<div class="form-group">
|
| 123 |
|
|
<label for="second-input" class="col-sm-2 control-label">Checkbox</label>
|
| 124 |
|
|
<div class="col-sm-10 checkbox">
|
| 125 |
|
|
<label>
|
| 126 |
|
|
<input type="checkbox" id="checkbox" /> Checkbox description
|
| 127 |
|
|
</label>
|
| 128 |
|
|
</div>
|
| 129 |
|
|
</div>
|
| 130 |
|
|
|
| 131 |
|
|
<!-- And more form-groups -->
|
| 132 |
|
|
|
| 133 |
|
|
</div>
|
| 134 |
|
|
</div>
|
| 135 |
|
|
|
| 136 |
|
|
<!-- And more panels -->
|
| 137 |
|
|
|
| 138 |
|
|
<div class="col-sm-10 col-sm-offset-2">
|
| 139 |
|
|
<input type="submit" class="btn btn-primary" value="Save" />
|
| 140 |
|
|
</div>
|
| 141 |
|
|
</form>
|
| 142 |
|
|
```
|
| 143 |
|
|
|
| 144 |
f180fe1a
|
Sander van Leeuwen
|
## Tables
|
| 145 |
|
|
|
| 146 |
|
|
* Wrap your tables in a `<div class="table-responsive">` to make them scroll horizontally on small devices.
|
| 147 |
|
|
* Tables get a standard set of classes: `table table-striped table-hover`
|
| 148 |
6c943511
|
Sander van Leeuwen
|
* Please add a `thead` (with corresponding `th`'s) and `tbody`
|
| 149 |
|
|
|
| 150 |
|
|
## Buttons
|
| 151 |
|
|
|
| 152 |
|
|
Many tables have 'action' buttons per row, like 'edit', 'move' and 'delete'. The old template uses icons for these actions, but in most cases there are not sufficient different icons and / or the icons aren't very self explanatory. We've chosen to replace these icons with (small) buttons:
|
| 153 |
|
|
|
| 154 |
|
|
```html
|
| 155 |
|
|
<a class="btn btn-xs btn-primary">edit</a> <a class="btn btn-xs btn-danger">delete</a>
|
| 156 |
|
|
```
|
| 157 |
|
|
|
| 158 |
|
|
The button colours aren't set in stone, but the variants used so far are:
|
| 159 |
|
|
|
| 160 |
|
|
* edit - dark blue, `btn-primary`
|
| 161 |
|
|
* enable / disable - yellow, `btn-warning`
|
| 162 |
|
|
* delete - red, `btn-danger`
|
| 163 |
|
|
* copy - neutral, `btn-default`
|
| 164 |
|
|
|
| 165 |
|
|
## Icons
|
| 166 |
|
|
|
| 167 |
01a84fcf
|
Sjon Hortensius
|
Icons are primarily used for status indications. Try to supply a legend when the icon is not 100% self explanatory. See `usr/local/www/firewall_rules.php` for an good example of icon usage and a legend.
|