WebCenter Portal Template Design Best Practices

Collaborate 2012 was a great event for the WebCenter product stack at Oracle. Excellent customer turnout, combined with a wealth of resources for WebCenter, helped to make this a very worthwhile event. I presented the following deck to provide an overview of WebCenter Template development and design best practices. Hope that these tips are helpful in your deployments.

WebCenter Portal
Template Development and Design Best Practices
John Brunswick | Oracle Principal Sales Consultant
In our presentation WebCenter Portal Template Development and Design Best Practices we will take a look at foundational elements that will help you be successful with designing and developing your website portal user interface.
.AFInstructionText,.x0,.PortletText1,.xcg,.PortletText2,.xch,.PortletText3,.xci,.PortletText4,.xcj,.portlet-form-field,.xd8,.x1lc,.x1ld,.x1le,.x1lf,.x1lg {font-family:Tahoma,Verdana,Arial,Helvetica,FreeSans,sans-serif;font-weight:normal;font-size:11px;color:#555555}.AFInstructionTextDisabled,.x1,.AFFieldTextDisabled,.x7,.x1u.p_AFDisabled.x2p .x25,.x1u.p_AFDisabled.x2q .x25,.x1u.p_AFDisabled.x2r .x25,.x1u.p_AFDisabled.x2s
  • Foundation
  • Skin Selectors
  • Skinning Approach
    • Page Layouts
    • CSS Menus
    • Externalizing Static Resources
  • Tools
  • Hair Loss and Hacks
  • Q&A
What We will Cover
We’ll start by examining how the Advanced Developer Framework manages cascading stylesheets and JavaScript and its impact on user interface development. We will also cover how to set up CSS using skin selectors to form the look and feel of your website or portal. Various skinning approaches to help you quickly and effectively skin your portal and tools available to help you skin your portal in addition to some tips and tricks to get out of tricky spots.
  • Design Meets IT…
  • Cool Messenger Bag
  • Drinks Complicated Coffee Drinks
  • Understands Typography
  • If you think something is “in”, he agrees, but says it “was 5 years ago”
Context for this Discussion – Design with Platforms
As the commercialization of Information Technology has taken place, more demands have been placed on our IT organizations to produce aesthetically pleasing websites. When we design and develop portals we often have to interface with marketing teams that have been using designers to develop the look and feel of the user experience. This can make it difficult to implement, if we do not have the correct approach to having it work within the portal platform.
Hitting Our Stride
When asked to attempt to style our portal we often encounter challenges trying to approach the design and development as we do with other technologies. ADF uses CSS and standard technologies for the UI layer, but to make things as easy to manage as possible we need to understand its foundation.

Apache Trinidad
ADF shares its user interface skinning capabilities with Apache Trinidad’s MyFaces, because of this we need to use something called Apache Trinidad skinning to change the look and feel of the Advanced Developer Framework pages. To do this we use ADF Skin Selectors that we will cover in more depth later.

CSS “Lifecycle” in ADF
CSS generated by ADF follows a certain life cycle. This lifecycle includes operations that happen on the server to deliver content that is specific to the platform requesting the webpage. This allows us to use server-side markup to ultimately deliver a very customized experience for a specific client. It also means that the CSS and JS delivered to the client are delivered on the basis of what we have done with ADF Skinning. The resulting files sent to the client are CSS standards, but in order to generate them we must follow the ADF skinning process. Please note that there are some other approaches that we will cover later, but the ADF Skinning approach does a nice job of isolating the look and feel from the code and version of the portal.

  • Obfuscation & Compression
    • Design goal of reduced file size
  • Turn off in web.xml
CSS Compression
As we start designing with CSS in WebCenter Portal we want to disable the compression that ADF applies. This can be done by turning off the compression feature in the web.XML file to make the resulting CSS generated by ADF for its components much more readable. This gives us the ability to inspect it, to quickly make UI adjustments.

ADF’s “geometry” determines the layout of the page. One thing that is important to be successful with portal design is to establish a good understanding of the layout components of ADF and their resulting user interfaces.
To help us understand this layout there are a few nice online tools. Take a look at the ADF Rich Client Demo online tool to get a sense of what different layout components look like. Additionally a blog post by Martin Day outlines the various best practices for how to use the layout components together.
Geometry and Layout

  • To Flow or not to Flow?
  • Scrolls Bar Headaches
    • Majority of web sites use flow-type layout
  • Since a page template can be changed dynamically
    • Create pages and design custom components that display properly in stretching and flowing context
Flow or Stretch?
To have WebCenter Portal pages that reflect most web site designs, we want to use a flow layout stretch layouts are good for dashboards and applications that are going to be very rich in nature and mimic a desktop experience. Take a look at Designing well known websites with ADF Rich Faces from Maiko Rocha and George Magessy for some examples of variosu layout strategies.

  • Build outer structure with containers that can be stretched and stretch its children
    • PanelStretchLayout, PanelSplitter, …
  • Create flowing islands
    • Use PanelGroupLayout with type=”scroll” or type=”vertical” - this can be stretched, but will not stretch its children
  • Don’t embed stretching components inside flowing islands
  • Don’t stretch something vertically when inside of a flowing container
  • Don’t use height with % unit
Flowing Tips
When we use a flow layout it is important to follow some basic tips – namely, create flowing islands and then make sure that components within them continue to flow.

  • 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 type=”vertical”
Flowing Layouts
Whenever using containers, don’t use stretching containers.
Skin Selectors


Skin Selectors
ADF uses a concept called Skin Selectors to associate styles with particular ADF components. The skin selectors style a particular component and subsections of that particular component. Due to the CSS being evaluated on the server we use a slightly different notation for ADF skin selectors, which are then transformed at runtime.
Enabling the ADF Skin Editing in JDeveloper
JDeveloper has functionality that gives us CSS type ahead capability with the IDE using ADF’s selectors.

  • Style Component or Components
  • Starts with af|
    • contains the name of the component
    • Piece of the component to skin, via a pseudo-element
    • ::label
    • ::content
    • ::read-only
Skinning Keys
Whenever we style components, we start with AF and a pipe symbol that indicates that it’s going to be an ADF Component. After that we’ll go ahead and have a component name and then particular subsection(s) of that component that we wish to apply styling to. JDeveloper helps us to identify these using its type ahead feature for CSS.
  • “.”
    • Do not use leading dot for selectors, leading dot in styleclass properties or use to define style class in CSS files
  • “:”
    • Refers to a CSS element of an ADF Faces or Trinidad component
  • “::”
    • Refers to a part of the component
    • af|inputText::content
Skinning Syntax
When creating CSS on the server for ADF we’re not going to use traditional styling of our CSS identifiers. For instance, the “.” selector will not be used. Instead we’ll be using the selectors described in the previous slides. To select areas within a component, we will be using colons. For complete details of ADF Skinning, please review Frank Nimpu’s ADF Faces Skinning on ADF Insider.

  • JDev code editing support
  • ADF Faces Skin Extensions
    • Syntax Help
    • Image selection
    • Code Completion
    • Code Folding
      • Collapses CSS style definitions
      • Mouse-over code info
Skin Development Support
Within each component there can be a variety of attributes that we can style. Using the JDeveloper CSS editor option, were are able to see each subset of the component as we use the type ahead for our ADF CSS.
  • @platform {/skin definitions go here/}
    • Possible values are: windows, macos, linux, solaris, ppc
    • Does not work for icons
  • @agent {/skin definitions go here/}
    • Possible values are: netscape, ie, mozilla, gecko, webkit , ice
    • Does not work for icons
  • :lang or :locale
  • :rtl pseudo-class to create a style or icon definition when the browser is in a right-to-left language
Functionality Available to “Skinners”
Because ADF CSS is evaluated on the server for the skin selectors, we have options to target specific CSS on the basis of platform and on the basis of locale or language. This practice should be used sparingly, as there are perhaps better ways to manage this within the WebCenter Portal platform or using styling techniques afforded to us by CSS3 Media Queries, etc.

  • StyleClass
    • Can be used in conjunction with skinning
    • Applies styles to the root DOM element
    • Can use EL for context specific CSS
  • InlineStyle
    • Styles the root DOM element
    • Can use EL for context specific CSS
CSS in ADF Faces
Style classes can be applied to a component in ADF using a class, very similar to traditional CSS – although here we would still be using the ADF skin selectors to actually apply the style. You can also use in-line styling on a specific component however this is discouraged, as this is essentially hard coding the style.

  • ContentStyle Works for
    • Input components
    • listboxes
    • Choices
    • richTextEditor
    • Shuttle
    • contentStyle applied to each list in a shuttle
CSS in ADF Faces
Styling with ContentStyle helps us to directly address content within a component. Often times components have a DIV wrapper and we ultimately want to stlye a part of the inside of a component, opposed to a wrapper.
Skinning Approach
Coarse Grained & Fine Grained
When skinning a WebCenter Portal instance we can look at it from coarse-grained and fine-grained standpoint – meaning that many large elements on the page like the background and the center of the page can use very basic styling techniques to impart a look and feel to particular corporate brand with very little effort. At the fine-grained level we can apply the styling to specific ADF components and controls within the page. A lot of value to be gained simply from the coarse-grained approach and then a small amount of tuning with the fine grained goes a long way to complete your overall look and feel that will be inline with your corporate brand.
Hybrid Model
Often times a hybrid model of styling works very well for portals. Taking the coarse-grained elements (page background, main portion of the body, etc) and using traditional CSS approaches with those, but then getting specific using the ADF skinning that we discussed previously, will work together to generate your overall portal appearance.
Navigation via CSS
An example of a hybrid approach would be using technology in WebCenter to generate a menu that uses unordered lists and list items, then applyies traditional CSS to them. Even though you’re benefiting from WebCenter’s navigation models, you’re not doing traditional ADF skinning – but instead using plain old CSS. As an example, take a look at E2.0 Workbench Podcast 2 – WebCenter PS3 Navigation Models and CSS Menus.
  • Expression Language (EL)
    • EL will allow the designer to access the various objects for navigation within their template design
    • Looping in EL should look very familiar for any web developers – nothing complicated required and coding is done inline within the page template!
    • Can mix regular HTML directly into the looping markup
EL & Looping Structures
In the CSS navigation example in the prior slode, we were using expression language that WebCenter provides for us to actually place the various items within our navigation into the markup that the portal renders for the client. We can then apply coarse-grained styling that uses traditional CSS techniques to style our menu. This is an approach that designers and web developers are very familiar with.
CSS Navigation Dropdown Code

  • Custom CSS
  • Images & Video
  • WC Content
    • “Web Folders”
    • Revise without involving development group
    • Revisions, Audit & Workflow
    • Drag and Drop
Externalizing Static Assets
When using coarse-grained techniques in addition to be ADF styling, its often times helpful to hold various styling assets outside of your WebCenter application. In order to do this we can use WebCenter Content to manage all of the unstructured assets for the portal. They can include things like CSS and images that we want manage within our environment and provides revision control and workflow. This is a best practice if you want to allow design teams to access and work with your WebCenter Portal without involving the development team for each and every change
When working with WebCenter Portal or any other technology it’s helpful to have tools to help expedite your work. Using visualization and inspection features in chrome and Firefox you’re able to work very quickly through the CSS needed to style your work. In addition, CSS3 is very powerful for providing visualizations that previously required images to achieve – like drop shadows and gradients. Finally, using something like JQuery were able to actually manipulate the Document Object Model to achieve any change using client-side technology.
Chrome Inspection
Above is an example of inspection within Google Chrome. As we hover over the login link in the upper right-hand corner, we are able to get a very good sense of which styles are being applied to this particular element of the page. This makes it easy to go back and adjust our ADF skinning for a particular component. This is an example of “fine-grained” skinning.
Tools – More!
Apache is a great tool to have handy when you need to very quickly deploy and test some new CSS or another type of artifact without having to check it into a standard repository. XAMPP is a great installer containing Apache and some additional technologies in a “one click” Windows installer.

  • “Reset” Stylesheet to Clean Base Styles
  • TR Inhibit Makes this possible
  • Nice Template within Sample
  • Inspired by WebDesignerWall.com
Bob Fraser CSS Reset Tool
One great feature within the server-side CSS capability with ADF is TR Inhibit. It stops the inheritance of a particular style from being passed down through the DOM for a given selector. Bob Fraser of the WebCenter Portal product management team has created a nice example using the TR inhibit approach, in the form of a reset stylesheet this is being used with some work that he’s done in mobile templating. * link pending to reset example
More Specific Tools
There are a variety of resources to help expedite our work, specifically some CSS3 generators to help us work with gradients, border radius settings, and shadows. CSS3 is a huge plus when attempting to speed development.
To get more detail about the specifics of ADF and how ADF skinning is achieved Frank Nimphius does an excellent job of giving a complete overview of ADF skinning capabilities. In addition, the latest version of JDeveloper now includes a skin editor built directly into the IDE for ADF.

3rd Party Information
As a developer sometimes it’s difficult to understand how and why things are designed certain ways. There are some great third-party websites that provide not only information but also inspiration for designers and developers.
Skin Editor for JDeveloper 11.1.2
Skin editor in the latest JDeveloper version
If you don’t have access to the latest JDeveloper release due to your WebCenter version, there’s an online tool that provides great visibility into how and why there is components are styled a particular way and all of the attributes that can be styled within them.
Hairloss and Hacks

  • DOM is your friend
  • $(‘.selector’).find
  • Magic of CDATA
  • ! Important
  • CSS using generated selectors
Applying Styling Client Side
Sometimes development can get very frustrating when you can’t get exactly what you want and you’ve tried many times to resolve an issue. Using a couple of these tricks, we can often times get around showstoppers. These are not best practices, however they can be used to experiment to find a real resolution. The first being the Document Object Model and using JavaScript by way of JQuery to adjust the DOM using client side notation that allows you to find various elements within the document object model. For instance, $(‘.selector’).find, allows your to searhc the DOM, then manipulate your entire page directly on the client to adjust a styling attribute of that element. Another trick is using something called CDATA. Using CDATA we can actually mark parts of our templates to skip being evaluated by the ADF engine. This allows us to get around any complications for things that the engine might have trouble understanding. Using “! Important” allows our style that has been marked with this enhancement to trump any other styling being applied to a particular element. Finally, we can actually use the auto generated CSS selectors from ADF and style them directly, instead of going the ADF Skin selector route. This will work, but the problem with doing styling against the auto generated selectors is that the style may break between different versions of the platform that you’re running.

ADF Skin Sample
Finally, here’s an example of a small amount of server-side CSS for an ADF skin that can be applied to some common elements to change their look and feel. Stay tuned on the blog, as eventually I will release a more full-featured sample of something similar to Bootstrap from Twitter in the form of an ADF template.
  • andre_almar
    June 20, 2012

    Hi John,
    Very useful tips, thanks for that.
    But I have a question. When we are working together with design teams, it’s better to let the developers build the entire HTML/CSS inside JDeveloper or it’s better to let the designers create the HTML/CSS and after that the developers try to adapt this HTML/CSS styles (create by designers) into Webcenter Portal? What is the best approach recommended?

  • John Brunswick
    June 20, 2012

     @andre_almar Thanks for the kind words Andre.
    There is no right or wrong approach, but my preference would be to adapt a design into a portal template in JDeveloper.  There will be some minimal ADF work to bring the JDeveloper template to parity with the HTML / CSS markup produced by designers and it is generally done by a developer / designer who has at least a little knowledge of ADF and the above considerations.
    Hope that helps!

  • joeswislocki
    September 20, 2012

    Hi John,
    Is it possible to make responsive designs with ADF?

    • John Brunswick
      September 20, 2012

       @joeswislocki Yes – it is possible.  It will take some legwork, as ADF components will add markup to the page that you then need to use media queries, etc to adjust the behavior of.  I have been buried with client work (which is great!), but hoping to get around to taking a stab at an approach to enable easy responsive design for our portal apps.  Will definitely post if / when that happens – a big area of interest lately for everyone.

      • joeswislocki
        September 27, 2012

         @John Brunswick Hi John,
        Do you happen to have or know of a good tutorial that shows how to take a unique web design(psd, html, css…) and implement it into JDeveloper to create a portal? Also, what is the best technique to transition native html into JDeveloper’s native xml format?

        • John Brunswick
          September 28, 2012

           @joeswislocki Hey Joe,
          That spans quite a few disciplines, I do not know of a single tutorial that would illustrate that.  With that being said…  there are some excellent videos / tutorials around moving PSDs to HTML templates.  If you Google around a bit there are some good examples like http://net.tutsplus.com/tutorials/site-builds/from-psd-to-html-building-a-set-of-website-designs-step-by-step/.
          Once you have the HTML, you basically move it into a JDeveloper portal template.  The key will be to use minimal geometry with ADF and let the HTML do the work in the page layout.  The above hopefully can help with some of that.
          Are you going to be at Oracle Open World?  I will be there and we can discuss in more detail.

        • joeswislocki
          September 28, 2012

           @John Brunswick Hi John,  
          I will not be at Oracle Open World, but I will be taking ADF training the following week.
          It is an exciting challenge to learn a new framework. 
          Thanks for the advice.

  • mark_mjdconsulting
    March 1, 2013

    Hi John,
    Hope you don’t mind me using the forum in this way.
    I’m looking for an oracle webcenter designer who has considerable experience with UCM and integrating designs for a new web portal. Ideally it would be someone who has implemented flat designs in webcenter installations and really knows this area and the limitations well. 
    The tricky bit seems to be to find these skills in the South East of the UK – the portal build is being done in Milton Keynes, UK and we would prefer someone on site for a couple of weeks if possible.
    Can you help at all.
    Mark Davies

    • John Brunswick
      March 1, 2013

      @mark_mjdconsulting Hey Mark,
      No worries at all – happy to help where possible.  Have you reached out to Fishbowl per chance?  They have an office in the UK and an awesome design guy who does WC Portal + WC Content very well and is an Oracle Ace – https://apex.oracle.com/pls/apex/f?p=19297:4:1155751261007::NO:4:P4_ID:5140.
      Hope that helps.

      • mark_mjdconsulting
        March 1, 2013

        @John Brunswick John, many thanks for your reply. Touching base with jim shortly.
        Thanks, Mark

    • John Brunswick
      March 1, 2013

      @mark_mjdconsulting The link to the Ace profile via LiveFyre will need to be cut and paste to work…  The following is their blog that may also help – http://cfour.fishbowlsolutions.com.  John Sim is the guy you will be looking for 🙂

  • mrffcardoso
    September 3, 2013

    John Brunswick andre_almar
    Hi Andre, I agreed with John, but in my case we decided It would be a designer’s job. It also depends very much on designer skills and past experiences. 
    This was my recent work.

    Fabio Cardoso

  • AdamCarlson1
    July 26, 2016

    Hey John, I read and bookmarked this page a while ago. Any way you can update it to fix the images and styling?

Leave a comment