Merge pull request #14 from sebastianconcept/13-API-for-STT-yield-nee…

…ds-to-be-adjusted-for-consistency

API adjustment for the STT yielding class to improve friendliness with Ride

CHANGES.md

@@ -1,6 +1,12 @@
 Feb 17, 2024
 ===================================
-- Using by default the same convetion seen in Ruby on Rails.
+- Using by default the same convention seen in Ruby on Rails for opening and closing tags `<% 40+2 %>` and `<%= 40+2 %>` .
+
+Jan 25, 2024
+===================================
+- STT has new deprecated methods in favor of methods that are friendlier to Ride-based applications.
+- `STT yield: aNamedPartialToYield` is now `STT yieldUsing: aNamedPartialToYield`.
+- `STT yield: aNamedPartialToYield on: aContext` is now `STT yield: aContext using: aNamedPartialToYield`.
 
 Jan 23, 2024
 ===================================

README.md

@@ -40,7 +40,7 @@ ___
 "By default it installs 'Core'"
 Metacello new
   baseline: 'STTemplate';
-  repository: 'github://sebastianconcept/STTemplate:v0.0.3';
+  repository: 'github://sebastianconcept/STTemplate:latest';
   load.
 
 "Optionally use `load: #('Core' 'Tests')`" 
@@ -49,7 +49,7 @@ Metacello new
 Or as dependency in your `Baseline`
 
 ```smalltalk
-spec baseline: 'STTemplate' with: [ spec repository: 'github://sebastianconcept/STTemplate:v0.0.3' ]
+spec baseline: 'STTemplate' with: [ spec repository: 'github://sebastianconcept/STTemplate:latest' ]
 ```
 
 ## Description
@@ -116,7 +116,7 @@ and then `42` coming from displaying `self value + 2`"
 In each iteration, it creates another Smalltalk closure that has access
 to self as expected and uses that to display its content:"
 
-'<% 1 to: 3 do: [ :i | %><p>The Answer is <span><%= self value + 2%>!</span></p><% ] >' sttRenderOn: (#answer -> 40).
+'<% 1 to: 3 do: [ :i | %><p>The Answer is <span><%= self value + 2%>!</span></p><% ] %>' sttRenderOn: (#answer -> 40).
 "'<p>The Answer is <span>42!</span></p><p>The Answer is <span>42!</span></p><p>The Answer is <span>42!</span></p>'"
 ```
 

STTemplate-Tests/STTemplateTest.class.st

@@ -998,6 +998,39 @@ STTemplateTest >> testWithoutCode [
 	self assert: ('<p>Hello</p>' sttRenderOn: nil) equals: '<p>Hello</p>'
 ]
 
+{ #category : #tests }
+STTemplateTest >> testYieldCustomContextUsingNamedPartial [
+
+	| rendered namedPartial |
+	namedPartial := { (#answer
+	                 ->
+	                 '<p>The answer is <%= 40 + (self at: #plus) %></p>' asSTTemplate) }
+		                asDictionary.
+
+	rendered := '<h1>Contents</h1><div><%= STT yield: self using: ''answer'' %></div>'
+		            sttRenderOn: { (#plus -> 2) } asDictionary
+		            partials: namedPartial.
+
+	self
+		assert: rendered
+		equals: '<h1>Contents</h1><div><p>The answer is 42</p></div>'
+]
+
+{ #category : #tests }
+STTemplateTest >> testYieldCustomContextUsingSinglePartial [
+
+	| rendered partial |
+	partial := '<p>The answer is <%= 40+self %></p>' asSTTemplate.
+
+	rendered := '<h1>Contents</h1><div><%= STT yield %></div>'
+		            sttRenderOn: 2
+		            partial: partial.
+
+	self
+		assert: rendered
+		equals: '<h1>Contents</h1><div><p>The answer is 42</p></div>'
+]
+
 { #category : #tests }
 STTemplateTest >> testYieldDeeperPartial [
 

STTemplate/STT.class.st

@@ -8,7 +8,7 @@ Class {
 }
 
 { #category : #public }
-STT class >> getTemplateFrom: aNamedPartialToYield in: partialsDictionaryish [
+STT class >> getTemplateFrom: aNamedPartialToYield in: templatesDictionaryish [
 
 	| parts selector reminder missing |
 	parts := aNamedPartialToYield substrings: '/'.
@@ -21,15 +21,16 @@ STT class >> getTemplateFrom: aNamedPartialToYield in: partialsDictionaryish [
 		reminder := '/' join: parts allButFirst.
 		^ self
 			  getTemplateFrom: reminder
-			  in: (partialsDictionaryish at: selector ifAbsent: missing) ].
+			  in: (templatesDictionaryish at: selector ifAbsent: missing) ].
 
-	^ partialsDictionaryish at: parts first ifAbsent: missing
+	^ templatesDictionaryish at: parts first ifAbsent: missing
 ]
 
 { #category : #public }
 STT class >> yield: aNamedPartialToYield [
 
 	| renderingContext |
+	self deprecated: ' use yield:using:'.
 	renderingContext := STTCurrentRenderingContext value.
 	renderingContext ifNil: [ 
 		STTError signal:
@@ -42,23 +43,49 @@ STT class >> yield: aNamedPartialToYield [
 STT class >> yield: aNamedPartialToYield on: aContext [
 
 	| renderingContext template outStream result |
+	self deprecated: ' use yield:using:'.	
 	renderingContext := STTCurrentRenderingContext value.
 	template := self
 		            getTemplateFrom: aNamedPartialToYield
-		            in: renderingContext partials.
+		            in: renderingContext templates.
 	outStream := STTCurrentRenderingStream value.
 	result := template
 		          renderOn: aContext
-		          partials: renderingContext partials.
+		          partials: renderingContext templates.
 	outStream nextPutAll: result
 ]
 
 { #category : #public }
-STT class >> yieldPartial: anSTTemplate on: aContext [
+STT class >> yield: aContext template: anSTTemplate on: writeStream [
 
-	| renderingContext outStream result |
+	writeStream nextPutAll: (anSTTemplate renderOn: aContext)
+]
+
+{ #category : #public }
+STT class >> yield: aContext using: aNamedTemplateToYield [
+
+	| renderingContext template |
 	renderingContext := STTCurrentRenderingContext value.
-	outStream := STTCurrentRenderingStream value.
-	result := anSTTemplate renderOn: aContext.
-	outStream nextPutAll: result
+	template := self
+		            getTemplateFrom: aNamedTemplateToYield
+		            in: renderingContext templates.
+
+	self
+		yield: aContext
+		template: template
+		on: STTCurrentRenderingStream value
+]
+
+{ #category : #public }
+STT class >> yieldUsing: aNamedPartialToYield [
+
+	| renderingContext |
+	renderingContext := STTCurrentRenderingContext value.
+	renderingContext ifNil: [ 
+		STTError signal:
+			('Template context unreacheable while trying to yield {1}' format:
+				 { aNamedPartialToYield asString }) ].
+	self
+		yield: renderingContext templateContext
+		using: aNamedPartialToYield
 ]

STTemplate/STTRenderingContext.class.st

@@ -9,34 +9,34 @@ Class {
 	#superclass : #Object,
 	#instVars : [
 		'templateContext',
-		'partials'
+		'templates'
 	],
 	#category : #'STTemplate-Core'
 }
 
 { #category : #'instance creation' }
-STTRenderingContext class >> on: aTemplateContext partials: partialsDictionarish [
+STTRenderingContext class >> on: aTemplateContext templates: templatesDictionarish [
 
 	^ self new
 		  initializeOn: aTemplateContext
-		  partials: partialsDictionarish
+		  templates: templatesDictionarish
 ]
 
 { #category : #initialization }
-STTRenderingContext >> initializeOn: aTemplateContext partials: partialsDictionarish [
+STTRenderingContext >> initializeOn: aTemplateContext templates: templatesDictionarish [
 
 	templateContext := aTemplateContext.
-	partials := partialsDictionarish
+	templates := templatesDictionarish
 ]
 
 { #category : #accessing }
-STTRenderingContext >> partials [
+STTRenderingContext >> templateContext [
 
-	^ partials
+	^ templateContext
 ]
 
 { #category : #accessing }
-STTRenderingContext >> templateContext [
+STTRenderingContext >> templates [
 
-	^ templateContext
+	^ templates
 ]

STTemplate/STTemplate.class.st

@@ -335,7 +335,7 @@ STTemplate >> isToBeDisplayed: sourceStream displayToken: displayToken [
 STTemplate >> isUnnamedYield: aSmalltalkExpression [
 
 	^ (aSmalltalkExpression indexOfSubCollection: 'yield') > 0 and: [ 
-		  (aSmalltalkExpression indexOfSubCollection: 'yield:') isZero ]
+		  (aSmalltalkExpression indexOfSubCollection: 'yieldUsing:') isZero ]
 ]
 
 { #category : #actions }
@@ -369,6 +369,7 @@ STTemplate >> render [
 STTemplate >> renderNamedYieldsFrom: smalltalkExpression on: rendered [
 
 	| partialRenderingSnippet |
+
 	partialRenderingSnippet := String streamContents: [ :str | 
 		                           str nextPutAll: smalltalkExpression.
 		                           self
@@ -388,21 +389,21 @@ STTemplate >> renderOn: anObject [
 ]
 
 { #category : #actions }
-STTemplate >> renderOn: anObject partial: partial [
+STTemplate >> renderOn: anObject partial: aSTTemplate [
 
 	"Answer the result of rendering the receiver using anObject as template context
-	and the given partial to be yield in the template.
+	and the given aSTTemplate as partial to be yield in the (main)template.
 	The partials are nothing but sub-templates that have also access to the template context.
 	The STTCurrentRenderingContext dynamic variable and STTCurrentRenderingContext gives them
 	access to complete its rendering process."
 
 	^ self
 		  renderOn: anObject
-		  partials: { (#_yield -> partial) } asDictionary
+		  partials: { (#_yield -> aSTTemplate) } asDictionary
 ]
 
 { #category : #actions }
-STTemplate >> renderOn: anObject partials: partialsDictionarish [
+STTemplate >> renderOn: anObject partials: templatesDictionarish [
 
 	"Answer the result of rendering the receiver using anObject as template context
 	and the given partials.
@@ -415,7 +416,7 @@ STTemplate >> renderOn: anObject partials: partialsDictionarish [
 			  | renderingContext |
 			  renderingContext := STTRenderingContext
 				                      on: anObject
-				                      partials: partialsDictionarish.
+				                      templates: templatesDictionarish.
 			  STTCurrentRenderingContext value: renderingContext during: [ 
 				  (self compiledMethodOn: anObject)
 					  valueWithReceiver: anObject
@@ -498,7 +499,8 @@ STTemplate >> renderYieldOn: rendered [
 	| partialRenderingSnippet smalltalkExpression |
 	"Preserves the context in which the partial should be rendered
 	and makes it available by grabbing it from the expected private selector key."
-	smalltalkExpression := 'STT yield: #_yield on: self'.
+
+	smalltalkExpression := 'STT yieldUsing: #_yield'.
 
 	partialRenderingSnippet := String streamContents: [ :str | 
 		                           str nextPutAll: smalltalkExpression.

STTemplate/String.extension.st

@@ -34,21 +34,20 @@ String >> sttRenderOn: anObject [
 ]
 
 { #category : #'*STTemplate' }
-String >> sttRenderOn: anObject partial: partial [
-
+String >> sttRenderOn: anObject partial: aSTTemplate [
 	"Answers the result of rendering an `STTemplate`
 	created from the receiver and rendered using 
-	the given object as template context and the given 
-	partial template to yield within."
+	the given object as context for the template and the given 
+	aSTTemplate to yield within."
 
-	^ self asSTTemplate renderOn: anObject partial: partial
+	^ self asSTTemplate renderOn: anObject partial: aSTTemplate
 ]
 
 { #category : #'*STTemplate' }
-String >> sttRenderOn: anObject partials: partialsDictionarish [
+String >> sttRenderOn: anObject partials: templatesDictionarish [
 
 	"Answers the result of rendering an `STTemplate`
-	 created from the receiver and rendered using the given object."
+	 created from the receiver and rendered using the given object and (sub)templates."
 
-	^ self asSTTemplate renderOn: anObject partials: partialsDictionarish
+	^ self asSTTemplate renderOn: anObject partials: templatesDictionarish
 ]

tryOnTeapot.md

@@ -2,7 +2,7 @@
 ```smalltalk
 Metacello new
   baseline: 'Teapot';
-  repository: 'github://zeroflag/Teapot/source';
+  repository: 'github://zeroflag/Teapot:v2.7.0/source';
   load.
 ```