Introducing PrimeElements with PrimeUI 3.0

Future is here!

PrimeUI 3.0 is now available featuring PrimeElements, the WebComponents library to create user interfaces declaratively with custom html elements. In addition to PrimeElements, template support and defect fixes, there are 4 new components as well.

Web Components is a collection of four specifications to create reusable user interface components. These different technologies are Custom Elements, Shadow DOM, Html Imports and Templates. Modern browsers provide native implementations and javascript libraries called pollyfills are available to use them on older browsers. There are some libraries to create web components easily such as Google Polymer or Mozilla X-Tag while providing additional features.

PrimeElements is an add-on library for PrimeUI that only uses the Custom Elements technology based on X-Tag APIs, a simple and lightweight library to create cross browser custom elements. PrimeElements is a library not a framework, features such as data binding, validation, routing are out of scope since they can be provided by your framework of choice. As they are regular html elements, there are various use cases including integration with a simple REST backend, a javascript mvc framework or implementation in a server side rendering web framework such as PHP, JSP, RoR, Django, ASP.NET MVC, Spring MVC, JavaEE MVC and many more. Advanced cases such as hybrid mobile apps and offline support is also possible since there is no dependency to a server side api.

PrimeElements drastically reduce the amount of work required to create nice looking and functional UIs by providing a rapid application development kit based on standard Web Components technologies. Maintenance effort also benefits from this as there is less amount of script involved. For example Modena for PrimeUI demo provides regular jQuery implementation and PrimeElements implementation of a complex sample page where PrimeElements page is 200 lines less and 5kb smaller in size.

Creation

A common approach to use a widget on a page involves a markup and invoking a jquery plugin on that markup.

<select id="basic" name="basic"> <option value="0">Select One</option> <option value="1">Option 1</option> <option value="2">Option 2</option> <option value="3">Option 3</option> </select> 1 2 3 4 5 6 <select id = "basic" name = "basic" > <option value = "0" > Select One </option> <option value = "1" > Option 1 </option> <option value = "2" > Option 2 </option> <option value = "3" > Option 3 </option> </select>

$('#basic').puidropdown(); 1 $ ( '#basic' ) . puidropdown ( ) ;

On the contrary, elements are created using their tags without need of an initialization script.

<p-dropdown> <option value="1">Option 1</option> <option value="2">Option 2</option> <option value="3">Option 3</option> </p-dropdown> 1 2 3 4 5 <p-dropdown> <option value = "1" > Option 1 </option> <option value = "2" > Option 2 </option> <option value = "3" > Option 3 </option> </p-dropdown>

That is it! As PrimeElements are also regular dom elements, they can be initialized with document.createElement() where you can later attach it to another element.

var dropdown = document.createElement('p-dropdown'); 1 var dropdown = document . createElement ( 'p-dropdown' ) ;

Extending Elements

Some of the PrimeElements extend standard elements instead of providing their own tags, p-button is one of them so same UI can be defined using “is” attribute. Notice that

there is no need for a script anymore as approach is declarative.

<button id="btn" type="button">Save</button> 1 <button id = "btn" type = "button" > Save </button>

$('#btn').puibutton(); 1 $ ( '#btn' ) . puibutton ( ) ;

Extend a Button

<button is="p-button" type="button" id="btn">Save</button> 1 <button is = "p-button" type = "button" id = "btn" > Save </button>

Accessing APIs

Elements can be interacted using their public apis. Example below demonstrates how to show a dialog at a button click.

<button type="button" is="p-button" icon="fa-external-link" onclick="document.getElementById('dlgelement').show()" >Show</button> <p-dialog id="dlgelement" title="Dialog Header" modal showeffect="fade" hideeffect="fade" draggable resizable> <p>Dialog content here.</p> </p-dialog> 1 2 3 4 5 <button type = "button" is = "p-button" icon = "fa-external-link" onclick = "document.getElementById('dlgelement').show()" > Show </button> <p-dialog id = "dlgelement" title = "Dialog Header" modal showeffect = "fade" hideeffect = "fade" draggable resizable > <p> Dialog content here. </p> </p-dialog>

Data Components

A complex example is datatable where there are many options for customization. Regular way is to write the markup and the script.

<div id="tbl"></div> 1 <div id = "tbl" > </div>

$('#tbl').puidatatable({ caption: 'List of Cars', paginator: { rows: 10 }, columns: [ {field: 'vin', headerText: 'Vin', sortable: true, filter: true}, {field: 'brand', headerText: 'Brand', sortable: true, filter: true}, {field: 'year', headerText: 'Year', sortable: true, filter: true}, {field: 'color', headerText: 'Color', sortable: true, filter: true, content: function(car){return $(<span style="color: {{color}};">{{color}}</span>);}} ], datasource: function(callback) { $.ajax({ type: "GET", url: 'rest/cars/list', dataType: "json", context: this, success: function(response) { callback.call(this, response); } }); }, selectionMode: 'single' }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 $ ( '#tbl' ) . puidatatable ( { caption : 'List of Cars' , paginator : { rows : 10 } , columns : [ { field : 'vin' , headerText : 'Vin' , sortable : true , filter : true } , { field : 'brand' , headerText : 'Brand' , sortable : true , filter : true } , { field : 'year' , headerText : 'Year' , sortable : true , filter : true } , { field : 'color' , headerText : 'Color' , sortable : true , filter : true , content : function ( car ) { return $ ( < span style = "color: {{color}};" > { { color } } < / span > ) ; } } ] , datasource : function ( callback ) { $ . ajax ( { type : "GET" , url : 'rest/cars/list' , dataType : "json" , context : this , success : function ( response ) { callback . call ( this , response ) ; } } ) ; } , selectionMode : 'single' } ) ;

PrimeElement shortens the code required using p-datatable and p-column elements.

<p-datatable datasource="rest/cars/list" paginator rows="10" selectionmode="single"> <p-column field="vin" headertext="Vin" sortable filter></p-column> <p-column field="year" headertext="Year" sortable filter></p-column> <p-column field="brand" headertext="Brand" sortable filter></p-column> <p-column field="color" headertext="Color" sortable filter> <script type="x-tmpl-mustache"> <span style="color:{{color}}">{{color}}</span> </script> </p-column> </p-datatable> 1 2 3 4 5 6 7 8 9 10 <p-datatable datasource = "rest/cars/list" paginator rows = "10" selectionmode = "single" > <p-column field = "vin" headertext = "Vin" sortable filter > </p-column> <p-column field = "year" headertext = "Year" sortable filter > </p-column> <p-column field = "brand" headertext = "Brand" sortable filter > </p-column> <p-column field = "color" headertext = "Color" sortable filter > <script type = "x-tmpl-mustache" > < span style = "color:{{color}}" > { { color } } < /span> </s cript > </p-column> </p-datatable>

Containers

PrimeElements can have any content as children just like a standard div element. Here is an example of tabview.

<div id="tabview"> <ul> <li><a href="#tab1">Tab 1</a></li> <li><a href="#tab2">Tab 2</a></li> <li><a href="#tab3">Tab 3</a></li> </ul> <div> <div id="tab1"> Tab 1 Content </div> <div id="tab2"> Tab 2 Content </div> <div id="tab3"> Tab 3 Content </div> </div> </div> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 <div id = "tabview" > <ul> <li> <a href = "#tab1" > Tab 1 </a> </li> <li> <a href = "#tab2" > Tab 2 </a> </li> <li> <a href = "#tab3" > Tab 3 </a> </li> </ul> <div> <div id = "tab1" > Tab 1 Content </div> <div id = "tab2" > Tab 2 Content </div> <div id = "tab3" > Tab 3 Content </div> </div> </div>

$('#tabview').puitabview(); 1 $ ( '#tabview' ) . puitabview ( ) ;

And the PrimeElement way to do the same.

<p-tabview> <p-tab title="Tab 1"> Tab 1 Content </p-tab> <p-tab title="Tab 2"> Tab 2 Content </p-tab> </p-tabview> 1 2 3 4 5 6 7 8 <p-tabview> <p-tab title = "Tab 1" > Tab 1 Content </p-tab> <p-tab title = "Tab 2" > Tab 2 Content </p-tab> </p-tabview>

Events

PrimeElements provide event callbacks prefixed with “on” keyword. An example with rating is below;

<p-rating stars="10" onrate="MyApp.handleRate"></p-rating> 1 <p-rating stars = "10" onrate = "MyApp.handleRate" > </p-rating>

var MyApp = { handleRate: function(event, value) { //value = new rating value } }; 1 2 3 4 5 var MyApp = { handleRate : function ( event , value ) { //value = new rating value } } ;

Premium Layouts and Themes

In addition to the free themeroller based themes, PrimeElements support premium layouts and themes as well to give the elements a great look and a responsive template to work within. Modena, Rio and Adamantium are now available at the brand new PrimeFaces Market.

Download

There are two ways to download the library, simpler way is to use bower and alternative is the zip file bundle. With bower it is easy as running “bower install primeui”. Zip file on the other hand is available at github releases. Check out quickstart page for the installation of the library.

Roadmap

Next major release is 3.1 along with 3.0.x maintenance releases. For 3.1, we plan to add new features to DataTable like frozen rows-columns, add new widgets like MegaMenu and DataList. In parallel, we’re doing proof-of-concept work to create a UI component suite called PrimeNG for AngularJS2.