This document is meant to help guide customers migrating from Wijmo 3 to Wijmo 5. You can follow along with the online sample. The source code is also available in the Wijmo 5 download.

Should I Migrate?

Before you migrate, it is important to understand why and when you should migrate to Wijmo 5. Wijmo 5 is meant for modern Web development and targets modern browsers. Because of this, Wijmo 5 is smaller and faster. Wijmo 3 is meant to support both old and new browsers. This makes Wijmo 3 much larger and slightly slower. Wijmo 5 is also a smaller set of components than Wijmo 3. We chose to focus on a handful of high quality controls (FlexGrid, Charts, Gauges, and Input) and defer to other libraries like Bootstrap for simple things like buttons, layout, etc. Continue to use Wijmo 3 if you rely on certain widgets, such as the Event Calendar, that are not included in Wijmo 5. Here are some scenarios to clarify it.

  • If you need to target older browser versions (mainly IE6, IE7, and IE8) then you should NOT migrate to Wijmo 5.
  • If you can set your minimum browser requirement to IE9, then you can migrate to Wijmo 5.
  • If you are targeting mobile environments only, you can migrate to Wijmo 5.
  • If you rely on any of the Wijmo 3 controls in the following table that do not have an equivalent in Wijmo 5 or an alternative in the right column, then you should continue to use Wijmo 3 and only introduce Wijmo 5 for other controls. Some of the alternative options include UI from Bootstrap, Ionic and HTML5 elements.

Wijmo 3

Wijmo 5

Alternative

Accordion

Bootstrap Accordion

AppView (Mobile)

Ionic Navigation

Bar Chart

FlexChart

Bubble Chart

FlexChart

Calendar

Calendar

CandleStick Chart

FlexChart

Carousel

Bootstrap Carousel

ComboBox

ComboBox

CompositeChart

FlexChart

DataView

CollectionView

Dialog

Bootstrap Modal

Editor

EventsCalendar

Expander

Bootstrap Collapse

Form Decorator

Bootstrap Forms

FileExplorer

FlipCard

Gallery

Grid

FlexGrid

InputDate

InputDate

InputMask

InputMask

InputNumber

InputNumber

LightBox

Linear Gauge

Linear Gauge

Line Chart

FlexChart

List

ListBox

ListView (Mobile)

Ionic List

Maps

Menu

Menu

Pager

Bootstrap Pagination

Pie Chart

FlexPie

Popup

Bootstrap Popover

Progress Bar

Bootstrap Progress bar

Radial Gauge

Radial Gauge

Rating

Ribbon

Scatter Chart

FlexChart

Slider

Input type=range

Sparkline

Splitter

SuperPanel

Tabs

Bootstrap Tabs

Tooltip

Tooltip

Tree

TreeMap

Upload

Input type=file

Video

Video element

Wizard

How to Migrate

The Application

For this exercise, we start with a simple application that has a Wijmo 3 Grid and Line Chart, both bound to JavaScript arrays. We keep it simple to focus on the differences in code and how to migrate. You can follow along with this sample online.

Referencing Wijmo 5

Wijmo 5 has zero dependencies, so you only need to reference the wijmo core (wijmo.js and wijmo.css) and whichever modules you want to use. Note: You can use each module independently. So you only need to include modules for the controls you use. To reference Wijmo 5, download it and copy the files into your project. Then reference the files in your HTML page with markup like the following. We include all modules here for illustration, but only requre wijmo, wijmo.grid and wijmo.chart.

<link href="styles/vendor/wijmo.min.css" rel="stylesheet" />  
<script src="scripts/vendor/wijmo.min.js" type="text/javascript"></script>  
<script src="scripts/vendor/wijmo.grid.min.js" type="text/javascript"></script>  
<script src="scripts/vendor/wijmo.chart.min.js" type="text/javascript"></script>  
<script src="scripts/vendor/wijmo.gauge.min.js" type="text/javascript"></script>  
<script src="scripts/vendor/wijmo.input.min.js" type="text/javascript"></script>

Wijmo 3 and Wijmo 5 can coexist in the same application, so until you have completely migrated to Wijmo 5, you can leave the Wijmo 3 files and references in your project.

Working with Data

In Wijmo 3, many people bind widgets to plain JavaScript arrays. In this application, we follow the same pattern. We have two arrays: one holds 100 records for the grid and one holds 12 records for the chart. Here is the code we use to create our arrays of data.

//populate array with data for Grid  
var rawData = data.getData(100);   

//populate array with data for Chart  
var chartData = data.getData(12);

The getData function in this case generates a JavaScript array of objects, but an Ajax request to get a JSON result would be more common. This code is not significant, but might be useful to you for clarity.

// data for the sample  
var appData = {  
    // create simple flat data  
    getData: function (count) {  
        var countries = 'US,Germany,UK,Japan,Italy,Greece'.split(','),  
            data = [];  

        for (var i = 0; i < count; i++) {  
            data.push({  
                Id: i,  
                Country: countries[i % countries.length],  
                Date: new Date(2014, i % 12, i % 28),  
                Amount: Math.random() * 10000,  
                Active: i % 4 === 0  
            });  
        }  
        return data;  
    }  
};

In Wijmo 5, we have introduced CollectionView, a data API based on the .NET API with the same name. You can bind all of the controls to CollectionView and utilize it heavily. For example, FlexGrid offloads all of its data operations to the CollectionView. The good news is that we can continue to use the same array that Wijmo 3 uses and create a new CollectionView using the JavaScript array as the source data. We will do this for both of the arrays we created.

//create a Wijmo 5 CollectionView from the rawData array  
var cv = new wijmo.collections.CollectionView(rawData);  

//create a Wijmo 5 CollectionView from the chartData array  
var chartcv = new wijmo.collections.CollectionView(chartData);

Note: You are not required to create CollectionViews. If you wish, you can pass the JavaScript arrays directly to Wijmo 5 controls. The Wijmo 5 controls internally convert them to CollectionViews before data binding.

Porting the Grid

The first thing we need is an HTML element to initialize our grid against. In Wijmo 3, we use an HTML

element, but in Wijmo 5, we use a
element. In this example, we set a static height of 300 pixels on the elements.

Wijmo 3

<table id="mywijgrid" style="height:300px;">  
</table>

Wijmo 5

<div id="myFlexGrid" style="height:300px;">  
</div>

Next, we need to create a new FlexGrid on the

element and initialize it. I won’t go through this code line by line, but I will mention some important parts.

Wijmo 3

//create and bind Wijmo 3 wijgrid  
$('#mywijgrid').wijgrid({  
    columnsAutoGenerationMode: 'none',  
    data: rawData,  
    allowSorting: true,  
    scrollMode: 'auto',  
    selectionMode: 'singleRow',  
    ensureColumnsPxWidth: true,  
    columns: [  
        {  
            dataKey: 'Id',  
            dataType: 'number',  
            dataFormatString: 'n0',  
            width: '20%'  
        },  
        {  
            dataKey: 'Country',  
            width: '20%'  
        },  
        {  
            dataKey: 'Date',  
            dataType: 'datetime',  
            width: '20%'  
        },  
        {  
            dataKey: 'Amount',  
            dataType: 'currency',  
            width: '20%'  
        },  
        {  
            dataKey: 'Active',  
            dataType: 'boolean',  
            width: '20%'  
        }  
    ]  
});

Wijmo 5

//create and bind Wijmo 5 FlexGrid  
var myFlexGrid = new wijmo.grid.FlexGrid('#myFlexGrid');  
myFlexGrid.initialize({  
    autoGenerateColumns: false,  
    itemsSource: cv,  
    isReadOnly: true,  
    selectionMode: wijmo.grid.SelectionMode.Row,  
    headersVisibility: wijmo.grid.HeadersVisibility.Column,  
    columns: [  
        {  
            binding: 'Id',  
            width: '*'  
        },  
        {  
            binding: 'Country',  
            width: '*'  
        },  
        {  
            binding: 'Date',  
            width: '*'  
        },  
        {  
            binding: 'Amount',  
            format: 'c0',  
            width: '*'  
        },  
        {  
            binding: 'Active',  
            width: '*'  
        }  
    ]  
});

Important things to note:

  • In Wijmo 5, we create a new instance of a FlexGrid against a DOM element. Then we call an initialize method on the new control. In Wijmo 3, we do both at once (using the jQuery UI Widget Factory pattern).
  • In Wijmo 5 we data bind the itemSource property to a CollectionView instead of the raw array of data.
  • In Wijmo 5, properties with multiple options have Enums to help make setting the value easier and less error prone. For example, in the Wijmo 3 wijgrid, we set selectionMode: 'singleRow' which is a string and could easily be mistyped. In the Wijmo 5 FlexGrid, we set selectionMode: wijmo.grid.SelectionMode.Row which is an Enum and even provides auto-completion in certain code editors.
  • In Wijmo 3, we have to set ensureColumnsPxWidth: true in order to customize the column widths to anything precise.
  • In Wijmo 5, we support star-sizing for column widths. To evenly distribute column widths, give them each one star (instead of calculating the percentage based on total columns divided by 100).
  • In Wijmo 5, there is no need to specify dataType for each column. It is inferred based on data. This seems inconsequential, but it makes the grid much easier to use without setting properties. It also provides default formatting for the dataTypes it infers.
  • In Wijmo 5, editing is enabled by default, so we set isReadOnly: false to disable it.
  • In Wijmo 5, row and column headers are visible by default, so to match Wijmo 3, set headersVisibility: wijmo.grid.HeadersVisibility.Column to show only column headers.

And here is our result. Two grids, bound to the same data and displaying a similar configuration.

Porting the Chart

Now it’s time to add a Wijmo 5 FlexChart. We need an HTML element to initialize our chart against. Both Wijmo 3 and Wijmo 5 use a

element to create charts. In this example, we set a static height of 300 pixels on the elements.

Wijmo 3

Wijmo 5

Next, we need to create a new FlexChart on the

element and initialize it. Again, I won’t go through this code line by line, but I will mention some important parts.

Wijmo 3

//create and bind a Wijmo 3 Line Chart  
$('#mywijlinechart').wijlinechart({  
    dataSource: chartData,  
    showChartLabels: false,  
    header: {  
        text: 'Sales Report'  
    },  
    legend: {  
        visible: false  
    },  
    axis: {  
        x: {  
            annoFormatString: 'MMM'  
        },  
        y: {  
            annoFormatString: 'c0'  
        }  
    },  
    seriesList: [  
        {  
            label: 'Sales',  
            data: {  
                x: {  
                    bind: 'Date'  
                },  
                y: {  
                    bind: 'Amount'  
                }  
            }  
        }  
    ]  
});

Wijmo 5

//create and bind a Wijmo 5 FlexChart  
var myFlexChart = new wijmo.chart.FlexChart('#myFlexChart');  
myFlexChart.initialize({  
    chartType: wijmo.chart.ChartType.Line,  
    header: 'Sales Report',  
    legend: {  
        position: wijmo.chart.Position.None  
    },  
    axisX: {  
        format: 'MMM'  
    },  
    axisY: {  
        format: 'c0'  
    },  
    itemsSource: chartcv,  
    bindingX: 'Date',  
    series: [  
        {  
            binding: 'Amount',  
            name: 'Sales'  
        }  
    ]  
});

Important things to note:

  • In Wijmo 5, we create a new instance of a FlexChart against a DOM element. Then we call an initialize method on the new control. In Wijmo 3, we do both at once (using the jQuery UI Widget Factory pattern).
  • In the Wijmo 5 FlexChart (similar to the FlexGrid) we data bind the itemSource property to a CollectionView instead of the raw array of data.
  • In Wijmo 5, properties with multiple options have Enums to help make setting the value easier and less error prone. Notice, in the Wijmo 5 FlexGrid, we set chartType: wijmo.chart.ChartType.Line which is an Enum and even provides auto-completion in certain code editors.
  • In the Wijmo 5 FlexChart, setting the format for the axis applies the format everywhere it is applicable, like the tooltip. In Wijmo 3, you have to apply formatting in each place that you want it.
  • In Wijmo 5, we have a single chart control (with the exception of the pie chart) that supports multiple types. In Wijmo 3, we have separate widgets for each type. The reasons for combining all of the Cartesian chart types are that they share almost all of the same properties, and that it is easier to change the chart type dynamically in Wijmo 5.
  • In Wijmo 5, many of the properties have been simplified and can be set at the root control level. In Wijmo 3, many properties require nested objects to configure properly. For example, setting the header text in the Wijmo 5 FlexChart is a single line of code like header: 'Sales Report' while the Wijmo 3 line chart requires an object with a sub property like header: { text: 'Sales Report' }
  • In the Wijmo 5 FlexChart, you always bind the X axis at the control level. Then you add Y axis series objects to the series collection. In the Wijmo 3 line chart, you add X and Y bindings to the seriesList collection.
  • The default series colors are different for Wijmo 3 and Wijmo 5. They could be made to match, but were left to defaults for this application. Wijmo 5 offers built-in palettes to choose from for series colors as well.

And here is our result. Two charts, bound to the same data and displaying a similar configuration.

Modifying Controls

Now that we have created the controls, we can begin to modify them. In this application, we have a button that modifies the grid’s sort. When the button is clicked, we sort the grid by the Amount column.

Wijmo 3

//Sort Grid when button clicked  
$('#btnSortWij').click(function () {  
    $('#mywijgrid').wijgrid('columns')[3].options.sortDirection = 'ascending';  
    $('#mywijgrid').wijgrid('ensureControl', true);  
});

Wijmo 5

//Sort Grid when button clicked  
document.getElementById('btnSortFlex').addEventListener('click', function () {  
    var sdNew = new wijmo.collections.SortDescription('Amount', true);  

    // remove any old sort descriptors and add the new one  
    cv.sortDescriptions.splice(0, cv.sortDescriptions.length, sdNew);  
});

Important things to note:

  • In Wijmo 5, we always work with the data, specifically the CollectionView. So in this example, unlike in Wijmo 3, we do not even access the FlexGrid in code. Instead we sort the CollectionView that the FlexGrid is bound to.
  • In Wijmo 5, we specify the property name we want to sort by. In Wijmo 3, we find the column by index and set its sortDirection.
  • In Wijmo 3, we must call the ensureControl method to tell the grid that it needs to redraw the table. If we do not call it, the grid does not display the new sort direction.
  • The Wijmo 5 FlexGrid automatically redraws when its data source changes.
  • This sample code uses jQuery for the Wijmo 3 sample code, but plain JavaScript for the Wijmo 5 sample code. Wijmo 5 has no dependencies so you can use plain JS when working with it.

Getting and Setting Properties

Another way to modify controls is to change properties after initialization. In Wijmo 5, we have created true JavaScript controls that offer real property getters and setters. We were able to accomplish this by utilizing ECMAScript 5’s Object.defineProperty. In contrast, with Wijmo 3, we used the jQuery UI pattern of calling methods to set properties. Wijmo 5 is unique in this way. We have revamped the way you work with our UI controls in JavaScript, and we think you will like it. It is a familiar control pattern used in .NET and other platforms.

Wijmo 3

//Show Row Headers in Grid when button clicked  
$('#btnHeadersWij').click(function () {  
    //Check if row headers are shown or not and show/hide them accordingly  
    if ($('#mywijgrid').wijgrid('option', 'showRowHeader') === true) {  
        $('#mywijgrid').wijgrid('option', 'showRowHeader', false);  
    }  
    else {  
        $('#mywijgrid').wijgrid('option', 'showRowHeader', true);  

    }  
});

Wijmo 5

//Show Row Headers in Grid when button clicked  
document.getElementById('btnHeadersFlex').addEventListener('click', function () {  
    //Check if row headers are shown or not and show/hide them accordingly  
    if (myFlexGrid.headersVisibility === wijmo.grid.HeadersVisibility.All) {  
        myFlexGrid.headersVisibility = wijmo.grid.HeadersVisibility.Column;  
    }  
    else {  
        myFlexGrid.headersVisibility = wijmo.grid.HeadersVisibility.All;  
    }  
});

Important things to note:

  • In Wijmo 5, we work with controls as classes with true properties. This lets us get and set property values directly and the control can react to those changes.
  • In Wijmo 3, we must call the widget method and pass in ‘option’ in order to get or set an option. We then pass in the option name as a string. And then if we want to set a value, we pass the value in as the third parameter. This is awkward syntax and is also error prone due to the case-sensitivity of the strings.
  • With Wijmo 5, we can set property values to Enum values to avoid typos. Some text editors even provide auto-completion for these values.
  • In Wijmo 5, both the row headers and column headers are configured using a single property. For example, setting the value to Column shows only column headers. Setting the value to All shows both row and column headers. In Wijmo 3, this is done with separate options.
  • Working with properties in Wijmo 5 is one of the biggest benefits of our new control architecture compared with the classic widget pattern.
  • This sample code uses jQuery for the Wijmo 3 sample code, but plain JavaScript for the Wijmo 5 sample code. Wijmo 5 has no dependencies, so you can use plain JS when working with it.
  • The code for this can be much more concise, but I wrote it out like this to clearly convey the getter and setter patterns for each.

Event Handling

Lastly, we add an event handler to our grid. For this sample, we are adding a handler for the selectionChanged event in the grid. When the event occurs, we update a span tag with the Amount value in the selected row.

Wijmo 3

//Bind to selectionChange in wijgrid  
$("#mywijgrid").bind("wijgridselectionchanged", function (e, args) {  
    var amt = args.addedCells.item(3).value();  

    //set text of span tag to Amount value  
    $('#lblWij').text(amt);  
});

Wijmo 5

//Bind to selectionChange in FlexGrid  
myFlexGrid.selectionChanged.addHandler(function (e, args) {  
    var amt = myFlexGrid.rows[args.row].dataItem.Amount;  

    //set text of span tag to Amount value  
    document.getElementById('lblFlex').innerHTML = amt;  
});

Important things to note:

  • In Wijmo 3, we use the jQuery bind method for event handling along with a naming convention. The convention is widget name + event name, all in lowercase. This approach is error prone since we are using strings with a specific convention to specify the event name.
  • In Wijmo 5, we add a handler to the actual event object. So we access the selectionChanged event object and call the addHandler method. This approach is much less error prone than the Wijmo 3 approach.
  • In Wijmo 5 we find the value by property name. In Wijmo 3, we find the data by column index.
  • Working with event data is similar between Wijmo 3 and Wijmo 5.
  • This sample code uses jQuery for the Wijmo 3 sample code, but plain JavaScript for the Wijmo 5 sample code. Wijmo 5 has no dependencies, so you can use plain JS when working with it.

Conclusion

As you can see, there are definitely some differences between the Wijmo 3 widgets and Wijmo 5 controls. Some differences are small and subtle; some are more significant. Hopefully this example helps to show you the default values in Wijmo 5 that are different from those in Wijmo 3. As for finding similar features, the Wijmo 5 documentation is very helpful for looking up property names, etc. Another important thing to note is the difference in philosophies behind the controls. The Wijmo 5 FlexGrid is not a full-featured grid, but the Wijmo 3 grid is. The Wijmo 5 FlexGrid is meant to be a fast and lightweight control that offers extensibility for easily adding features you want. For example, we do not build filtering or paging into the FlexGrid, but they are easily achieved through the CollectionView API. Good luck in migrating your applications to Wijmo 5 and please feel free to send us any questions you have during the process.

Categories: Sample, Tutorials, Web

Tags: HTML5, JavaScript, wijmo5, migrate, porting, tutorials, sample, Wijmo

About the Author

Chris Bannon

Chris Bannon is a corny dad, a lighthearted guy, and a hard-working programmer. He takes his work very seriously, but not himself.

While his work is important, he values his family most. He spends most of his time with his wife and daughters. You can also find him playing amateur ice hockey for the Pittsburgh Pharaohs.

Chris Bannon is currently the Global Product Manager of Wijmo at GrapeCity. He started working at ComponentOne, a division of GrapeCity, in 2007 as their Lead Web Developer. After rebuilding ComponentOne’s entire web stack, he moved to product management to create a web product of his own: Wijmo. Wijmo is now a multi-million dollar developer tool and is used by fortune 500 Companies like Microsoft, Thomson Reuters, NASA and Tesla. Chris started his education by becoming a Certified Internet Webmaster. He went to college, but most of what he has learned has been in the field. Chris travels to speak around the world. If you ever see him, please don't hesitate to say hi.

Comments