BlackBerry Developer Blog » layout

BlackBerry 10 UI Layout patterns for HTML5 Applications

Anzor B. — Tue, 02 Apr 2013 15:18:05 +0000

Full source code with comments is available at: https://github.com/blackberry/BB10-WebWorks-Samples/tree/master/UI-Layouts

A typical BlackBerry 10 application consists of a number of full-screen views, containing elements (headers, footers, lists, buttons, etc…) that are stacked to take up available screen estate.

This article outlines layout techniques that may be used to create such views in HTML5/WebWorks applications, targeting the BlackBerry Z10 and BlackBerry Q10.

This is a typical vertical stack layout with a header, content and footer. The header and footer typically have a fixed height, while the content section stretches up to fill available space depending on screen size.

Absolute/Fixed layout pattern

The absolute/fixed layout allows developers to position elements anywhere on the screen using x and y coordinates. This is not uncommon in layouts today, and is quite easy to implement as long as the number of root elements (header,content,footer) remains low. The developer is required to provide exact dimensions and positions of all elements so they don’t overlap and appear to be ‘stacked’. As the number of root elements increases – for example we add a search bar to the root, it’s top value is positioned at (height of header) px, while content top is be positioned at (height of header + height of search bar) px, and so on.

Source with comments here: https://github.com/anzorb/UI-Layouts/tree/master/absolute

HTML:

CSS:

/* set all sections to absolute */
body,html,.container{
	width:100%;
	height:100%;
	background: #181818;
	margin:0;
}

/* set all sections to absolute */
header,
.content,
footer{
	position: absolute;
}

/* when absolute, we need to explicitly specify the top and bottom coordinates to fill content in */
.content{
	top:240px;
	bottom:120px;
	width:100%;
	background:#181818;
	/* scrolling properties */
	overflow: scroll;
	-webkit-overflow-scrolling: touch;
}

/* common attributes, such as background color and width to stretch to cover the whole screen */
header,
footer{
	background:#bbbbbb;
	width:100%;
}

/* when using absolute, it makes more sense to place the search bar inside of header */
header {
	top:0;
	height: 220px; /* 100 (search bar) + 120 (self) */
}

/* positioned at the bottom of our container */
footer {
	height:120px;
	bottom:0;
}

Pros:

Cross-platform (works across 100% of mobile and desktop browsers)

Cons:

Developers are required to provide exact measurements, and number of root elements needs to remain low to avoid manual calculations.

Stack/Flexible layout pattern

Source: http://www.html5rocks.com/en/tutorials/flexbox/quick/

While targeting smartphone applications, developers often need to stack components to take up the available screen height. Header, content and footer sections appear under one another, with the content section flexible and scrollable if its contents overflow the available height. Other elements, such as the search bar can be inserted into the stack, pushing content down and decreasing the height of any flexible regions automatically.

With flex-box, creating a stack layout is easy as it relies on the browser engine to decide how to position and stretch elements to fill the screen. All elements remain relatively positioned which means we are no longer required to provide top or bottom values, and choose which elements have fixed widths and which are to remain flexible.

Please note: At the time of writing this article, the flex-box standard has split into ‘old’ flex-box and ‘new’ flex-box. The new flex-box standard support is nearly non-existent or broken in most browsers. Although BlackBerry 10 supports both standards – I chose to focus on the old flex-box in this article for wider browser support. The concept remains the same – flex-box allows stack layouts for web applications.

Source with comments here: https://github.com/blackberry/BB10-WebWorks-Samples/tree/master/UI-Layouts/box

HTML

CSS

/* set your container's display to -webkit-box */
.container{
	display: -webkit-box;
	-webkit-box-orient: vertical;
	-webkit-box-align: stretch;
}

/* setting contents flexibility to 1, ensures that it stretches to fill available space */
.content{
	-webkit-box-flex: 1;
	width:100%;
	background:#181818;
	overflow: scroll;
	-webkit-overflow-scrolling: touch;
}

/* fixed heights for header and footer */
header,
footer{
	background:#bbbbbb;
	height:120px;
	width:100%;
}
/* OR flexible heights thanks to flex-box
header.flexible{
	height: auto;
}

The -webkit-box-flex: 1; property is the ratio of how much available space is allocated to the element relative to other elements. So if we wanted to have two content sections on top of one another, taking up the same height while remaining flexible and adapting to available screen space, we can add the same property (webkit-box-flex: 1) to our second content section. Since the ratio is 1:1, both will take up the same room, while stretching as available screen estate increases.

The Stack/Flexible layout also simplifies use cases where headers/footers and other elements need to remain flexible. For example in an application that displays news articles the header displays news articles’ titles and may take up anywhere from a single line to 3 lines vertically. Ideally, especially when using gradient we want the header to stretch as to not truncate the text :

Developers can also leverage min-height and max-height to tell the renderer how flexible the header will be. Since header is a child of container, and container is flexible, no other properties are required.

/* this allows header to grow up to 170px, which allows for the use case discussed above */
header{
	max-height:170px;
	line-height:45px;
}

Pros:

Truly flexible, no exact dimensions are required.

Offers a ‘stack’ layout model to HTML5 developers, not uncommon among Cascades developers.

Cons:

Confusion over new and old flex-box.

Browser support (not supported in IE and Opera).

*Although a library exists that ports functionality to IE 6-9 and Opera 10

https://github.com/doctyper/flexie

Detecting and adapting to Landscape orientation

Source code here: https://github.com/blackberry/BB10-WebWorks-Samples/blob/master/UI-Layouts/box/media-queries.css

The BlackBerry Z10 screen is 720px wide, which means that we have 720px of screen height to work with when the device is in landscape. It is often good practice to resize certain elements such as the header and/or footer to allow for more content. The following example demonstrates how to use CSS Media Queries to increase the amount of content visible when in landscape:

Here’s the CSS that makes this possible.

@media screen and (orientation:landscape){
     header
     ,footer{
	height:90px;
     }
}

The Landscape orientation media query is triggered when viewport height is less than viewport width. This means that if the device is in portrait, and we pull up the keyboard, landscape orientation will also get triggered, resulting in the rules above applied even though the device is in portrait. This is because the virtual keyboard causes a decrease in the screen height to a point where screen is a few pixels shorter than it is wide. This may be an issue if for example the footer contains wider buttons in landscape. The user will see the buttons get wider as the virtual keyboard pops-up – not the best User Experience.

One way to tackle this is by adding a width property:

/* detect landscape orientation and device width of 1280px */
@media all and (orientation:landscape) and (width:1280px){
     header
     ,footer{
	height:90px;
     }
}

This restricts our rule to only be in effect when the screen width (or innerWidth) is 1280, in other words, only if device is really in landscape.

A number of core BlackBerry 10 Applications allow the virtual keyboard to overlay the action bar. This allows for greater screen estate, especially if the application relies on messaging a lot (think BBM for example).

A good practice is to have a minimum height where all elements are displayed, and if height is smaller, begin to hide the elements to allow for more content.

The virtual keyboard is 413px high in portrait and 274px high in landscape.

Remaining space when the keyboard is up:

1280 – 413 = 867px (portrait 1280×720 or 1280×768)

768 – 274 = 494px (landscape 1280×768)

720 – 274 = 446px (landscape 1280×720)

This means we can target 450px as the minimum height in landscape and 870px in portrait.

Using CSS Media Queries, let’s hide the header and footer if height does not exceed 450px/870px:

/* hide header and footer when available height is shorter than target */
@media 
all and (max-height:870px) and (max-width: 768px), /* portrait 1280x720 and 1280x768 */
all and (max-height:450px) and (width: 1280px) /* landscape */
{
    header,footer{
		display:none;
	}
}

Before with VKB up – portrait:	After with VKB up – portrait:

Before with VKB up – portrait:	After with VKB up – portrait:

CSS Media queries also allow developers to target specific devices, by detecting device height and width. The following rules apply if the device screen is 720×720, making the header and footer shorter to allocate more room to the content section.

/* detect BlackBerry Q10 and make header and footer shorter for more screen estate  */
@media all and (width:720px) and (height: 720px)
{
    header,
    footer{
            height: 90px;
    }     
}

Since the BlackBerry Z10 offers 768px of screen height when in landscape, while the Q10 offers 720px, it is often easier to apply the same rules to both, as to provide more content in both cases, without having to maintain two separate sets of rules for each.

Here’s how the above rule can be combined with one mentioned earlier:

/* detect landscape orientation and Q10 device */
@media 
all and (orientation:landscape) and (width:1280px),
all and (width:720px) and (height: 720px)
{
     header
     ,footer{
	height:90px;
     }
}

Please note that these CSS queries are designed for the flexible layout model only .There would have to be more rules to make it work with the fixed model, as we are required to provide exact positions changes along with size changes when orientation changes – another pro for the flexible box model.

In conclusion, it’s worth noting that both code quality and performance improve when leaving the layout tasks to the layout engine (CSS), rather than detecting orientation/screen size using JavaScript and applying classes/style. The stack model has been used by Native developers for quite some time and is finally making a debut to HTML5 and provides an intuitive way to create layouts that adapt across devices with different form factors.

Be sure to check out the full source code here (https://github.com/blackberry/BB10-WebWorks-Samples/tree/master/UI-Layouts) and save it for when you are working on the layout of your next BlackBerry 10 application.

Sources

QUICK HITS WITH THE FLEXIBLE BOX MODEL by Paul Irish

http://www.html5rocks.com/en/tutorials/flexbox/quick/

Media Queries for Standard Devices

http://css-tricks.com/snippets/css/media-queries-for-standard-devices/

Time well spent: An intuitive interface design is the difference between app success and mediocrity

Matt W — Mon, 02 Apr 2012 19:06:32 +0000

Nothing is more frustrating than putting countless hours of hard work into your BlackBerry® app, making sure every subroutine is perfect and every millisecond of performance squeezed, only to find out that users are displeased with some aspect of layout or interaction. Speaking from experience, I find that numerous times we all too often dive into architecting and developing the meat and potatoes of an app, leaving the user interface to get created ad hoc. Yet behind every good app there is a great user interface!

Now, you might be saying: “But Matt! I do think about layout and design – but I can’t design for every user’s tastes.” While we do typically put some thought into layout and design, I find we (as developers) rarely think about it from an end user’s perspective. We are too close to the project, and end up seeing aspects of the application from a specific view. Think of it this way – every parent thinks their baby is the cutest ever…but what do the rest of us think? What a good app developer/designer needs to do is take a step back and look at the design from others’ points of view and, better yet, gather points of view from others.

Nothing helps guide a design better than real world feedback. Take your design and layouts and talk to your peers, your mother, your granddad, or even your future end users (basically anyone that will talk to you.) You can even solicit feedback from a limited beta of your app or use various online solutions such as getsatisfaction.com. Ask your users what they like, what they don’t like, how they would expect things to flow, and so on. Taking this feedback and integrating it into your app will help ensure users are happy – and happy users mean good BlackBerry App World™ storefront ratings!

If you cannot easily gather end user feedback on the design and flow of your app, here are some other points to keep in mind at the beginning of your project:

Keep the user interface and design as simple as possible. Your app should require a user to have little to no instructions in order to get started.
For touch screen devices, ensure proper spacing of objects that a user will interact with. Nothing will frustrate your users more if their touch events are misread.
The layout of the screen should be well used, but not too cluttered. For objects in groups, space them evenly for a clean look.
Make use of menus when required. Menus are great when there are additional options or settings that you want a user to have access to, but don’t want to have them always displayed on screen.
Lastly, remember to keep your app consistent. Every screen within the app should offer a similar user experience in layout, theme and flow. A user should know this is your app regardless of the screen they are looking at.

Hopefully you have found these tips useful. If you have your own, please share them in the comments section below or head on over to the BlackBerry Developer Support forums and post them there.

How to use Table View layout

Shiladitya S. — Wed, 14 Oct 2009 22:50:22 +0000

Every layout is unique and highly dependent upon the application using it. However, the basic building block for any complex layout is a cell. Each cell can define its space requirements or share with adjacent cells. If we try to visualize this arrangement it will look much like a table. With TableLayoutManager (full sample code here), which can handle fixed or relative cell sizes and allow embedding tables, developers can build almost any layout they want very easily. I am not going to focus today on how to build a layout manager, as there are ample BlackBerry® Developer Zoneresources on this topic. Instead, I will explore the possibilities of how TableLayoutManager can be used. TableLayoutManager has two constructors:

public TableLayoutManager(int columnStyles[], long style)

public TableLayoutManager(int columnStyles[], int columnWidths[], int horizontalPadding, long style )

columnStyles[] defines the styles for all columns, and the number of this array refers to the number of columns desired in a given row. The different column styles to choose from are listed below:
USE_PREFERRED_SIZE – Allows the field to use up all the space it needs.
USE_PREFERRED_WIDTH_WITH_MAXIMUM – Allows the field to use up as much space as it needs UP TO a preset maximum. You can specify the maximum for each field by passing in the width in the columnWidths variable.
SPLIT_REMAINING_WIDTH – Columns will use up the remaining width evenly.
FIXED_WIDTH – Sets columns to a fixed width.

The SPLIT_REMAINING_WIDTH style can be thought of as the “this column will utilize all the remaining width of the table” style. So if TableLayoutManager has a column defined as SPLIT_REMAINING_WIDTH in conjunction with Manager.USE_ALL_WIDTH, the column will fill the remaining space. If there are multiple columns defined as SPLIT_REMAINING_WIDTH, they will evenly share that remaining width.

style – is the manager style. You can just choose from Manager. HORIZONTAL_SCROLL, Manager.xxxx.

columnWidths – if you choose you can specify widths to be used for each field for force particular columns size.

horizontalPadding – you can also specify horizontal padding between columns .

As you can see above, it’s pretty easy to define the desired amount of columns. Based on number of fields added to the layout, TableLayoutManager will automatically align them in separate rows to keep the desired number of columns. This can often be a helpful feature, as developers won’t need to know the number of rows their table may have at construction time.

Now let’s explore some views that are possible with TableLayoutManager.

Example 1: Say you are building your next great application that requires cover art to be displayed as a grid like view.

This view has five columns, each of which is a BitmapField and each field will accept focus . This table can be constructed very easily with TableLayoutManager. Here is a code sample of how I constructed the table:

TableLayoutManager colFMgr = new TableLayoutManager(new int[] { TableLayoutManager.USE_PREFERRED_SIZE, TableLayoutManager.USE_PREFERRED_SIZE, TableLayoutManager.USE_PREFERRED_SIZE, TableLayoutManager.USE_PREFERRED_SIZE, TableLayoutManager.USE_PREFERRED_SIZE }, Manager.HORIZONTAL_SCROLL);

for(int i= 0;i < images.length;i++) { colFMgr.add(new BitmapField(images[i],Field.FOCUSABLE)); } add(colFMgr );

If you want a little more control on bitmap sizes and how the layout manager uses each cell size you can use the other constructor to pass in widths for each column.

Example 2: Now say I wanted some text below each image but did not want the text to take primary focus.

As you can see, it’s the same structure as Example 1, but for every five BitmapFields, I would have to add five Label fields and disable focus on the Labels. TableLayoutManager will take care of the layout and ordering.

Example 3: Now consider using a table view where the left column contains an image and right columns contain some textual description with a ‘more’ link.

Conceptually, the per-row view in wireframe would be an outer table with 2 columns:

And an inner table with two columns to host some textual description:

The inner table is inserted within the COL 1 of the outer table to get our desired view for a given row. Note that the space alignments are configurable based on the style you choose on the layout manager.

Now that we have constructed each row, you can keep adding COL 1(flower art bitmap) and COL 2 (inner table) and it will take the form as shown in the Example 3 screen shot. All this translates in very little code using TableLayoutManager:

TableLayoutManager outerTable = newTableLayoutManager(new int[] { TableLayoutManager.USE_PREFERRED_SIZE, TableLayoutManager.SPLIT_REMAINING_WIDTH },0);

For constructing the inner table:

TableLayoutManager innerTable = new TableLayoutManager(new int[] { TableLayoutManager. USE_PREFERRED_SIZE, TableLayoutManager.USE_PREFERRED_SIZE }, Manager.USE_ALL_WIDTH);

In the second case, USE_ALL_WIDTH causes the table to fill the maximum width space. The first USE_PREFERRED_WIDTH will allow COL 1 to take up the minimum necessary amount of space, and COL 2 will automatically fill to fit. If you want COL 2 to use the minimum size, set COL 1 to SPLIT_REMAINING_WIDTH.

Here’s how to add the fields to the inner table:
innerTable.add(titleField); innerTable.add(titleField1); innerTable.add(descriptionField); innerTable.add(descriptionFieldLink); innerTable.add(ratingField); innerTable.add(ratingFieldImage);

And how to add a bitmap field to the outer table and add the inner table.
outerTable.add(Bitmap.getBitmapResource("image1.png"))); outerTable.add(innerTable);

To add more rows to this table, keep adding bitmaps and inner tables to the outer table. And don’t forget to add the outer table to the Screen!
super.add(colFieldMgrForRow);

This is not the only way to build a layout like this. For example, for each row I can use a horizontal layout manager (hfm) with two columns. The second column for this hfm would need a vertical field manager (vfm), for which I need three hfm for each row of text (title, description, rating etc). So really there is no one size fits all for layout management. It’s simply a matter of picking the right one that works for your application.