PFSenseDevWiki : CoreGUI

PfSenseDevHome :: Categories :: PageIndex :: RecentChanges :: RecentlyCommented :: Login/Register

CoreGUI


Where is it?
http://www.pfsense.org/~sullrich/CoreGUIBuilder/∞

What is it?

CoreGUI is the XML to webConfigurator framework being used in pfSense. Originally written in a form that would read native .conf files in a different closed-source project. The idea was completely rebuilt and adopted to work with the famous one file configuration system originally written for m0n0wall. CoreGUI can drastically lesson the work needed to create a rich GUI in pfSense that conforms to all of pfSenses theming needs.

PHP code can be included in a .inc file with the <includefile> xml directive. The code is included so that you can hook into php for different parts of the CoreGUI session. More on this in a bit.

Examples of CoreGUI in action

Screenshot∞ of OLSR CoreGUI application.

The code behind OLSR

<?xml version="1.0" encoding="utf-8" ?>
<packagegui>
	<name>OLSRD</name>
	<version>1.0</version>
	<title>OLSRD</title>
	<!-- Menu is where this packages menu will appear -->
	<menu>
		<name>OLSRD</name>
		<section>Services</section>
		<configfile>olsrd.xml</configfile>
	</menu>
	<service>
	            <name>OLSRD</name>
	            <rcfile>/usr/local/sbin/olsrd -f /var/etc/olsr.conf</rcfile>
	</service>
	<tabs>
		<tab>
			<text>OLSRD Settings</text>
			<url>/pkg_edit.php?xml=olsrd.xml&amp;id=0</url>
		</tab>
	</tabs>
	<additional_files_needed>
	    <prefix>/usr/local/www/</prefix>
	    <chmod>0755</chmod>
	    <item>http://www.pfsense.com/packages/config/OLSRD_rules.php</item>
	</additional_files_needed>
	<!-- configpath gets expanded out automatically and config items will be
	       stored in that location -->
	<configpath>['installedpackages']['OLSRD']['config']</configpath>
	<!-- fields gets invoked when the user adds or edits a item.   the following items
	       will be parsed and rendered for the user as a gui with input, and selectboxes. -->
	<fields>
		<field>
			<fielddescr>Enable OLSR</fielddescr>
			<fieldname>enable</fieldname>
			<description>Enables the dynamic mesh linking daemon</description>
			<type>checkbox</type>
		</field>
		<field>
			<fielddescr>Interfaces</fielddescr>
			<fieldname>interface_array</fieldname>
			<value>lan</value>
			<multiple>true</multiple>
			<size>3</size>
			<type>interfaces_selection</type>
		</field>
		<field>
			<fielddescr>Enable HTTPInfo Plugin</fielddescr>
			<fieldname>enablehttpinfo</fieldname>
			<description>Enables the OLSR stats web server</description>
			<type>checkbox</type>
		</field>
		<field>
			<fielddescr>HTTPInfo Port</fielddescr>
			<fieldname>port</fieldname>
			<description>Port that HTTPInfo will listen on</description>
			<type>input</type>
		</field>			
		<field>
			<fielddescr>Allowed host(s)</fielddescr>
			<fieldname>allowedhttpinfohost</fieldname>
			<description>Hosts that are allowed to access the HTTPInfo web service.</description>
			<type>input</type>
		</field>
		<field>
			<fielddescr>Allowed host(s) subnet</fielddescr>
			<fieldname>allowedhttpinfosubnet</fieldname>
			<description>Enter the subnet mask in form 255.255.255.0</description>
			<type>input</type>
		</field>
		<field>
			<fielddescr>Enable Dynamic Gateway</fielddescr>
			<fieldname>enabledyngw</fieldname>
			<description>Enables the OLSR Dynamic Gateways feature</description>
			<type>checkbox</type>
		</field>
		<field>
			<fielddescr>Ping</fielddescr>
			<fieldname>ping</fieldname>
			<description>Pings this host to ensure connectivity</description>
			<type>input</type>
		</field>
		<field>
			<fielddescr>Poll</fielddescr>
			<fieldname>polling</fieldname>
			<description>How often to look for a inet gw, in seconds.</description>
			<type>input</type>
		</field>			
		<field>
			<fielddescr>Enable Secure Mode</fielddescr>
			<fieldname>enabledsecure</fieldname>
			<description>Enables the secure mode</description>
			<type>checkbox</type>
		</field>
		<field>
			<fielddescr>Key</fielddescr>
			<fieldname>securekey</fieldname>
			<description>Paste the secure key information here.</description>
			<type>textarea</type>
			<rows>5</rows>
			<cols>50</cols>
		</field>
	</fields>
	<custom_delete_php_command>
	</custom_delete_php_command>
	<custom_php_resync_config_command>
		conf_mount_rw();
		$fd = fopen("/usr/local/etc/olsrkey.txt","w");
		fwrite($fd, $_POST['securekey']);
		fclose($fd);
		foreach($_POST['interface_array'] as $iface) {
				$if = convert_friendly_interface_to_real_interface_name($iface);
				if($if) {
						setup_wireless_olsr($if);
				}
		}
		conf_mount_ro();
	</custom_php_resync_config_command>
	<custom_php_install_command>
	</custom_php_install_command>
	<custom_php_deinstall_command>
	</custom_php_deinstall_command>
</packagegui>


CoreGUI form hooks

CoreGUI has a number of php hooks that are executed if populated with data. For example in the above example we have a number of hooks that should be pretty self explanitory when they are run. One that may not be very obvious is <custom_php_resync_config_command>. This tags code is executed after the forms data is parsed, validated and saved. Its generally a good idea to do custom operations after this call (creating conf files, etc).

Why CoreGUI doesn't suck(TM)

One of the neatest features of CoreGUI is that it automatically records the inputted data into the config.xml file. This rapidly decreases the time needed in handling post data, validating the data and then finally recording it in the needed section. Here is an example of OLSR's data segment in config.xml

<olsrd>
		<config>
				<enable></enable>
				<interface_array>MYTESTINTERFACE</interface_array>
				<enablehttpinfo>on</enablehttpinfo>
				<port>8080</port>
				<allowedhttpinfohost>10.0.250.110</allowedhttpinfohost>
				<allowedhttpinfosubnet>255.255.255.0</allowedhttpinfosubnet>
				<enabledyngw></enabledyngw>
				<ping>60</ping>
				<polling>60</polling>
				<enabledsecure></enabledsecure>
				<securekey>SECRET KEY</securekey>
		</config>
</olsrd>


Okay, I've got a XML CoreGUI type file, how do I test?

Testing is easy! Simply put the new xml file into /usr/local/pkg/ and then call the pkg handler. More on this in a sec.

Okay, I see pkg.php and pkg_edit.php and wizard.php.. which one to use, when and why?

CoreGUI can handle two different types of data. Groups of data (pkg.php) and a single data record (pkg_edit.php). Examples of this can be found in the spamd package. In the "SpamD External Sources"∞ tab. Basically when the user clicks on edit or add, it redirects to pkg_edit.php which will edit the specific record.

wizard.php is very similar to the normal CoreGUI files (pkg.php and pkg_edit.php) but it has a wrapper that seperated each screen into a "step". This is a great way of creating wizards. We plan on add and extend the wizard steps out to their own .inc file soon since its much easier to debug and simply add in the hooks to call the functions from the .inc file.

The main difference between the two is that wizard.php uses the <bindstofield> directive to map the data to the correct place in config.xml. pkg.php and pkg_edit.php uses the field name for the storage keyname.

Here is an example wizard.php block of XML code:

<totalsteps>8</totalsteps>
<step>
	<id>1</id>
	<title>pfSense Setup Wizard</title>
	<disableheader>true</disableheader>
	<description>This wizard will guide you through the initial configuration of pfSense.</description>
	<fields>
		<field>
			<name>Next</name>
			<type>submit</type>
		</field>
	</fields>
</step>
<step>
	<id>2</id>
	<title>General Information</title>
	<description>On this screen you will set the General pfSense parameters.</description>
	<fields>
		<field>
			<name>Hostname</name>
			<type>input</type>
			<bindstofield>system->hostname</bindstofield>
			<description>EXAMPLE: myserver</description>
		</field>
		<field>
			<name>Domain</name>
			<type>input</type>
			<bindstofield>system->domain</bindstofield>
			<description>EXAMPLE: mydomain.com</description>
			<validate>^[a-z0-9.|-]+$</validate>
			<message>Domain name field is invalid</message>
		</field>
		<field>
			<name>Primary DNS Server</name>
			<type>input</type>
			<bindstofield>system->dnsserver</bindstofield>
			<!-- we must unset the fields because this is an array. -->
			<unsetfield>yes</unsetfield>
			<arraynum>0</arraynum>
		</field>
		<field>
			<name>Secondary DNS Server</name>
			<type>input</type>
			<bindstofield>system->dnsserver</bindstofield>
			<arraynum>1</arraynum>
		</field>
		<field>
			<name>Next</name>
			<type>submit</type>
		</field>
	</fields>
</step>


In the case of OLSR's main settings screen its considered a single record and we basically call /pkg_edit.php?xml=olsrd.xml&id=0 to force the editing of record #0 (the first record).

Multi record applications

Multi record applications are applications such as Squid, SpamD and friends. When you want to manage multiple entries (users, server configs, client configs) etc, you will want to use pkg.php and add in some extra xml glue. Here is an example from SpamD's External Sources screenshot we showed you earlier:

	<adddeleteeditpagefields>
		<columnitem>
			<fielddescr>Provider Name</fielddescr>
			<fieldname>providername</fieldname>
		</columnitem>
		<columnitem>
			<fielddescr>Provider Type</fielddescr>
			<fieldname>providertype</fieldname>
		</columnitem>
		<columnitem>
			<fielddescr>Description</fielddescr>
			<fieldname>providerdescription</fieldname>
		</columnitem>
	</adddeleteeditpagefields>


The complete source to the above is located here∞.

The above basically creates multiple records with add and delete options. Clicking on an item will redirect to pkg_edit.php and use the id of the record (0 if new).

Validating data

Earlier in the wizard example we saw a <validate> data field. This is basically a regular expression that gets executed on the client in javascript.

pkg.php and pkg_edit.php currently do not have data validation features. This will be added soon.

Widget Types

CoreGUI supports many "widget" or "field" types. Examples of them are:

  1. input
  2. checkbox
  3. select
  4. interfaces_selection
  5. textarea
  6. rowhelper

Most of the above should be pretty self-explanitory if you have worked with HTML except the rowhelper. Rowhelper type widgets allow you add a series of data in javascript with + and - options. An example of this widget can be found in the Firewall -> Aliases -> Edit area.

Other cool CoreGUI Applications

OpenVPN Server∞ and OpenVPN Client∞ rewritten in CoreGUI by Fernando Lemos

There are no comments on this page. [Add comment]

Page History :: 2007-08-18 23:33:03 XML :: Owner: ChrisBuechler :: Search:
Valid XHTML 1.0 Transitional∞ :: Valid CSS∞ :: Powered by Wikka Wakka Wiki 1.1.6.3∞
Page was generated in 0.0572 seconds