/wheels/controller/layouts.cfm

  1<cffunction name="usesLayout" access="public" returntype="void" output="false" hint="Used within a controller's `init()` method to specify controller- or action-specific layouts."
  2	examples=
  3	'
  4		<!---
  5			Example 1: We want this layout to be used as the default throughout the entire
  6			controller, except for the myajax action
  7		 --->
  8		<cffunction name="init">
  9			<cfset usesLayout(template="myLayout", except="myajax")>
 10		</cffunction>
 11		
 12		<!---
 13			Example 2: Use a custom layout for these actions but use the default layout.cfm
 14			for the rest
 15		--->
 16		<cffunction name="init">
 17			<cfset usesLayout(template="myLayout", only="termsOfService,shippingPolicy")>
 18		</cffunction>
 19		
 20		<!--- Example 3: Define a custom method to decide which layout to display --->
 21		<cffunction name="init">
 22			<cfset usesLayout("setLayout")>
 23		</cffunction>
 24		
 25		<cffunction name="setLayout">
 26			<!--- Use holiday theme for the month of December --->
 27			<cfif Month(Now()) eq 12>
 28				<cfreturn "holiday">
 29			<!--- Otherwise, use default layout by returning `true` --->
 30			<cfelse>
 31				<cfreturn true>
 32			</cfif>
 33		</cffunction>
 34	'
 35	categories="controller-initialization,rendering" chapters="rendering-layout" functions="renderPage">
 36	<cfargument name="template" required="true" type="string" hint="Name of the layout template or method name you want to use">
 37	<cfargument name="ajax" required="false" type="string" default="" hint="Name of the layout template you want to use for AJAX requests">
 38	<cfargument name="except" type="string" required="false" hint="List of actions that SHOULD NOT get the layout">
 39	<cfargument name="only" type="string" required="false" hint="List of action that SHOULD ONLY get the layout">
 40	<cfargument name="useDefault" type="boolean" required="false" default="true" hint="When specifying conditions or a method, pass `true` to use the default `layout.cfm` if none of the conditions are met">
 41	<cfscript>
 42		// when the layout is a method, the method itself should handle all the logic
 43		if ((StructKeyExists(this, arguments.template) && IsCustomFunction(this[arguments.template])) || IsCustomFunction(arguments.template))
 44		{
 45			StructDelete(arguments, "except", false);
 46			StructDelete(arguments, "only", false);
 47		}
 48		if (StructKeyExists(arguments, "except"))
 49			arguments.except = $listClean(arguments.except);
 50		if (StructKeyExists(arguments, "only"))
 51			arguments.only = $listClean(arguments.only);
 52		variables.$class.layout = arguments;
 53	</cfscript>
 54</cffunction>
 55
 56<cffunction name="$useLayout" access="public" returntype="any" output="false">
 57	<cfargument name="$action" type="string" required="true">
 58	<cfscript>
 59		var loc = {};
 60		loc.returnValue = true;
 61		loc.layoutType = "template";
 62		if (isAjax() && StructKeyExists(variables.$class.layout, "ajax") && Len(variables.$class.layout.ajax))
 63			loc.layoutType = "ajax";
 64		if (!StructIsEmpty(variables.$class.layout))
 65		{
 66			loc.returnValue = variables.$class.layout.useDefault;
 67			if ((StructKeyExists(this, variables.$class.layout[loc.layoutType]) && IsCustomFunction(this[variables.$class.layout[loc.layoutType]])) || IsCustomFunction(variables.$class.layout[loc.layoutType]))
 68			{
 69				// if the developer doesn't return anything from the method or if they return a blank string it should use the default layout still
 70				loc.invokeArgs = {};
 71				loc.invokeArgs.action = arguments.$action;
 72				loc.temp = $invoke(method=variables.$class.layout[loc.layoutType], invokeArgs=loc.invokeArgs);
 73				if (StructKeyExists(loc, "temp"))
 74					loc.returnValue = loc.temp;
 75			}
 76			else if ((!StructKeyExists(variables.$class.layout, "except") || !ListFindNoCase(variables.$class.layout.except, arguments.$action)) && (!StructKeyExists(variables.$class.layout, "only") || ListFindNoCase(variables.$class.layout.only, arguments.$action)))
 77			{
 78				loc.returnValue = variables.$class.layout[loc.layoutType];
 79			}
 80		}
 81		return loc.returnValue;
 82	</cfscript>
 83</cffunction>
 84
 85<cffunction name="$renderLayout" returntype="string" access="public" output="false">
 86	<cfargument name="$content" type="string" required="true">
 87	<cfargument name="$layout" type="any" required="true">
 88	<cfscript>
 89		var loc = {};
 90		if ((IsBoolean(arguments.$layout) && arguments.$layout) || (!IsBoolean(arguments.$layout) && Len(arguments.$layout)))
 91		{
 92			// store the content in a variable in the request scope so it can be accessed
 93			// by the includeContent function that the developer uses in layout files
 94			// this is done so we avoid passing data to/from it since it would complicate things for the developer
 95			contentFor(body=arguments.$content, overwrite=true);
 96			loc.include = application.wheels.viewPath;
 97			if (IsBoolean(arguments.$layout))
 98			{
 99				loc.layoutFileExists = false;
100				if (!ListFindNoCase(application.wheels.existingLayoutFiles, variables.params.controller) && !ListFindNoCase(application.wheels.nonExistingLayoutFiles, variables.params.controller))
101				{
102					if (FileExists(ExpandPath("#application.wheels.viewPath#/#LCase(variables.params.controller)#/layout.cfm")))
103						loc.layoutFileExists = true;
104					if (application.wheels.cacheFileChecking)
105					{
106						if (loc.layoutFileExists)
107							application.wheels.existingLayoutFiles = ListAppend(application.wheels.existingLayoutFiles, variables.params.controller);
108						else
109							application.wheels.nonExistingLayoutFiles = ListAppend(application.wheels.nonExistingLayoutFiles, variables.params.controller);
110					}
111				}
112				if (ListFindNoCase(application.wheels.existingLayoutFiles, variables.params.controller) || loc.layoutFileExists)
113				{
114					loc.include = loc.include & "/" & variables.params.controller & "/" & "layout.cfm";
115				}
116				else
117				{
118					loc.include = loc.include & "/" & "layout.cfm";
119				}
120				loc.returnValue = $includeAndReturnOutput($template=loc.include);
121			}
122			else
123			{
124				arguments.$name = arguments.$layout;
125				arguments.$template = $generateIncludeTemplatePath(argumentCollection=arguments);
126				loc.returnValue = $includeFile(argumentCollection=arguments);
127			}
128		}
129		else
130		{
131			loc.returnValue = arguments.$content;
132		}
133		return loc.returnValue;
134	</cfscript>
135</cffunction>