Friday 10th April, 2015

Vertical page fitting

In many web-apps and web based control panels it is often desirable to have the displayed layout and content automatically scale to fit the user's browser, allowing you to present a unified and slick interface. Responsive techniques are well developed for how to handle horizontal widths, but vertical resizing brings its own challenges.

In this post I will introduce a new plug-in for DataTables that will automatically change the page length of the table to fit within a given vertical area. The actual DataTables interface is very simple (using only the page.len() method and draw()), but knowing when to change the page length is quite interesting, so I will also discuss the technique used.

A demo using the plug-in is shown below. For the purposes of this demo I've created a resizeable box around the table that you can click and drag, resulting in the table's page length changing automatically to fit the box:

NamePositionOfficeAgeStart dateSalary
Tiger NixonSystem ArchitectEdinburgh612011-04-25$320,800
Garrett WintersAccountantTokyo632011-07-25$170,750
Ashton CoxJunior Technical AuthorSan Francisco662009-01-12$86,000
Cedric KellySenior Javascript DeveloperEdinburgh222012-03-29$433,060
Airi SatouAccountantTokyo332008-11-28$162,700
Brielle WilliamsonIntegration SpecialistNew York612012-12-02$372,000
Herrod ChandlerSales AssistantSan Francisco592012-08-06$137,500
Rhona DavidsonIntegration SpecialistTokyo552010-10-14$327,900
Colleen HurstJavascript DeveloperSan Francisco392009-09-15$205,500
Sonya FrostSoftware EngineerEdinburgh232008-12-13$103,600
Jena GainesOffice ManagerLondon302008-12-19$90,560
Quinn FlynnSupport LeadEdinburgh222013-03-03$342,000
Charde MarshallRegional DirectorSan Francisco362008-10-16$470,600
Haley KennedySenior Marketing DesignerLondon432012-12-18$313,500
Tatyana FitzpatrickRegional DirectorLondon192010-03-17$385,750
Michael SilvaMarketing DesignerLondon662012-11-27$198,500
Paul ByrdChief Financial Officer (CFO)New York642010-06-09$725,000
Gloria LittleSystems AdministratorNew York592009-04-10$237,500
Bradley GreerSoftware EngineerLondon412012-10-13$132,000
Dai RiosPersonnel LeadEdinburgh352012-09-26$217,500
Jenette CaldwellDevelopment LeadNew York302011-09-03$345,000
Yuri BerryChief Marketing Officer (CMO)New York402009-06-25$675,000
Caesar VancePre-Sales SupportNew York212011-12-12$106,450
Doris WilderSales AssistantSydney232010-09-20$85,600
Angelica RamosChief Executive Officer (CEO)London472009-10-09$1,200,000
Gavin JoyceDeveloperEdinburgh422010-12-22$92,575
Jennifer ChangRegional DirectorSingapore282010-11-14$357,650
Brenden WagnerSoftware EngineerSan Francisco282011-06-07$206,850
Fiona GreenChief Operating Officer (COO)San Francisco482010-03-11$850,000
Shou ItouRegional MarketingTokyo202011-08-14$163,000
Michelle HouseIntegration SpecialistSydney372011-06-02$95,400
Suki BurksDeveloperLondon532009-10-22$114,500
Prescott BartlettTechnical AuthorLondon272011-05-07$145,000
Gavin CortezTeam LeaderSan Francisco222008-10-26$235,500
Martena MccrayPost-Sales supportEdinburgh462011-03-09$324,050
Unity ButlerMarketing DesignerSan Francisco472009-12-09$85,675
Howard HatfieldOffice ManagerSan Francisco512008-12-16$164,500
Hope FuentesSecretarySan Francisco412010-02-12$109,850
Vivian HarrellFinancial ControllerSan Francisco622009-02-14$452,500
Timothy MooneyOffice ManagerLondon372008-12-11$136,200
Jackson BradshawDirectorNew York652008-09-26$645,750
Olivia LiangSupport EngineerSingapore642011-02-03$234,500
Bruno NashSoftware EngineerLondon382011-05-03$163,500
Sakura YamamotoSupport EngineerTokyo372009-08-19$139,575
Thor WaltonDeveloperNew York612013-08-11$98,540
Finn CamachoSupport EngineerSan Francisco472009-07-07$87,500
Serge BaldwinData CoordinatorSingapore642012-04-09$138,575
Zenaida FrankSoftware EngineerNew York632010-01-04$125,250
Zorita SerranoSoftware EngineerSan Francisco562012-06-01$115,000
Jennifer AcostaJunior Javascript DeveloperEdinburgh432013-02-01$75,650
Cara StevensSales AssistantNew York462011-12-06$145,600
Hermione ButlerRegional DirectorLondon472011-03-21$356,250
Lael GreerSystems AdministratorLondon212009-02-27$103,500
Jonas AlexanderDeveloperSan Francisco302010-07-14$86,500
Shad DeckerRegional DirectorEdinburgh512008-11-13$183,000
Michael BruceJavascript DeveloperSingapore292011-06-27$183,000
Donna SniderCustomer SupportNew York272011-01-25$112,000
NamePositionOfficeAgeStart dateSalary
Click and drag me!

Use

Using the plug-in is very simple - include the page resizing plug-in from the DataTables CDN on your page:

JS

Then select one of the following two options to enable this feature for your table:

Option 1: Add the pageResize option to your DataTables initialisation:

$('#example').DataTable( {
    pageResize: true
} );

Option 2: Add the class pageResize to your HTML table - e.g.:

<table id="myTable" class="display pageResize">
    <thead> ... </thead>
    <tbody> ... </tbody>
</table>

CSS

The page resize plug-in doesn't require any specific CSS, but you may wish to use CSS to hide the paging length control that DataTables displays by default:

div.dt-length {
    display: none;
}

The other option to hide the page length control is to make use of the layout option.

Additionally, in IE you will find that there is a border that simply cannot be removed using CSS. Unfortunately, the only way to address this is to use a solid colour in your wrapper element's background colour (i.e. the element that defines the height that DataTables should take up):

#myContainer {
    background-color: white;
}

Requirements

  • Paging must be enabled (paging - it is by default in DataTables)
  • Page length change must be enabled (lengthChange - again it is by default)
  • Every row must be of equal height - add the class nowrap to your table if you are using the DataTables default stylesheet. This is to make the fitting calculation fast and efficient.
  • The container element that the DataTable sits in must have a defined height that the table is to fill (the height can be flexible, e.g. vh CSS units).

How it works

The code for this plug-in is tiny - just 4K uncompressed, so you will be able to look through the code and understand how it works very quickly. As a quick run down: it calculates the hight available in the container, removes the heights for the table controls, header and footer and then works out how many rows can be shown in the space remaining based on the row height. Finally the table length is set using page.len() and drawn using draw().

The interesting part comes when we consider how the code knows when to resize. You'll notice in the demo above, a window resize isn't required to redraw the table and no API call is required to tell the component that it has resized.

As only the window object has a resize event we can't just listen for an event on the container element, but what we can do is use the object tag to create a new HTML document, insert it into the container element and then listen for its resize events! The object is setup to fit into the container, so any resize event it fires is a result of a change in size of the host node.

The code for this is also very simple:

var obj = $('<object/>')
    .css( {
        position: 'absolute',
        top: 0,
        left: 0,
        height: '100%',
        width: '100%',
        zIndex: -1
    } )
    .attr( 'type', 'text/html' )
    .attr( 'data', 'about:blank' );

obj[0].onload = function () {
    var body = this.contentDocument.body;
    var height = body.offsetHeight;

    this.contentDocument.defaultView.onresize = function () {
        var newHeight = body.offsetHeight;

        if ( newHeight !== height ) {
            height = newHeight;

            // Resize has occurred - do something!
        }
    }
};

obj.appendTo( host );

This idea is so useful that, if it proves to be a success in this plug-in, I will consider including it in DataTables core, as it would address problems such as being required to call columns.adjust() when a hidden scrolling table is made visible, updating FixedColumns manually on resize and other common gotchas.

Feedback welcome

As always, improvements and suggestions very welcome! The code for this plug-in is hosted on GitHub. If you have any thoughts on improvements, please send a pull request, or open a new discussion in the forums.

One shortcoming I'm particularly keen to address is full integration with Responsive. While Responsive will operate correctly with this plug-in enabled for the most part, child rows that are made visible will not be taken into account in the row count calculation causing vertical alignment problems. This will likely be addressed by introducing a new option to Responsive to show hidden information in a pop-up panel, rather than in a child row.