Best Practices from Oracle Development's A‑Team

Adaptive ADF/WebCenter template for the iPad


A frequently asked question is about adaptive design with ADF/WebCenter Portal and how customers could go about creating an adaptive iPad template for their WebCenter Portal application. Customers are looking not only for the out-of-the-box (OOTB) support for mobile Safari, which is certified against (PS5) for ADF/WebCenter, but also to create a specific template to streamline their workflow on the iPad.

Main Article

But first, let's quickly understand how can we bake in some adaptive goodness into ADF Faces. First thing we need to understand is, yes, there are a couple of constraints that we will need to work around, namely, the use or layout managers and skins. Please also keep in mind that I'm not and I don't pretend to be a web designer, much less an UIX specialist, so feel free to leave your thoughts on the matter in the comments section. Now, back to the limitations.

Layout Managers

ADF Faces layout managers will create an abstraction on top of the generated HTML code for a page, so a developer does not need to be worried about how to size and dimension the UI layout (e.g. af:panelStretchLayout).  Although layout managers can be helpful, in this specific situation we will need to know a little bit more of how the final HTML is being rendered, so we can apply the CSS class accordingly and create transition containers where the media queries will be applied. If you're using 11gR2 ( there is the new component af:panelGridLayout (here and here) that will greatly improve creating responsive templates and pages. Since the af:panelGridLayout is based on the grid/fluid systems, it will generate DIVs in the final page. However, for this sample, I'm limited to the same version that the custom is on (PS5), so the sample will be using the af:panelStretchLayout component as a starting point.


Since media queries and anything with "@" notation cannot be used in the skin CSS file (the skin pre-processor will remove all extraneous "@" from the CSS file), the solution is to split the CSS in two separate files: a skin CSS file and a plain CSS where you will add the media queries. The main issue is that you won't be able to use media queries for any faces components. However, the media queries for the components like af:panelGroupLayout and af:panelBorderLayout can be achieved through their styleClass property.  This will enable these components to be responsive to to the iPad orientation, by changing its dimensions, font sizes, hide/show areas, etc.

Difference between responsive and adaptive design

The best definition of adaptive vs responsive web design I could find is this:

“Responsive web design,” as coined by Ethan Marcotte, means “fluid grids, fluid images/media & media queries.” “Adaptive web design,” as I use it, is about creating interfaces that adapt to the user’s capabilities (in terms of both form and function). To me, “adaptive web design” is just another term for “progressive enhancement” of which responsive web design can (an often should) be an integral part, but is a more holistic approach to web design in that it also takes into account varying levels of markup, CSS, JavaScript and assistive technology support.

Responsive/adapative web design is much more than slapping an HTML template with CSS around your content or application. The content and application themselves are part of your web design - in other words, a responsive template is just an afterthought if it is not originating from a responsive design the involves the whole web application/s.

Tips on responsive / adapative design with ADF/WebCenter

Some of the tips listed below were already mentioned in multiple blog posts about ADF layout and skinning, but it is still worth remembering:

  • A simple guideline for ADF/WebCenter apps would be to first create a high-level group of devices
    • smartphones, tablets,  and desktop.
    • Create a basic structure to provide responsiveness: a page template, a skin, and an external CSS:
      • pagetemplate_smartphone.jspx, smartphone_skin.css, smartphone-responsive.css
      • pagetemplate_tablet.jspx, tablet_skin.css, tablet-responsive.css
      • pagetemplate_desktop.jspx, desktop_skin.css, desktop-responsive.css

These three assets can be changed on the fly through an user-agent check on the server side, delivering the right UI to the right device. Within each of the assets, you can make fine adjustments for each subgroup of devices with media queries.  For example, smart phones with different screen dimensions and pixel density. Having these three groups and the corresponding assets per group seem to be a good compromise between trying to put everything on a single set of assets - specially considering the constraints above - and then going to the other side of the spectrum to create assets per discrete device (iPhone4, iPhone5, Nexus, S3, etc.). Keep in mind that these are my rules and are not in any shape or form a best practice.  The following is the design, which best fits the scenarios that I will be working with:

  • If HTML tags are needed on the page, surround them with an af:group to protect the DOM structure
  • For non-stretchable/fixed layouts:
    • Use non-stretching containers: panelGroupLayout, panelBorderLayout, …
    • panelBorderLayout can be used to approximate HTML table component
    • To avoid multiple scroll bars, do not nest scrolling PanelGroupLayout components. Consider layout=vertical
  • For stretchable/fluid layouts:
    • Most stretchable ADF components also work in flowing context with dimensionsFrom=auto
    • To stretch a component horizontally, use styleClass=AFStretchWidth; do not use width:100%
  • Skinning
    • Don't use CSS3 @media, @import, animations, etc. on skin css files (they will be removed)
    • CSS3 properties within a class (box-shadow, transition, etc.) will work
    • Consider resetting skin classes to better control their rendering:
body {color: inherit;font: inherit;} af|document {-tr-inhibit: all;} af|commandLink {-tr-inhibit: all;} af|goLink {-tr-inhibit: all;} af|inputText::content {font: inherit;}
  • Specific meta tags and CSS properties:
    • To avoid zooming (optional) use
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0"/>
    • Use -webkit-overflow-scrolling: touch to enable native momentum scrolling within overflown areas (here)
    • Use text-rendering: optmizeLegibility to improve readability (here)
    • User text-overflow: ellipsis to gracefully crop overflown text (here)
  • The meta-tags are included in each and every page in the metaContainer facet of af:document tag. You can also use a javascript to inject the meta-tags from the template. For the purpose of the example, I wanted to use as few workarounds as possible.

The iPad template and sample application

This sample application has been built as a WebCenter Portal application, but can reuse the template and techniques in any vanilla ADF application.

Keep in mind that I'm neither a designer nor a CSS specialist, so please don't bash me too much on the messy CSS file you'll find on the application.

To enable the dynamic change of the template and skin, the (default) WebCenter PreferencesBean class has been overridden with custom code.

This is the sample application in landscape orientation:


This is the sample application in portrait orientation - the left side menu hides automatically based on a CSS media query:


A screenshot demonstrating a displayed skinned popup:


In the sample application, the left side bar will have links that are coming from the WebCenter Portal navigation model.  The link will trigger a full request through an af:goLink, while the light blue button will trigger a partial-page-request (PPR) based navigation. The dark blue toolbar buttons at the top and the search box do not have any functions.  In addition, both the Approve and Reject buttons will show a skinned popup.  The sample application can be downloaded here: WebCenterPortalResponsiveTemplate

There's a known issue with some PPR calls that are randomly generating a 403 error redirecting to the login page.




Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content