Support for Partials, Layout Pages and Sections

The MergeText and RenderAspScript methods support the ability to render Partial pages. There's also the concept of Layout pages which allow you to create the base page layout in a single page that can be reused for many or all content pages. Layout pages then contain a Content region into which the content page is rendered as well as optional sections that can be used to render additional content from the content page into the Layout page.

Scripts and Templates: Same Syntax

Scripts and Templates use the same basic syntax to describe Layout, Sections and Partials using specific tags that can be embedded into a script or template. Note that the markup syntax is finicky and you need to ensure you use the right amount of spacing and the right quote characters in order for these tags to work. This has been done to optimize performance in finding these tags at runtime. Please make sure you follow the layouts described below exactly.

For the following examples I'll use a script page (.wcs), but the syntax related to these concept is identical in both scripts and templates.

Layout Page

Layout pages are top level pages that typically hold a common page frame - things like the page head (html,head,body tags) as well as the HTML for the banner, top level menu, as well as a footer. Most pages in a site use a common layout and a Layout page can provide most of that common layout on a single page. An embedded tag is then used to embed the actual Content page into the layout.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>    
    <%= IIF(vartype(pcTitle) = "C",pcTitle,"") %>    
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
    <link href="bower_components/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet" />
    <%= RenderSection("headers") %>
</head>
<body>    
   <%= RenderPartial("~/Views/Common/LoginTag.wcs") %>
   
    <h1>HEADER FROM LAYOUT PAGE</h1>         

    Content goes here:
    <%= RenderContent() %>    

    <hr />   
    LAYOUT FOOTER 
             
    <%= RenderSection("scripts") %>           
</body>  
</html>

This page contains two sections, one partial and a content section:

<%= RenderContent() %>

RenderContent is the most important tag that is responsible for embedding the content HTML into the layout page. The content rendered is the initial page you requested as part of the render operation.

<%= RenderSection("headers") %>

RenderSection describes a 'hole' in the Layout page into which the Content page can render content by creating a Section tag in the content page. We'll get to that below. For now just know that anywhere you think you might have content that the content page needs to fill create a section for it.

Note that section content expresions are always evaluated, not executed, even if running inside of scripts.

<%= RenderPartial("~/Views/Common/LoginTag.wcs") %>

RenderPartial embeds the content of another page into the current page, or in this case the current layout page. The function is passed a Web relative path with ~/ to identify the Web root. RenderPartial loads the page and executes it as a separate operation. In scripts the page is actually re-running a separate PRG file. For templates the Partial content is simply embedded into the host page and evaluated inline with the rest of the page.

Content Page

Content pages are the pages you actually load. So this would be customer.wcs, invoice.wcs etc. Content pages can then optionally link Layout pages and can call out to Partial pages, which works the same as described above. Finally Content pages can also have Sections that are back filled into a Layout page.

When used in combination with a layout page, a content page typically is not a fully self-contained HTML document but just an HTML fragment. The layout page contains the HTML header and overall document structure, while the content page only fills in the main content area typically.

Here's a content page:

<% Layout="~/LayoutPage.wcs" %> 

<% section="headers" %>
     <title>My 3nd Awesome Web Page - <%= Time() %> </title>
     <link href="css/MyPage.css" rel="stylesheet" />
<% endsection %>  
 
<div>           
<h3>This is my CONTENT PAGE</h3>
<p>   
  Time is: <%= DateTime() %> Yup it is!   
</p> 
  
<h3>Partial Content below (10x)</h3>  
<hr />  
<% for x = 1 to 5 %>     
    <%= RenderPartial("~/PartialPage.wcs") %>  
<% endfor %>
<hr />
    
           
</div>               

<% section="bottomcontent" %>
    Bottom Content:<br />
    <%= Version() %>
<% endsection %>

<% section="scripts" %>    
    <script src="bower_components/jquery/jquery.js"></script>
<% endsection %>

This page contains a Layout section, a Partial reference and a couple of Sections.

<% Layout="~/LayoutPage.wcs" %>

The layout tag is basically specifies the name of the Layout to a page. Note that this tag is an assignment tag and doesn't use an = sign. You specify the web root relative path to the page that serves as the Layout master.

<%= RenderPartial("~/PartialPage.wcs") %>

As in the Layout page - you can call and pull in a Partial page to render into the content page. Use partials to break complexity in pages into more manageable pieces. Note that in scripts you can easily run partials in a loop as shown in the example. This is not possible for templates which don't have a good way to do looping structures.

<% section="scripts" %>    
    <script src="bower_components/jquery/jquery.js"></script>
<% endsection %>

Allow you to push content from the content page back into the Layout page using names of sections that are defined in the Layout page. The above says that you are to take the evaluated content from the script section above, and take the result of that evaluated content and embed it into the layout page, where it defines the .

Sections are always Evaluated not Executed!

Note that sections are always evaluated not executed like a script, even if they are referenced inside of a script page. This means you can use <%= expression %> but not <% code %> This includes if you reference <%= RenderPartial() %> inside of a section which is then also evaluated as a template, rather than executed as script.

Partials

Partial pages are nested, child pages that are rendered from a content or layout page. Partials allow you to break down complex HTML layout into more easily manageable sections. For scripts this is also useful as you can reduce the size of the generated PRG files.

Partials can be called from either Layout or Content pages and behave exactly like content pages. You can also reference any variables that were passed into the Content page (Partials execute as child pages to the content page so models and data are in scope, but local vars from the content page are not).

Partials are referenced from either a content or layout page:

<div>
    <%= RenderPartial("~/WriteMessage_Modals.wwt") %>
</div>

You then implement the page - WriteMessage_Modals.wwt to hold the content you want embedded. There's nothing special about a Partial page, it behaves like any other script or content page and you can use code blocks and expressions as you can on the host page.


© West Wind Technologies, 1996-2018 • Updated: 12/27/18
Comment or report problem with topic