Note for APEX 5.1 UI, Theme, Templates and Substitution Strings


From application shared components, User Interface section, we can get the hierarchy diagram as below. 

Source SVG
There are three levels, User Interface, Theme, and Template.
  • UI attributes specify user interface options, including application level logo, favicon, user interface detection (especially application level CSS files for screen auto-detection ) and current theme
  • Theme as a collection of templates, include theme level JavaScript, CSS, icons, image, skin style, and other static files serving current theme, component default template assignment, region default template assignment, and global template options (references between CSS classes and global style options, i.e. Button type option: tiny, Small or large)
  • Template: 
    • Major template types include page, region, report, button, breadcrumb, list and label (with yellow background color)
    • Theme42 also includes templates for Legacy Calendar and Popup LOV as default but I don't draw in the diagram
    • Note: 
      • Navigations, including Navigation bar at top-right area and Navigation menu at left side, utilize list template (with buff background color)
      • Default header and footer templates are unassigned (with grayish background color). I checked historical docs. These two settings are from APEX 4.2 but without detailed usage. I don't know where they are in a page or how to create these regions from page designer. If anybody knows, please guide me.  update 20170506: from my next post, I find clue about these toolbar regions. I suppose they are in internal app 8851 Mobile Master Theme. 
Jorge Rimblas analogize template to Russian dolls in book Expert Oracle Application Express. That makes sense. The essence and core of template technology is substitution. If we say substitution strings are the holes pre-dug in a complete HTML page, we can say, from UI's point of view, what we do in application builder is filling up these nested holes pre-designed in templates. APEX engine will render the content we fill in application builder to web UI elements (HTML, JavaScript and CSS), and then fill them in the corresponding position where the associated substitution string is. 

The diagram below divided to three columns illustrates the mapping of metadata defined in UI, theme and template to substitution strings in page template, the position of the page designer layout in page template, and the correspondence between page template and rendered WEB page.  Note: Standard page template is as the example below.
Source SVG
The first column, "UI, Theme and Template Components", has been illuminated at the beginning of this note. 

For the second column, "Page Template, Layout and Substitution Strings", they are:

  • Header, Body and Footer are three major sections from definition of standard page template
  • Page Header, Page Navigation, Breadcrumb Bar, Content Body, Footer and Inline Dialogs are from layout in Page Designer, and corresponding substitution string are under the layout section name (with white background color)
  • Other substitution strings are listed as the order in page template
  • Note: not all substitution strings are listed here, just these important ones I think. 
The third column, "WEB Page" is the rendered HTML page associated with three sections from page template in the second column.

Following the arrow direction, we can find the connections among three columns. First for blue arrows:

  • #APEX_CSS#: is used by Application Express for default CSS files, such as jquery-ui, font-apex
  • #THEME_CSS#: CSS files in theme definition will go to #THEME_CSS#
  • #TEMPLATE_CSS#: CSS files defined in page template including inline CSS, as well as CSS files from other component templates (such as region, report and list templates) will go to #TEMPLATE_CSS#
  • #THEME_STYLE_CSS#: theme style CSS files will go to #THEME_STYLE_CSS#. Default style Vita will invoke vita related CSS files
  • #APPLICATION_CSS#: CSS files defined in User Interface attributes will go to #APPLICATION_CSS# 
  • #PAGE_CSS#: CSS files defined in page properties from page designer including inline CSS will go to #PAGE_CSS#
  • #FAVICON#: Favicon defined in UI attributes will go to substitution string #FAVICON#
  • #HEAD#: will be replaced by HTML Header in page properties from page designer
  • Note: 
    • The CSS files defined by plugins will go to #APEX_CSS#, such as D3, FlotPie
    • There are no syntax verification and URL validation for what we define for substitution strings
    • If input html tags like "<div></div>" into HTML Header in page properties, this will cause unexpected HTML output and move #HEAD# substitution content out of "<head></head>" tag. So make sure what we define is correct and matches HTML context.
Above content defined in application level, theme level and page level (including component level) will replace the substitution strings in head HTML tag, then finally will be translated to HTML tags, like we can use link, meta tags to fill up head tag area. 
Note: we might find there are some script tags in head, marked as blue color in the third column, but in the template there is no substitution string for script. If we happen to use Oracle JET lib, we would be able to see these JavaScript libs for it. Actually, I don't know why these scripts can go to this area without corresponding substitution string in the template. I suppose it's an internal logic for Oracle JET chart region rendering and using #HEAD# substitution string according to the generated position and unremovableness for #HEAD# in page template. 
Then for black arrows:
  • #REGION_POSITION_07#:  the page components that are set to Page Header layout position in page properties will go to #REGION_POSITION_07# as the content of Page Header
  • #NAVIGATION_BAR#: the list defined for Navigation Bar and other page components set to Page Navigation layout position in page properties will go to this area, such as Sign Out, and Help links
  • #SIDE_GLOBAL_NAVIGATION_LIST#: the list defined for Navigation menu will go to this area, but this section will not be displayed in page layout
  • #REGION_POSITION_01#: the page components that are set to Breadcrumb Bar layout position in page properties, including the default PageNavigator Breadcrumb defined in shared components will go to #REGION_POSITION_01#
  • #BODY#: the page components that are set to Content Body layout position in page properties will go to #BODY#
  • #REGION_POSITION_05#: the page components that are set to Footer layout position in page properties will go to #REGION_POSITION_05#
  • #REGION_POSITION_04#: the page components that are set to Inline Dialogs position in page properties will go to #REGION_POSITION_04#
  • Note:
    • These sections displayed in layout of page designer all support drag and drop
    • Navigation menu is a major section but not displayed in layout as default, listing here just for reminding
    • The default template defined for Inline dialogs is in the settings of UI attributes. But I don't draw out in the first column
    • The page components in the first column can be set to any section in page layout, take an example, we can add one region and one button in Page Header or Footer if we need. But here I just put the arrow to Body section in the second column
These content defined in page level will replace the substitution strings in body HTML tag, then finally will be translated to HTML or  scripts in <body></body> tags.
Note: we might find there are some scrip tags in html body, marked as blue color in middle section of the third column. There scripts are generated by certain type regions or plugins. As far as I knew, if there is a tree region in the page, there will be some scripts following the region.
Last for brown arrows:
  • #DEVELOPER_TOOLBAR#: development mode toolbar
  • #APEX_JAVASCRIPT#: is used by Application Express for default JavaScript files, such as jquery js files
  • #GENERATED_CSS#: from APEX forum: is used as placeholder for CSS code emitted by plug-ins, and more significantly, JavaScript function definition code generated by Dynamic Actions will go to this place
  • #THEME_JAVASCRIPT#: JavaScript files defined on theme level, such as hammer,theme42,modernizr, will go to this placeholder
  • #TEMPLATE_JAVASCRIPT#: JavaScript file URLs and "Function and Global Variable Declaration" code defined in the template, actually only in page template, will go to this placeholder
  • #APPLICATION_JAVASCRIPT#: JavaScript files defined on user interface level will be here
  • #PAGE_JAVASCRIPT#: JavaScript file URLs and "Function and Global Variable Declaration" code defined in on page level, actually only in page property in page designer, will be here
  • #GENERATED_JAVASCRIPT#: JavaScript code created by components on the fly will go to this placeholder, the general order would be:
    • JavaScript file URLs defined in page component templates, such as region template, report template, plug-in template, ordered as layout sequence defined in properties
    • After file URLs, "apex.jQuery( document ).ready" will start to invoke functions generate in the page document. The general order is as below:
      • JavaScript code defined in "execute when page loads" in region template or JavaScript code emitted by PL/SQL Code from plug-in definition, ordered as layout sequence defined in page properties
      • JavaScript code generated by Dynamic Actions in #GENERATED_CSS#
      • JavaScript code defined in "execute when page loads" in page template
      • JavaScript code defined in "execute when page loads" JavaScript option in page property
      • JavaScript event for Page items
These content will replace the substitution strings in Footer page template section, and then finally will be translated to footer area between closing </form> tag and closing </body> tag as default.

If we review this diagram from the reverse direction, from the third column to the first one, we might get a picture how the template is designed in APEX.


APEX has already abstracted HTML tag peers to high-level components, i.e. region, item, button, breadcrumb,  and provided variation through component types, templates, template options and customizable CSS classes, that offers a clear advantage of focusing on business logic implementation to developers. And the comprehensive design for UI, Theme, components templates, substitution string with customizable architecture enable flexibility and elasticity for look and feel of applications.


I draw these diagrams to help myself understand more deeply and clearly with APEX UI, theme, template and rendering order, and make notes as a reference. 

Tools and Env:
Template and Theme: Standard Page Template and Universal theme 42 as default setting
Testing Application: packaged application bug tracking
Environment: Application Express 5.1.0.00.45 built by OXAR
Diagram Tool: Drow.io desktop application for Chrome
Thanks to:
OXAR saving my life for building environment

Comments

Popular posts from this blog

RDS Customizable for APEX 5.1

Use Plugin Code Editor - Part 1/4: Demo