Registreren

Surrounding page

Almost every page of an application uses a surrounding page. A surrounding page contains elements that are constant for all pages of your application. Usually this includes a header with a menu, a footer and margins left and right. In the center of the surrounding page the application content is shown. You can use the standard surrounding page or create your own surrounding page.

Creating a surrounding page

You can create your own surrounding page, using the velocity scripting language. Like every script, some variables are predefined. The most important one is $document. Here is an example of a script for a surrounding page. This script contains everything you need to render pages correctly:

<!DOCTYPE html>
<html class="cx_standard" lang="$document.getLanguage()">
    <head>
        $document.getMetaTags()
        #set($documentTitle = $document.getTitle())
        #if($documentTitle)
            <title>$documentTitle</title>
        #end
        $!document.getFavicons()
        $document.getDefaultCSS()
        $!document.getCSS()
        $document.getDefaultScripts()
         $!document.getScripts()
    </head>
    #set($bodyAttributes = $engine.newHTMLAttributeMap())
    #set($bodyAttributes['class'] = $document.getCSSClass()) ## can be null
    #set($bodyAttributes['data-modified'] = $document.isModified())
    <body $bodyAttributes>
        #set($pageWrapperClass = "cx_page-wrapper")
        #set($menu = $document.getXMenu())
        #if($menu)
            #set($pageWrapperClass = "$pageWrapperClass cx_fixed-top-menu-wrapper")
        #end
        <div class="$pageWrapperClass" cx-module='pagewrapper'>    
            $!menu.toHTML()
            $!document.getContent()
        </div>
    </body>
</html>


See bottom of page for surrounding page used in user interfaces before UI 4.0

This is of course a very simple surrounding page, it doesn't really add much in terms of design, it's
purpose is just to show you the concept. Let's go through the methods used here (in yellow).

  • $document.getMetaTags() adds some meta tags, this is not strictly necessary but it is good practice. Also, this way you can have the content add some meta tags to be used in the header part of your html.
  • $document.getFavicons() adds favicon tags - in case you have the following files:
    • /favicons/favicon.png      (200 * 200)
    • /favicons/favicon32.png  (32 * 32)
    • /favicons/favicon16.png  (16 * 16)
  • $document.getDefaultCSS() includes all the default stylesheets needed to make the engine pages look like they do.
  • $document.getCSS() includes the CSS files added by the 'extra CSS' field in the blueprint (User interface tab) and $document.addCSS() method.
  • $document.getDefaultScripts() adds all the default javascript files to make the engine pages behave correctly. For example, the mini calendar widget to enter dates uses some javascript. Remember, that if you don't include this line, your pages may not work!
  • $document.getScripts() includes javascript files added with the $document.addScripts() method.
  • $document.getXMenu().toHTML() renders a dropdown menu, the html is created automatically for you. You can also use this menu structure to create your own html should you desire to do so.
  • Finally $document.getContent() gets the actual page content that is embedded within the surrounding page.

Notice the use of the exclamation mark in for example $!document.getContent(). This is added in case there is no content at all. Velocity will render this as an empty line. If you don't add the exclamation mark and there is no content, velocity will literally print out the code.

Testing a surrounding page

You can test a surrounding page. Go backstage, under Menu - Session - Set surrounding page. Set the name of the surrounding page.

 

Set the surrounding page in your application

If you want to set the surrounding page for all users, go to 'Blueprint properties' - Tab 'User interface' tab and set the surrounding page. 

How is the surrounding page evaluated?

A surrounding page is never called directly, instead the request will instruct the engine to render some content which is then wrapped inside the surrounding page. Imagine a request (url) that shows some search results. First, the engine renders the content (fig. 1) then the content is embedded in the surrounding page (fig. 2) at the point where $document.getContent() was encountered.

Figure 1
 		 Figure 2


Tips: writing html/css for a surrounding page, avoiding conflicts

  • Build your surrounding page based on bootstrap components to be sure it integrates with the components generated by the engine.
  • Your own stylesheet may conflict with the default crossmarx stylesheets.
  • jQuery is loaded if you get the default scripts. Do not add an extra version of jQuery! This will break things.

 

 

 

 

Surrounding page old version

In older user interface versions (before UI 4.0) the following script was used:

<!DOCTYPE html>
<html class="cx_minimal">
    <head>
        $document.getMetaTags()
        <title>$!document.getTitle()</title>
        $document.getDefaultCSS()
        $!document.getCSS()
        $document.getDefaultScripts()
        $!document.getScripts() 
    </head>
    <body class="$!service.getCSSClass()">

        #set($menu = $document.getXMenu()) 
        <div class="cx_page_wrapper #if($menu)cx_fixed-top-menu-wrapper#end"> 

            #if($menu)
                $menu.toHTML()
            #end
            #set($contentClass = $document.getCSSClassForContent())
            <div class="$contentClass">
                <div class="row">
                    <div class="col-md-12">
                        $!document.getContent()
                    </div>
                </div>
            </div> 
        </div>
    </body>
</html>