..	*******************************************************************************
	* MetaFactory.io R2
	* Technical Documentation
	* 
	* File name   : VE_Functions.rst
	* Created by  : Marnix Bochove (original text)
	*
	* MetaFactory BV Amsterdam 
	*******************************************************************************

.. include:: /inline-images.txt
.. include:: /external-links.txt

Velocity Functions
==================
These are functions that can be called from a Velocity snippet using so-called context variables

|Eye M| For global variables see :ref:`Freemarker and Velocity Context Variables <Reference/TemplateEngines/ContextVariables:Freemarker and Velocity Context Variables>`

Call by using the *$metafactory* context variable
-------------------------------------------------

..	list-table::
	:widths: 40 60
	:header-rows: 1
	:class: tight-table
	
	*	-	Name and Type
		-	Description
	*	-	asList(Object[] someArray): List
		-	Converts a array to a list.
			
			This method can be called from velocity to convert a array to a list so it’s easier to get some element or to find it’s length.
	*	-	createEmptyList(): List
		-	Creates a empty ArrayList (java.util.ArrayList) 
	*	-	createEmptyMap(): Map
		-	Creates a empty Map (java.util.Map) 
	*	-	addLibraryToClass(String library)
		-	Adds a library (import statement) to the current class 
	*	-	addLibraryToClass(String library, boolean isStatic)
		-	Adds a library (import statement) to current class. If isStatic is true, a static import is created, otherwise a “normal” import.
	*	-	addLibrary(XMIClass sxmiClass, String library, boolean isStatic)
		-	Adds a library (import statement) to sxmiClass. If isStatic is true, a static import is created, otherwise a “normal” import.
	*	-	addLibraryToInterface(String library)
		-	Adds a library (import statement) to the current interface 
	*	-	addLibraryToInterface(String library, boolean isStatic)
		-	Adds a library (import statement) to current interface. If isStatic is true, a static import is created, otherwise a “normal” import.
	*	-	addLibrary(XMIInterface sxmiInterface, String library, boolean isStatic)
		-	Adds a library (import statement) to sxmiInterface. If isStatic is true, a static import is created, otherwise a “normal” import. 
	*	-	evaluateSnippet(String snippetName): String
		-	Evaluates a velocity snippet. The snippetName has the the same syntax as the pattern, but without ${snippet. and without }.
			If the snippet can not be found, it’s automatically created with default content.
			
			Loupe S| Example: We have this snippet expression in the pattern: ${snippet.java.model.operation.tostring}.
			
			We can call this snippet from a velocity template this way:
			
			
			.. code-block::
			
				$generator.evaluateSnippet(“java.model.operation.tostring”)
			
	*	-	evaluateSnippet(String snippetName, String defaultSnippetContent): String
		-	Evaluates a velocity snippet. The snippetName has the the same syntax as the pattern, but without ${snippet. and without }.
			If the snippet can not be found, it’s automatically created with defaultSnippetContent.
			
			Loupe S| Example: We have this snippet expression in the pattern: ${snippet.java.model.operation.tostring}.
			
			We can call this snippet from a velocity template this way:
			
			.. code-block::
			
				$generator.evaluateSnippet(“java.model.operation.tostring”, “// TODO: implement toString”)
			
	*	-	evaluateFreeMarkerSnippet(String snippetName): String
		-	Evaluates a freemarker snippet. The snippetName has the the same syntax as the pattern, but without ${fmsnippet. and without }.
			If the snippet can not be found, it’s automatically created.
			
			Loupe S| Example: We have this snippet expression in the pattern: ${fmsnippet.java.cdi.beans.load}.
			
			We can call this snippet from a freemarker template this way:
			
			.. code-block::
			
				$generator.evaluateFreeMarkerSnippet(“java.cdi.beans.load”)
	*	-	evaluateFreeMarkerSnippet(String snippetName, String defaultSnippetContent): String
		-	Evaluates a freemarker snippet. The snippetName has the the same syntax as the pattern, but without ${fmsnippet. and without }.
			If the snippet can not be found, it’s automatically created with defaultSnippetContent.
			
			Loupe S| Example: We have this snippet expression in the pattern: ${fmsnippet.java.cdi.beans.load}.
			
			We can call this snippet from a freemarker template this way:
			.. code-block::
			
				$generator.evaluateFreeMarkerSnippet(“java.cdi.beans.load”, “default content of new snippet if it doesn’t exist yet”)

Call by using the $context context variable
-------------------------------------------

..	list-table::
	:widths: 40 60
	:header-rows: 1
	:class: tight-table
	
	*	-	Name and Type
		-	Description
	*	-	getPatternPropertyValue(String propertyName): String
		-	Finds the value of pattern property with name propertyName and throws PropertyNotFoundException if property not found
			
			Loupe S| Example:Suppose you have the following pattern property:
			
			.. code-block:: xml
			
				<pattern>
					<properties>
						... 
						<images.webdir>/images</images.webdir>
						... 
					</properties>
					... 
				</pattern>
			
			The pattern property images.webdir can be used in a velocity snippet this way:
			
			.. code-block:: xml
				
				${context.getPatternPropertyValue('images.webdir')}
	*	-	getPatternPropertyValue(String key, String defaultValue): String
		-	Finds the value of pattern property with name propertyName and returns defaultValue if property not found
			
			Loupe S| Example:Suppose you have the following pattern property:
			
			.. code-block:: xml
			
				<pattern>
					<properties>
						... 
						<images.webdir>/images</images.webdir>
						... 
					</properties>
					... 
				</pattern>
			
			The pattern property images.webdir can be used in a velocity snippet this way:
			
			.. code-block:: xml
			
				${context.getPatternPropertyValue('images.webdir', 'images')}
			
	*	-	existsPatternProperty(String key): boolean
		-	Checks if the pattern property with name is key exists.
			
			Loupe S| Example: Suppose you have the following pattern property:
			
			.. code-block:: xml
			
				<pattern>
					<properties>
						... 
						<images.webdir>/images</images.webdir>
						... 
					</properties>
					... 
				</pattern>
			
			The following code can be used to check if this property exists:
			
			.. code-block:: xml
			
				#if($context.existsPatternProperty(‘images.webdir’)) 
					…do something 
				#else 
					…do something else 
				#end
			
	*	-	getProjectPropertyValue(String propertyName): String
		-	Finds the value of project property with name propertyName. Throws a PropertyNotFoundException if property not found.
	*	-	getProjectPropertyValue(String key, String defaultValue): String
		-	Finds the value of project property with name propertyName. Returns defaultValue if property not found.
	*	-	existsProjectProperty(String key): boolean
		-	Checks if the project property with specified key exists.

Call by using the $sxmiFactory context variable
-----------------------------------------------

..	list-table::
	:widths: 40 60
	:header-rows: 1
	:class: tight-table
	
	*	-	Name and Type
		-	Description
	*	-	sxmiFactory 
		-	|Hammer M| Not documented yet. Please send an email.


Best practices and lines you often need
---------------------------------------

-	Always check if your expectations are true.
	If you expect something to be loaded, check it and give a error with a good explanation => Fail Fast!.
	
-	Declare and define the variables you need in velocity.