Cchost/concepts/Templates - Revision history

Fourstones: /* Overriding system default files */

2009-03-24T23:49:04Z

‎Overriding system default files

Fourstones: /* Overriding system default files */

2009-03-24T23:45:04Z

‎Overriding system default files

Fourstones: /* Resolving partial paths */

2009-03-24T23:43:17Z

‎Resolving partial paths

Fourstones: /* Overview */

2009-03-24T20:13:26Z

‎Overview

Fourstones: /* Embedded Macros vs. Paths */

2008-11-15T01:32:41Z

‎Embedded Macros vs. Paths

Fourstones: /* Resolving partial paths */

2008-11-14T22:42:50Z

‎Resolving partial paths

Fourstones: /* Macro table */

2008-11-14T15:24:08Z

‎Macro table

Fourstones: /* Variables Gotchas */

2008-11-14T15:21:23Z

‎Variables Gotchas

Fourstones: /* Resolving partial paths */

2008-11-12T11:19:30Z

‎Resolving partial paths

Fourstones: /* Resolving partial paths */

2008-11-12T11:18:43Z

‎Resolving partial paths

@@ Line 234: / Line 234: @@
 As of 5.1 (currently in SVN) there is a new option in admin/paths called '''Prioritize Custom Skins''' which affects the precedence rules outlined above. If checked, it moves #5 to just below #1.
-That means, with that option set, when a template in ccskins/shared refers to a javascript, image, style sheet or embedded template, the system will look at the admin 'Skin Path' option ''before'' looking anywhere else (except the off the root of the installation).
+That means, with that option set, when a template in ccskins/shared refers to a javascript, image, style sheet or embedded template, the system will look at the admin 'Skin Path' option ''before'' looking anywhere else (except off the root of the installation).
 ==Embedded Macros vs. Paths==

@@ Line 232: / Line 232: @@
 '''6. System default locations''' ('''ccskins/shared/pages''', '''ccskins''', '''ccskins/shared''', '''ccskins/shared/formats''')
 ===Overriding system default files===
-As of 5.1 (currently in SVN) there is a new option in admin/paths called '''Prioritize Custom Skins''' which affects the precedence rules outlined above. If checked, that system move #5 just below #1.
+As of 5.1 (currently in SVN) there is a new option in admin/paths called '''Prioritize Custom Skins''' which affects the precedence rules outlined above. If checked, it moves #5 to just below #1.
-That means, with that option set, when a template in ccskins/shared refers to a javascript, image, style sheet or embedded template, the system will look at the admin 'Skin Path' option ''before'' looking anywhere else.
+That means, with that option set, when a template in ccskins/shared refers to a javascript, image, style sheet or embedded template, the system will look at the admin 'Skin Path' option ''before'' looking anywhere else (except the off the root of the installation).
 ==Embedded Macros vs. Paths==

@@ Line 231: / Line 231: @@
 '''6. System default locations''' ('''ccskins/shared/pages''', '''ccskins''', '''ccskins/shared''', '''ccskins/shared/formats''')
 ==Embedded Macros vs. Paths==
 A 'macro function' is function inside a PHP template with a specific naming pattern and signature:

@@ Line 14: / Line 14: @@
 As you can can see from the graphic, the template is a lower level component this is not called directly from URL invocation.
-Instead the template engine is used in conjunction with the [[cchost/concepts/Query Engine|Query engine]] when displaying content stored in the database in ccHost (such as user upload meta-data or topics). The best way to understand to most common case usages of the template engine in this way is to study the [[Cchost/Custom_Query_Templates|query templates walk-through]]. For more advanced features make sure to see the [[Cchost/developer/tutorial/Ultimate_Template|Ultimate Template]].
+Instead the template engine is used in conjunction with the [[cchost/concepts/Query Engine|Query engine]] when displaying content stored in the database in ccHost (such as user upload meta-data or topics). The best way to understand the most common case usages of the template engine in this way is to study the [[Cchost/Custom_Query_Templates|query templates walk-through]]. For more advanced features make sure to see the [[Cchost/developer/tutorial/Ultimate_Template|Ultimate Template]].
 The template engine is also used when displaying pages authored outside the ccHost system as discussed in the [[Cchost/concepts/Content#Pages_Authored_Outside_ccHost|Content]] section via the '''docs''' command.

@@ Line 234: / Line 234: @@
 A 'macro function' is function inside a PHP template with a specific naming pattern and signature:
-   function _t_<file_name>_macro_name( &$T, &A )
+   function _t_<file_name>_<macro_name>( &$T, &A )
 In order to call this macro, the caller would specify:
@@ Line 242: / Line 242: @@
 and the ''template'' parameter in a Query API URL would be:
-   api/query?t=<file_name>/macro_name>
+   api/query?t=<file_name>/<macro_name>>
 Using this calling convention turned out to create an unfortunate situation in which the template engine doesn't know if the forward slash is meant as a file system path separator or the indicator to look into a file for a macro function.
@@ Line 254: / Line 254: @@
 The solution is not pretty.
-In order to disambiguate the template engine requires that callers put a file extension on the last macro file in the path. So if you means a file called 'links_by.tpl' you have to say so:
+In order to disambiguate the template engine requires that callers put a file extension on the last macro file in the path. So if you mean a file called 'links_by.tpl' you have to say so:
    api/query?t=formats/links_by.tpl
-otherwise:
+otherwise if you meant a macro called links_by in formats.tpl
    api/query?t=formats.php/links_by
 (Sorry about that.)

← Older revision		Revision as of 22:42, 14 November 2008
Line 231:		Line 231:

	'''6. System default locations''' ('''ccskins/shared/pages''', '''ccskins''', '''ccskins/shared''', '''ccskins/shared/formats''')		'''6. System default locations''' ('''ccskins/shared/pages''', '''ccskins''', '''ccskins/shared''', '''ccskins/shared/formats''')
		+	==Embedded Macros vs. Paths==
		+	A 'macro function' is function inside a PHP template with a specific naming pattern and signature:
		+
		+	function _t_<file_name>_macro_name( &$T, &A )
		+
		+	In order to call this macro, the caller would specify:
		+
		+	%call(<file_name>/<macro_name>)%
		+
		+	and the ''template'' parameter in a Query API URL would be:
		+
		+	api/query?t=<file_name>/macro_name>
		+
		+	Using this calling convention turned out to create an unfortunate situation in which the template engine doesn't know if the forward slash is meant as a file system path separator or the indicator to look into a file for a macro function.
		+
		+	This can be a problem when callers are in the habit of leaving off the extension of the file name:
		+
		+	api/query?t=formats/links_by
		+
		+	Does the above request mean a template called 'links_by' in the 'formats' directory? Or does it mean a macro function called 'links_by' in a template file called 'formats'?
		+
		+	The solution is not pretty.
		+
		+	In order to disambiguate the template engine requires that callers put a file extension on the last macro file in the path. So if you means a file called 'links_by.tpl' you have to say so:
		+
		+	api/query?t=formats/links_by.tpl
		+
		+	otherwise:
		+
		+	api/query?t=formats.php/links_by
		+
		+	(Sorry about that.)

@@ Line 156: / Line 156: @@
     ?>
 |-
-|%map('var-name','alias')%
+|%map('left-side','right-side')%
-|<? $alias = ''var-name''; ?>
+|<? 'left-side' = ''right-side''; ?>
 |-
 |%query(''query-spec'')%

@@ Line 69: / Line 69: @@
 Array indexing is done using the forward slash ('/'). This code initializes a local variable 'R' with the contents of $A['records'][0]:
-    %map( records/0, R )%
+    %map( #R, records/0 )%  // yes '#'
 ==Macro table==

@@ Line 198: / Line 198: @@
 The following is the precedence used for resolving partial paths by the template engine:
-. Relative to the ccHost root installation directory
+'''1. Relative to the ccHost root installation directory'''
 For example if you keep certain kinds of images in a directory directly accessible from your web root you could access them simply:
@@ Line 204: / Line 204: @@
    <nowiki><img src="%url(my_special_images/icons/pontiac.jpg)%"</nowiki>
-. Relative to the current template being parsed.
+'''2. Relative to the current template being parsed.'''
 The directory of the template that is currently being is used to override all other path considerations. This way a stylesheet or
@@ Line 223: / Line 223: @@
-. Relative to the current skin's root
+'''3. Relative to the current skin's root'''
-. Relative to any imported skins
+'''4. Relative to any imported skins'''
-. Relative to the paths found in the 'Skins Path' admin option
+'''5. Relative to the paths found in the 'Skins Path' admin option'''
-. System default locations ('''ccskins/shared/pages''', '''ccskins''', '''ccskins/shared''', '''ccskins/shared/formats''')
+'''6. System default locations''' ('''ccskins/shared/pages''', '''ccskins''', '''ccskins/shared''', '''ccskins/shared/formats''')