Merge pull request #36 from greystate/issue-35-modes

Issue 35 modes
greystate · May 9, 2015 · 1996e45 · 1996e45
2 parents 13edead + 1999e8c
commit 1996e45
Show file tree

Hide file tree

Showing 15 changed files with 151 additions and 23 deletions.
diff --git a/dist/xslt/helpers/_CalendarHelper.xslt b/dist/xslt/helpers/_CalendarHelper.xslt
@@ -3,7 +3,7 @@
 	<!-- You need to set this to the name of the property/attribute on your event nodes that holds the "date" value -->
 	<!ENTITY eventDate "eventStartDateTime">
 ]>
-<?umbraco-package XSLT Helpers v1.1.0 - CalendarHelper v1.2?>
+<?umbraco-package XSLT Helpers v1.2.0 - CalendarHelper v1.2?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:umb="urn:umbraco.library" xmlns:freeze="http://xmlns.greystate.dk/2012/freezer" xmlns:date="urn:Exslt.ExsltDatesAndTimes" xmlns:make="urn:schemas-microsoft-com:xslt" version="1.0" exclude-result-prefixes="umb date make freeze">
 
 	<!-- Grab today's date - we probably need it, this being a calendar and all -->

diff --git a/dist/xslt/helpers/_GroupingHelper.xslt b/dist/xslt/helpers/_GroupingHelper.xslt
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<?umbraco-package XSLT Helpers v1.1.0 - GroupingHelper v1.0?>
+<?umbraco-package XSLT Helpers v1.2.0 - GroupingHelper v1.0?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
 
 	<!-- 'Groupify' template -->

diff --git a/dist/xslt/helpers/_MediaHelper.xslt b/dist/xslt/helpers/_MediaHelper.xslt
@@ -8,7 +8,7 @@
 	
 	Enables simple retrieval of media by handling the GetMedia() call and error-checking
 -->
-<?umbraco-package XSLT Helpers v1.1.0 - MediaHelper v2.0?>
+<?umbraco-package XSLT Helpers v1.2.0 - MediaHelper v2.0?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:umb="urn:umbraco.library" xmlns:freeze="http://xmlns.greystate.dk/2012/freezer" xmlns:get="urn:Exslt.ExsltMath" xmlns:make="urn:schemas-microsoft-com:xslt" version="1.0" exclude-result-prefixes="umb get make freeze">
 
 

diff --git a/dist/xslt/helpers/_MultiPickerHelper.xslt b/dist/xslt/helpers/_MultiPickerHelper.xslt
@@ -4,7 +4,7 @@
 
 	Helper file for rendering various datatypes that store node ids.
 -->
-<?umbraco-package XSLT Helpers v1.1.0 - MultiPickerHelper v1.1?>
+<?umbraco-package XSLT Helpers v1.2.0 - MultiPickerHelper v1.1?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:umb="urn:umbraco.library" version="1.0" exclude-result-prefixes="umb">
 
 	<xsl:key name="document-by-id" match="*[@isDoc]" use="@id"/>

diff --git a/dist/xslt/helpers/_NavigationHelper.xslt b/dist/xslt/helpers/_NavigationHelper.xslt
@@ -3,7 +3,7 @@
 	<!-- You can change this to suit your environment -->
 	<!ENTITY subPages "*[@isDoc][not(@template = 0) and not(umbracoNaviHide = 1)]">
 ]>
-<?umbraco-package XSLT Helpers v1.1.0 - NavigationHelper v1.2?>
+<?umbraco-package XSLT Helpers v1.2.0 - NavigationHelper v1.2?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:umb="urn:umbraco.library" xmlns:freeze="http://xmlns.greystate.dk/2012/freezer" version="1.0" exclude-result-prefixes="umb freeze">
 
 <!-- :: Configuration :: -->

diff --git a/dist/xslt/helpers/_PaginationHelper.xslt b/dist/xslt/helpers/_PaginationHelper.xslt
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<?umbraco-package XSLT Helpers v1.1.0 - PaginationHelper v1.6?>
+<?umbraco-package XSLT Helpers v1.2.0 - PaginationHelper v1.7?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:umb="urn:umbraco.library" xmlns:str="urn:Exslt.ExsltStrings" xmlns:make="urn:schemas-microsoft-com:xslt" version="1.0" exclude-result-prefixes="umb str make">
 
 	<!-- Config constants -->
@@ -58,6 +58,12 @@
 		<!-- Specify which node() to sort by (as a string), e.g.: 'name', 'name DESC', '@updateDate ASC' etc. -->
 		<xsl:param name="sortBy"/>
 
+		<!-- Set to true() to enable custom sorting -->
+		<xsl:param name="customSort"/>
+
+		<!-- Set to true() to enable using a special template (if you need to apply in specific modes, or send parameters along etc.) -->
+		<xsl:param name="customApply"/>
+
 		<!-- Also, allow forcing specific options -->
 		<xsl:param name="options" select="$options"/>
 
@@ -78,18 +84,24 @@
 
 		<xsl:choose>
 			<!-- Do we need to pre-sort the selection? -->
-			<xsl:when test="normalize-space($sortBy)">
+			<xsl:when test="normalize-space($sortBy) or $customSort">
 				<xsl:variable name="sortedProxy">
 					<xsl:call-template name="preSort">
 						<xsl:with-param name="selection" select="$selection"/>
 						<xsl:with-param name="sortBy" select="$sortBy"/>
+						<xsl:with-param name="customSort" select="$customSort"/>
 					</xsl:call-template>
 				</xsl:variable>
 				<xsl:variable name="sortedSelection" select="make:node-set($sortedProxy)/nodes/nodeId"/>
 				<xsl:apply-templates select="$selection[generate-id() = $sortedSelection[position() &gt;= $startIndex and position() &lt;= $endIndex]]">
 					<xsl:sort select="count($sortedSelection[. = generate-id(current())]/preceding-sibling::nodeId)" data-type="number" order="ascending"/>
 				</xsl:apply-templates>
 			</xsl:when>
+			<xsl:when test="$customApply">
+				<xsl:call-template name="customApply">
+					<xsl:with-param name="currentSelection" select="$selection[position() &gt;= $startIndex and position() &lt;= $endIndex]"/>
+				</xsl:call-template>
+			</xsl:when>
 			<xsl:otherwise>
 				<!-- Render the current page using apply-templates -->
 				<xsl:apply-templates select="$selection[position() &gt;= $startIndex and position() &lt;= $endIndex]"/>
@@ -283,10 +295,11 @@
 	<xsl:template name="preSort">
 		<xsl:param name="selection" select="/.."/>
 		<xsl:param name="sortBy"/>
+		<xsl:param name="customSort"/>
 
 		<nodes>
 			<xsl:choose>
-				<xsl:when test="$sortBy = '$CUSTOM'">
+				<xsl:when test="$customSort">
 					<xsl:call-template name="customSort">
 						<xsl:with-param name="selection" select="$selection"/>
 					</xsl:call-template>
@@ -337,5 +350,15 @@
 	<xsl:template match="*" mode="presort">
 		<nodeId><xsl:value-of select="generate-id()"/></nodeId>
 	</xsl:template>
+
+	<!--
+		This is the template that's called when you need to customize the call to
+		`<xsl:apply-templates />` (e.g. to add a specific mode or to pass parameters).
+		The `$currentSelection` parameter holds the current page of items.
+	 -->
+	<xsl:template name="customApply">
+		<xsl:param name="currentSelection"/>
+		<xsl:apply-templates select="$currentSelection" mode="customApply"/>
+	</xsl:template>
 
 </xsl:stylesheet>
diff --git a/paginationhelper/README.md b/paginationhelper/README.md
@@ -80,12 +80,12 @@ It won't cover every scenario, e.g. it doesn't do numerical sorting, and you can
 
 ### Advanced sorting
 
-Because XSLT allows for some very special sorting (e.g., sorting by a substring of a value or the combined value of two or more values), there need to be a way to support this, so by sending the string **'$CUSTOM'** into the `sortBy` parameter, the helper will execute a named template (**"customSort"**) to perform the sorting, so in that one you can just paste your existing sort statements, e.g.:
+Because XSLT allows for some very special sorting (e.g., sorting by a substring of a value or the combined value of two or more values), there need to be a way to support this, so by specifying the `customSort` parameter as `true()`, the helper will execute a named template (**"customSort"**) to perform the sorting, so in that one you can just paste your existing sort statements, e.g.:
 
 ```xslt
 <xsl:call-template name="PaginateSelection">
 	<xsl:with-param name="selection" select="$currentPage/Textpage" />
-	<xsl:with-param name="sortBy" select="'$CUSTOM'" />
+	<xsl:with-param name="customSort" select="true()" />
 </xsl:call-template>
 
 ...
@@ -99,6 +99,33 @@ Because XSLT allows for some very special sorting (e.g., sorting by a substring
 </xsl:template>
 ```
 
+## Advanced template handling
+
+Now *what if* you have to pass a parameter to every item you render in the paginated set? Or maybe your original (un-paginated) output had two modes, e.g. a "list" mode and a "grid" mode? (It could happen :) Can you still just *inject* Pagination Helper into the mix and have everything "just work"?
+
+Well, you can at least specify that you would like a little bit more control, and that you will in fact personally oversee the specific rendering of each page yourself. Here's how:
+
+You pass the parameter `customApply` (set to `true()`) and then you modify the named "customApply" template to suit your needs, e.g., to pass an index variable to the item template, you can do this:
+
+```xslt
+<xsl:call-template name="PaginateSelection">
+	<xsl:with-param name="selection" select="$currentPage/Textpage" />
+	<xsl:with-param name="customApply" select="true()" />
+</xsl:call-template>
+
+...
+
+<xsl:template name="customApply">
+	<xsl:param name="currentSelection" />
+	<xsl:apply-templates select="$currentSelection">
+		<xsl:with-param name="index" select="position()" />
+	</xsl:apply-templates>
+</xsl:template>
+```
+
+*Note: You can take the "customSort" and/or "customApply" templates out of the Pagination Helper file and put them in your main XSLT file to have them survive between updates. Just remember to delete them from the Pagination Helper*
+
+
 ## QueryString options
 
 The pager links rendered will include all existing querystring options on the original page (i.e., "page 1"), so if

diff --git a/paginationhelper/_PaginationHelper.xslt b/paginationhelper/_PaginationHelper.xslt
@@ -85,6 +85,12 @@
 		<!-- Specify which node() to sort by (as a string), e.g.: 'name', 'name DESC', '@updateDate ASC' etc. -->
 		<xsl:param name="sortBy" />
 
+		<!-- Set to true() to enable custom sorting -->
+		<xsl:param name="customSort" />
+
+		<!-- Set to true() to enable using a special template (if you need to apply in specific modes, or send parameters along etc.) -->
+		<xsl:param name="customApply" />
+
 		<!-- Also, allow forcing specific options -->
 		<xsl:param name="options" select="$options" />
 
@@ -105,18 +111,24 @@
 
 		<xsl:choose>
 			<!-- Do we need to pre-sort the selection? -->
-			<xsl:when test="normalize-space($sortBy)">
+			<xsl:when test="normalize-space($sortBy) or $customSort">
 				<xsl:variable name="sortedProxy">
 					<xsl:call-template name="preSort">
 						<xsl:with-param name="selection" select="$selection" />
 						<xsl:with-param name="sortBy" select="$sortBy" />
+						<xsl:with-param name="customSort" select="$customSort" />
 					</xsl:call-template>
 				</xsl:variable>
 				<xsl:variable name="sortedSelection" select="make:node-set($sortedProxy)/nodes/nodeId" />
 				<xsl:apply-templates select="$selection[generate-id() = $sortedSelection[position() &gt;= $startIndex and position() &lt;= $endIndex]]">
 					<xsl:sort select="count($sortedSelection[. = generate-id(current())]/preceding-sibling::nodeId)" data-type="number" order="ascending" />
 				</xsl:apply-templates>
 			</xsl:when>
+			<xsl:when test="$customApply">
+				<xsl:call-template name="customApply">
+					<xsl:with-param name="currentSelection" select="$selection[position() &gt;= $startIndex and position() &lt;= $endIndex]" />
+				</xsl:call-template>
+			</xsl:when>
 			<xsl:otherwise>
 				<!-- Render the current page using apply-templates -->
 				<xsl:apply-templates select="$selection[position() &gt;= $startIndex and position() &lt;= $endIndex]" />
@@ -310,10 +322,11 @@
 	<xsl:template name="preSort">
 		<xsl:param name="selection" select="/.." />
 		<xsl:param name="sortBy" />
+		<xsl:param name="customSort" />
 
 		<nodes>
 			<xsl:choose>
-				<xsl:when test="$sortBy = '&CustomSortTrigger;'">
+				<xsl:when test="$customSort">
 					<xsl:call-template name="customSort">
 						<xsl:with-param name="selection" select="$selection" />
 					</xsl:call-template>
@@ -364,5 +377,15 @@
 	<xsl:template match="*" mode="presort">
 		<nodeId><xsl:value-of select="generate-id()" /></nodeId>
 	</xsl:template>
+
+	<!--
+		This is the template that's called when you need to customize the call to
+		`<xsl:apply-templates />` (e.g. to add a specific mode or to pass parameters).
+		The `$currentSelection` parameter holds the current page of items.
+	 -->
+	<xsl:template name="customApply">
+		<xsl:param name="currentSelection" />
+		<xsl:apply-templates select="$currentSelection" mode="customApply" />
+	</xsl:template>
 
-</xsl:stylesheet>
+</xsl:stylesheet>
diff --git a/paginationhelper/entities.ent b/paginationhelper/entities.ent
@@ -1,8 +1,6 @@
 <!ENTITY % use.in.umbraco "IGNORE">
 <!ENTITY % use.in.textmate "INCLUDE">
 
-<!ENTITY CustomSortTrigger "$CUSTOM">
-
 <![ %use.in.umbraco; [
 	<!ENTITY GetMediaFile "umb:GetMedia(., false())">
 	<!ENTITY GetMediaFolder "umb:GetMedia(., true())">

diff --git a/paginationhelper/test/CustomApplyTest.xspec b/paginationhelper/test/CustomApplyTest.xspec
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<x:description
+	stylesheet="PaginationHelperCustomApplySample.xslt"
+	xslt-version="1.0"
+	xmlns:x="http://www.jenitennison.com/xslt/xspec"
+>
+	<x:scenario label="when calling PaginateSelection">
+		<x:call template="PaginateSelection">
+			<x:param name="selection" select="document('fixtures/people-with-nicks.xml', /)//person" />
+			<x:param name="showPager" select="false()" />
+		</x:call>
+		<x:scenario label="with the customApply parameter">
+			<x:call>
+				<x:param name="customApply" select="true()" />
+			</x:call>
+			<x:expect label="it should use the 'customApply'-moded template">
+				<p>"James Sawyer" &lt;[email protected]&gt;</p>
+				<p>"Kate Austen" &lt;[email protected]&gt;</p>
+				<p>...</p>
+				<p>...</p>
+				<p>"Jack Shepard" &lt;[email protected]&gt;</p>
+			</x:expect>
+		</x:scenario>
+	</x:scenario>
+
+</x:description>
diff --git a/paginationhelper/test/PaginationHelperCustomApplySample.xslt b/paginationhelper/test/PaginationHelperCustomApplySample.xslt
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<xsl:stylesheet
+	version="1.0"
+	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+>
+
+	<xsl:variable name="q">&quot;</xsl:variable>
+
+	<xsl:template match="/">
+		<body>
+			<xsl:apply-templates />
+		</body>
+	</xsl:template>
+
+	<xsl:template match="people">
+		<xsl:call-template name="PaginateSelection">
+			<xsl:with-param name="customApply" select="true()" />
+		</xsl:call-template>
+	</xsl:template>
+
+	<xsl:template match="person">
+		<p>
+			<a href="{email}"><xsl:value-of select="name" /></a>
+		</p>
+	</xsl:template>
+
+	<xsl:template match="person" mode="customApply">
+		<p><xsl:value-of select="concat($q, name, $q, ' &lt;', email, '&gt;')" /></p>
+	</xsl:template>
+
+	<xsl:include href="../_PaginationHelper.xslt" />
+
+</xsl:stylesheet>
diff --git a/paginationhelper/test/PaginationHelperSample.xslt b/paginationhelper/test/PaginationHelperSample.xslt
@@ -21,7 +21,5 @@
 	</xsl:template>
 
 	<xsl:include href="../_PaginationHelper.xslt" />
-
-
 
-</xsl:stylesheet>
+</xsl:stylesheet>
diff --git a/paginationhelper/test/PaginationHelperSortedSample.xslt b/paginationhelper/test/PaginationHelperSortedSample.xslt
@@ -24,4 +24,4 @@
 
 	<xsl:include href="../_PaginationHelper.xslt" />
 
-</xsl:stylesheet>
+</xsl:stylesheet>
diff --git a/paginationhelper/test/PaginationHelperSortedTest.xspec b/paginationhelper/test/PaginationHelperSortedTest.xspec
@@ -163,9 +163,9 @@
 
 		</x:scenario>
 
-		<x:scenario label="with sortBy '$CUSTOM'">
+		<x:scenario label="with customSort true()">
 			<x:call>
-				<x:param name="sortBy" select="'$CUSTOM'" />
+				<x:param name="customSort" select="true()" />
 			</x:call>
 			<x:expect label="it should call the customSort template">
 				<p>Hugo Reyes</p>

diff --git a/version.ent b/version.ent
@@ -1,8 +1,8 @@
 <!-- Current Versions -->
-<!ENTITY packageVersion "1.1.0">
+<!ENTITY packageVersion "1.2.0">
 <!ENTITY XSLTHelpersVersionHeader "XSLT Helpers v&packageVersion;">
 <!ENTITY MediaHelperVersion "2.0">
-<!ENTITY PaginationHelperVersion "1.6">
+<!ENTITY PaginationHelperVersion "1.7">
 <!ENTITY GroupingHelperVersion "1.0">
 <!ENTITY CalendarHelperVersion "1.2">
 <!ENTITY NavigationHelperVersion "1.2">