Uniformity Guidelines

Starting in FreePBX 13 the development team made the decision to apply a consistent look and feel to all of FreePBX. The below guidelines should be taken into account when you are creating or editing your module for FreePBX 13.

Getting Started

Starting with FreePBX 12 we now incorporate Twitter Bootstrap into the project. Bootstrap is the most popular HTML, CSS, and JS framework for developing responsive, mobile first projects on the web. You should give it a once over before continuing with this article at: http://getbootstrap.com/

Since most of FreePBX is user driven "form" based input you'll want to focus on the "form" elements http://getbootstrap.com/css/#forms

We also use bootstrap's "grid" system http://getbootstrap.com/css/#grid

Using the Grid

When we use the "grid" to create a module page we are trying to achieve two goals. First when we are in a desktop environment we want the page to be divided with 66% of the space given to the form elements while 33% is given to what we now call "bootnav" (formerly called rnav).

Open

When the page shrinks to less than 768px width we hide our "bootnav". Since bootstrap "stacks" when the width is less than 768px by default the nav will jump to the bottom of the page, however since it is hidden it is not seen and our primary form display becomes full width.

Open

Bootstrap itself works with columns of 12. So every row must have 12 columns total. To get our desired 66% to 33% ratio we are going to use 9 for the left half and 3 for the right half.

So for our page layout (usually in page.<modulename>.php or under the "views" folder we want to start off like so:

Adding "Bootnav"

Adding Floating Right Nav to Your Module

Adding Tabbable Pages

We are going to throw a lot of html in your face right now but quickly review the below html:

You'll notice we've now added a div with a class of "freepbx-container". This is important as it helps our CSS and Javascript match to your page and automatically perform all of the beautifulness that needs to happen. You don't have to do a thing (well besides any special tricks you'd like to perform)

The above HTML will produce output looking like below

You can click on tab2 and watch as javascript hides the first page and shows the second (hidden) page without refreshing the entire page. Everything is still stored on the page so that when the "form" is submitted everything will go along with it. No need to keep track of multiple pages or tags

So lets break apart the HTML used to create this

First and foremost we've got the "freepbx-container" div. Remember that if you want to use tabbing pages you need to wrap the tabs inside of this so that the javascript and css will be applied.

Next up we've got the form element. Make sure you've added all necessary data tags that are needed by the traveling page buttons (such as data-fpbx-delete, the class "fpbx-submit" and role="form"). For more information on this please see Adding Form Buttons to Your Module (Action Bar)

Beyond that we have our "tablist" in which we can see our active tab.

Then we have the wrapper div called "display". Your pages must be wrapped in this div to have the border surrounding them. Each tab is contained in an "info-pane" div with an id that matches the tab's data-name. Make sure to add the "hidden" class to any tab page that should not be shown on initial page load (usually everything but your active tab).

Add Form Elements

Now that we've got a nice tabbed page going on we should add our form elements to each page along with the optional auto hiding help text.

The above page will output the below result. Let's spend some time dissecting each bit.

Here is the only part we are caring about at this point, which is everything inside our first tab.

First off make sure everything is in a "container-fluid" element which gives us a little more padding

The next part is our section. Note the usage of data-id for the section instead of just id. This is because many of the section ids have spaces, which are not valid.

Now we start building the first form element. Make sure to use the wrapper class "element-container" so that everything works as expected!

Lets add some rows and columns to separate everything out. Use the class "control-label" for each label and make sure that the for points to the id of the form element.

Warning: If you don't add 'form-horizontal' to the form-group class, your labels will be too high!

If your form input needs an explanation, you lay it out slightly differently, by adding a 'fpbx-help-icon' and a new full width row. Before adding a help row, think if you could rephrase the name, or add better placeholder text instead!

Remember that any form element you want to error out you simply need to call "warnInvalid" like so (against any jqueried element). This will error out the element until input has changed:

Validation Errors

Special Classes

btn-file

Used to wrap file uploads.

delAction

Adds Confirmation to delete links.

password-meter and toggle-password

Adds a password strength meter and a show hide toggle to password fields.  

clicktoedit

Framework 13.0.7.4+

Makes the field read only until the user clicks on it. This is used in password fields to prevent browsers from auto-populating inappropriately 

Standard Icons

http://fortawesome.github.io/Font-Awesome/icons/

View Functions

Available Framework13.0.1alpha67