print pageHow do I integrate my existing site templates into ShadoCMS?
This is a question often asked by developers new to Shado and when someone is first trialling ShadoCMS so we feel it is worthy of a blog entry.
Setting up
All templates live in the [site name]/app_templates folder and must be named starting with "tmp_", e.g tmp_standard.cfm . The best tool for editing templates is eclipse using the cfeclipse plugin.
Templates can live directly in the app_templates folder or you can create a sub folder of the app_templates folder to organize your templates. Templates are ColdFusion files and can contain HTML, ColdFusion code or a mixture of both. The other thing you should know is that when ShadoCMS renders a page they use the app_templates/index.cfm file which acts as a central controller for all pages.
app_templates/Index.cfm - explained
The app_templates/index.cfm file acts as a central controller for your site. All pages run through this file and templates are called from here. Whenever a page is requested the ShadoCMS SAPI.SITE object is setup in the request scope. The initRequest() function of the SAPI initalises data for the current page. It puts all inherited section and page variables into request scope including the retro getPageObject query (request.getPageObject). Calling the #request.sapi.site.getTemplate()# method will render your template.
<cf_lesswhitespace>
<cfscript>
/* multilanguage stuff */
// code to change a users language before the request begins
if(structKeyExists(url,"switchUserLanguageTo")){
request.userContext.setLanguage(url.switchUserLanguageTo,request.siteContext);
}
// stuff we will be using on our templates.
request.oStringTranslator = createObject("component","#request.siteContext.dsn#.app_templates.objects.stringtranslator.stringtranslator");
</cfscript>
<!---
Run the standard global include that sets up required variables from
Shado and any custom stuff for this site.
--->
<cfinclude template="/#request.siteContext.dsn#/app_globals.cfm">
<!---
Call the SAPI site object and initialise the current request.
The initRequest() function initalises data for the current page. It puts
all inherited section and page variables into request scope including the
retro getPageObject query (request.getPageObject).
The getPageObject query is also returned from the function and in this case
we assign it to the local variable (variables.getPageObject).
--->
<cfset variables.getPageObject = request.sapi.site.initRequest(allowCacheInPreviewMode=false)>
<!---
Include the template for the page that has been initalised for this request.
--->
<cfif structKeyExists(request.sapi.site.getpage(),"page_title")>
<cfinclude template="#request.sapi.site.getTemplate()#">
<cfelse>
<!--- presume if page_title doesn't exist that they are trying to view a page that does not exist in another language' --->
<h1>No translation exists for this page in the selected language</h1><cfabort>
</cfif>
<!---
Run any final processing tasks that Shado needs to do (primarily stats gathering)
--->
<cfinclude template="/shadomx/util/circuits/inc_shado_final_processing.cfm">
</cf_lesswhitespace>
<!--- Include the admin bar (shado edit toolbar) --->
<cfinclude template="/#request.siteContext.dsn#/app_templates/coreincludes/inc_adminbar.cfm">
Anatomy of a Template
So the index.cfm file is used to call your template now you can look at what makes up a template.
The code below is indicative of the type of logic often seen at the top of a template. The first line sets up our site objects and then we use this to add a template specific style sheet if one exists. We also setup our pagelet object and a navigation object.
Data about the page (and the section it lives in) are available in the request.sapi.site.getPage() function. Do a dump on this function to see what is available.
<!--- Set up the site object --->
<cfset oSite = request.sapi.site>
<!--- Add a css (if it exists) with the same name as the template, gives us template specific styles --->
<cfset oSite.addTemplateStyleSheet(currentTemplatePath=getcurrentTemplatepath())>
<!--- Create a site specific pagelet object, allows us to control individual parts of the page --->
<cfset oPagelet = createobject("component","#request.sitecontext.dsn#.app_templates.coreobjects.pagelet")>
<!--- get our custom navigation generator component --->
<cfset oNav = createObject("component","#request.siteContext.dsn#.app_templates.coreobjects.nav") >
<cfset navArgs = oNav.init()>
<cfset qNavQuery = oNav.getTopNav(argumentCollection=navArgs)>
Now onto the main body of the template.
To get a reference to the name of the site (and therefore the sitefolder ) you use the #request.sitecontext.dsn# variable. You can do a cfdump on request.sitecontext to see what other variables exist in the request.sitecontext scope <cfdump var="#request.sitecontext.dsn#">. Data about the page and the section it lives in is available in the oSite.getPage() function.
<cfoutput>
<!--- this include will output the HTML head tag including the <body> tag --->
<cfset oPagelet.renderPagelet(pathToPagelet="#request.siteContext.dsn#.app_templates.corepagelets.htmlheadtag", pageletname="htmlheadtag")>
<div id="container">
<div id="header">
<cfinclude template="/#request.sitecontext.dsn#/app_templates/corepagelets/header.cfm">
<ul id="nav">
<cfloop query="qNavQuery">
<li><a href="/#request.siteContext.dsn##ssurl#">#title#</a></li>
</cfloop>
</ul>
<form method="post" action="/#request.sitecontext.dsn#/search.cfm" id="searchForm">
<input name="SEARCHVALUE" id="search" type="text"> <input src="/#request.sitecontext.dsn#/app_templates/coretemplates/images/search_button.gif" name="send" value="search" alt="search" title="search site" id="searchButton" type="image">
</form>
</div>
<img src="/#request.sitecontext.dsn#/app_templates/coretemplates/images/#request.templateimage#" alt="Straker" id="banner">
<div id="primaryContent">
<cfset oPagelet.renderPagelet(pathToPagelet="#request.siteContext.dsn#.app_templates.corepagelets.content.crumbs", pageletname="crumbs",cache=false)>
<h1>#oSite.getPage().page_title#</h1>
<cfset request.sapi.site.addcontainer2page(3, "Top Content ", request.container2edit)>
<cfset request.sapi.site.addcontainer2page(1, "Main Content", request.container2edit)>
<cfset request.sapi.site.addcontainer2page(5, "Bottom Content ", request.container2edit)>
<cfset oPagelet.renderPagelet(pathToPagelet="#request.siteContext.dsn#.app_templates.corepagelets.content.news", pageletname="news")>
</div>
<div id="sidebar">
<cfif request.getpageobject.page_uuid neq "720EA0A8-9807-75AA-96FA-3BABDFD460E7">
<cfset navArgs.RootSectionUUID = request.sapi.site.getPage().circuit_uuid>
<cfset qSubNav = oNav.getNav(argumentCollection=navArgs)>
<cfloop query="qSubNav">
<div><a href="/#request.siteContext.dsn##ssurl#" class="mainlevel">#title#</a></div>
</cfloop>
</cfif>
<cfset request.sapi.site.addcontainer2page(2, "Other Content", request.container2edit)>
</div>
<div id="footer">
<ul id="footNav">
<cfloop query="qNavQuery">
<li><a href="/#request.siteContext.dsn##ssurl#">#title#</a> | </li>
</cfloop>
</ul>
<a href="http://www.straker.co.nz/">© straker 2007</a>
</div>
</div>
</body>
</html>
</cfoutput>
Comments
There are no comments for this page as yet.
Full RSS
