Changes for page Custom Project Templates

Summary

• Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.mschrag
	1	+XWiki.avendasora

Content

...	...	@@ -1,44 +1,76 @@
1		-WOLips 3.3+ supports the definition of custom project templates. These templates support the declaration of custom configuration parameters and the files within the template are processed using the [[Velocity Template Engine>>http://velocity.apache.org/engine/devel/vtl-reference-guide.html]].
	1	+{{toc}}{{/toc}}
2	2
3		-To use a custom project template, select the "WO Project from Template" option under the WOLips category of the New Project Wizard.
	3	+= Introduction =
4	4
5		-[[image:WOProjectFromTemplate.png]]
	5	+WOLips 3.3 supports the definition of custom project templates. These templates support creating new types of WebObjects projects beyond the ones that ship with WOLips.
6	6
7		-==== Creating a Template ====
	7	+To use a custom project template, create a new project by going to the "File" menu and selecting "New -> Other..." then select the "WO Project from Template" option under the WOLips section.
	8	+[[image:NewProjectFromTemplate.png]]
8	8
	10	+= Creating a Template =
	11	+
	12	+Templates are basically like a regular project folder, but some of the contents are modified to use the variables defined in the template.xml file to change their names or values in their contents. The modified files within the template are processed using the [[Velocity Template Engine>>http://velocity.apache.org/engine/devel/vtl-reference-guide.html]].
	13	+
9	9	The declaration of templates is very simple. The template system looks for folders in the following locations (in the following order):
10	10
11		-* The ProjectTemplates folder inside of the WOLips templateengine plugin jar
12		-* /Library/Application Support/WOLips/Project Templates
13		-* YourHomeDirocuments and Settingspplication DataOLipsroject Templates
14		-* YourHomeDirocuments and SettingsppDataocalOLipsroject Templates
15		-* ,,/Library/Application Support/WOLips/Project Templates,,
	16	+1. The ProjectTemplates folder inside of the WOLips templateengine plugin jar
	17	+1. /Library/Application Support/WOLips/Project Templates
	18	+1. YourHomeDirocuments and Settingspplication DataOLipsroject Templates
	19	+1. YourHomeDirocuments and SettingsppDataocalOLipsroject Templates
	20	+1. /Library/Application Support/WOLips/Project Templates
16	16
17		-Without any additional metadata, the template system derives the name of the template from the name of the folder in one of the above locations. For instance, if you create a folder named ",,/Library/Application Support/WOLips/Project Templates/Wonder Application," the template system will offer a template named "Wonder Application" in the template selection dialog. Project templates found later in the list of locations above will override those of the same name from earlier in the list. For instance, a "Wonder Application" template found in ,,/Library will overrode a "Wonder Application" template from /Library.
	22	+{{note}}
	23	+Project templates found later in the list of locations above will override those of the same name from earlier in the list. For instance, a "Wonder Application" template found in \~/Library will override a "Wonder Application" template from /Library.
	24	+{{/note}}
18	18
19		-After creating a template folder, you can create a hierarchy of files and folders within that folder. When you create a project using this template, a copy of all of the files and folders in your template will be used to create the new project. It is up to you to declare //all// of the files within a project, including Eclipse project metadata files like .classpath. You can refer to the built-in project templates as a starting point for creating your own custom templates.
	26	+The name that the template shows up as in the New Project wizard is controlled by one of two things:
20	20
21		-That's it! For creating static boilerplate templates, you're done.
	28	+1. The template's folder name
	29	+1. The name attribute of the template tag in the template.xml file inside the template folder (if present, this overrides the value set by the template folder name).
22	22
23		-==== Template Metadata and Template Inputs ====
	31	+For instance, if you create a folder named ",,/Library/Application Support/WOLips/Project Templates/Wonder Application," the template system will offer a template named "Wonder Application" in the template selection dialog. If you then set the name attribute to "My Wonder Application", that is what you will see in the dialog.,,
24	24
	33	+If you want to look at the current templates that ship with WOLips, the best way to analyse them is by [[importing the source>>Building WOLips]] of WOLips from Subversion. The templates are located in //woproject/wolips/core/plugins/org.objectstyle.wolips.templateengine/ProjectTemplates//.
	34	+
	35	+Here is an additional custom template for creating [[Wonder ERD2W Applications>>Custom Project Templates^Wonder ERD2W Application.zip||title="Click to download attachment"]] that you can view as an example.
	36	+
	37	+{{note}}
	38	+Remember, if you copy an existing template to test it out you must rename both the folder *and* the name attribute of the template tag in the template.xml file otherwise whichever loads last will replace the first!
	39	+{{/note}}
	40	+
	41	+After creating a template folder, you can create a hierarchy of files and folders within that folder. When you create a project using this template, a copy of all of the files and folders in your template will be used to create the new project. It is up to you to declare //all// of the files within a project, including Eclipse project metadata files like .classpath. You can refer to the built-in project templates as a starting point for creating your own custom templates.
	42	+
	43	+That's it For creating static boilerplate templates, you're done.
	44	+
	45	+= Template Metadata and Template Inputs =
	46	+
25	25	For a static template, the simple process above is enough. However, it's a common requirement to have configuration options for project templates. The WOLips project template engine provides an easy way to declare these options.
26	26
27		-After creating a template using the directions in the above section, you can additionally create a file named "template.xml" inside your project template folder. For instance, in the example above, you would create the file ",,/Library/Application Support/WOLips/Project Templates/Wonder Application/template.xml". ,,
	49	+After creating a template using the directions in the above section, you can additionally create a file named "template.xml" inside your project template folder. For instance, in the example above, you would create the file ",,/Library/Application Support/WOLips/Project Templates/My Application Template/template.xml".,,
28	28
29	29	An example template.xml is below:
30	30
31		- <?xml version="1.0" encoding="UTF-8"?>
32		- <template name = "Wonder Application">
	53	+{{code value="xml"}}
	54	+
	55	+<?xml version="1.0" encoding="UTF-8"?>
	56	+ <template name = "My Application">
33	33	<inputs>
34		- <input name = "linkToWonderProjects" type = "Boolean">
35		- <question>Link to Wonder Projects?</question>
36		- <default>false</default>
	58	+ <input name = "basePackage" type = "Package">
	59	+ <question>Base Package?</question>
	60	+ <default>your.app</default>
37	37	</input>
38		- <input name = "linkToWonderFrameworks" type = "Boolean">
39		- <question>Link to Wonder Frameworks?</question>
40		- <default>true</default>
	62	+ <input name = "componentsPackage" type = "Package">
	63	+ <question>Components Package?</question>
	64	+ <default>your.app.components</default>
41	41	</input>
	66	+ <input name = "servletDeployment" type = "Boolean">
	67	+ <question>Deploy to Servlet Container?</question>
	68	+ <default>false</default>
	69	+ </input>
	70	+ <input name = "webXML" type = "Boolean">
	71	+ <question>Autogenerate web.xml file?</question>
	72	+ <default>false</default>
	73	+ </input>
42	42	<input name = "YourFavoriteColor" type = "String">
43	43	<question>Your Favorite Color?</question>
44	44	<options>
...	...	@@ -51,34 +51,65 @@
51	51	</inputs>
52	52	</template>
53	53
54		-The "name" attribute of the template node overrides the name of the folder the templates are in. For instance, you could have the above template.xml inside a folder named "Template 1" and the template system would consider the name of the template to be "Wonder Application."
	86	+{{/code}}
55	55
56		-Within a template, you can declare a single "inputs" node that can contain multiple "input" nodes. Each input node corresponds to a variable that will be presented to the user on the second page of the wizard. Each input specifies a "name" attribute, which will become the variable name of the input for later reference in the Velocity templates; and a "type" attribute which can be one of Boolean, String, or Integer. The type value determines the control that will be used to display the input to the user (String = text field, Boolean = checkbox, Integer = spinner, etc). Each input also contains a "question" node, whose value corresponds to the label of the control when displayed to the user. In the above example, the "linkToWonderFrameworks" will display a checkbox to the user with the label "Link to Wonder Frameworks?". Additionally, you can provide a "default" node that defines the default value of the variable. If a default is not specified, the default value will be null for all input types.
	88	+If you don't set a "name" attribute in the "template" tag, the name of the Template Folder will be used. In this example the Template will show up as "My Application" in the list of available templates. If "name" handn't been defined, the it would show up as the folder name, which was "My Application Template".
57	57
	90	+Within a template, you can declare a single "inputs" node that can contain multiple "input" nodes. Each input node corresponds to a variable that will be presented to the user on the second page of the wizard. Each input specifies a "name" attribute, which will become the variable name of the input for later reference in the Velocity templates; and a "type" attribute which will determine the type of control presented to the user. They are:
	91	+
	92	+* Boolean -> Check Box
	93	+* String -> Text Field
	94	+* Package -> Text Field
	95	+* Integer -> Spinner
	96	+
	97	+Each input also contains a "question" node, whose value corresponds to the label of the control when displayed to the user. In the above example, the "servletDeployment" will display a checkbox to the user with the label "Deploy to Servlet Container?". Additionally, you can provide a "default" node that defines the default value of the variable. If a default is not specified, the default value will be null for all input types.
	98	+
	99	+The package type is slight extension to the String type. For a variable declared as type Package, in addition to having your variable bound, you will also have a variable named "yourvariablename//folder" with replaces dots for slashes. For instance, if your variable is named "basePackage" you will also get a variable named "$basePackage//folder". If the user left the default of "your.app" in the basePackage field, then the two variables would be:
	100	+
	101	+* basePackage = "your.app"
	102	+* basePackage//folder = "your/app"//
	103	+
58	58	Finally, the input system supports the declaration of enumerated types. By declaring an "options" node that contains an ordered set of "option" nodes, you can define the possible values that the user can provide. In the above example, the "YourFavoriteColor" input defines three options: Red, Green, and Blue. Each option node has a "name" attribute, which will be the value displayed to the user, and a "value" attribute, which will be the actual backing value of the selection. The value of the option should be of the type specified in the "type" attribute of the input. For instance, if you declare the input type to be "Integer," your option values should be integer values (in quotes).
59	59
60		-==== Using Template Inputs ====
	106	+= Using Template Inputs =
61	61
62		-So now that you have template input defined, you will want to be able to use them. The name use used in the "name" attribute of your input declaration will be the name of the variable in your Velocity context. For instance, in the example above, the Velocity variable "linkToWonderProjects" will be bound to the boolean value corresponding to the user's selection, and can be used just like any other velocity variable. The Apache project provides a [[Velocity reference guide>>http://velocity.apache.org/engine/devel/vtl-reference-guide.html]].
	108	+So now that you have template inputs defined, you need to be able to use them. The name used in the "name" attribute of your input node will be the name of the variable you can use in your template's files. For instance, in the example above, the Velocity variable "servletDeployment" will be bound to the boolean value corresponding to the user's selection, and can be used just like any other velocity variable. The Apache project provides a [[Velocity reference guide>>http://velocity.apache.org/engine/devel/vtl-reference-guide.html]].
63	63
64		-As an example, the Wonder Application template's .classpath file is defined as:
	110	+As an example, the .classpath file can be modified to automatically add a link to the JavaWOJSPServlet.framework if the user selects "Deploy to Servlet Container" in the the wizard.
65	65
66		- <?xml version="1.0" encoding="UTF-8"?>
67		- <classpath>
68		- <classpathentry kind="src" path="Sources"/>
69		- #if ($linkToWonderProjects)
70		- <classpathentry combineaccessrules="false" kind="src" path="/ERJars"/>
71		- <classpathentry combineaccessrules="false" kind="src" path="/ERExtensions"/>
72		- <classpathentry combineaccessrules="false" kind="src" path="/ERPrototypes"/>
73		- <classpathentry combineaccessrules="false" kind="src" path="/JavaWOExtensions"/>
74		- #end
75		- #if ($linkToWonderFrameworks)
76		- <classpathentry kind="con" path="org.objectstyle.wolips.WO//CLASSPATH/ERExtensions/ERJars/ERPrototypes/JavaWOExtensions/JavaEOAccess/JavaEOControl/JavaFoundation/JavaJDBCAdaptor/JavaWebObjects/JavaXML"/>
77		- #else
78		- <classpathentry kind="con" path="org.objectstyle.wolips.WO//CLASSPATH/JavaEOAccess/JavaEOControl/JavaFoundation/JavaJDBCAdaptor/JavaWebObjects/JavaXML"/>
79		- #end
80		- <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE//CONTAINER"/>
81		- <classpathentry kind="output" path="bin"/>
82		- </classpath>//
	112	+{{code value="xml"}}
83	83
84		-Happy templating!
	114	+<?xml version="1.0" encoding="UTF-8"?>
	115	+<classpath>
	116	+ <classpathentry kind="src" path="Sources"/>
	117	+ <classpathentry kind="con" path="WOFramework/JavaEOAccess"/>
	118	+ <classpathentry kind="con" path="WOFramework/JavaEOControl"/>
	119	+ <classpathentry kind="con" path="WOFramework/JavaFoundation"/>
	120	+ <classpathentry kind="con" path="WOFramework/JavaJDBCAdaptor"/>
	121	+ <classpathentry kind="con" path="WOFramework/JavaWebObjects"/>
	122	+ <classpathentry kind="con" path="WOFramework/JavaXML"/>
	123	+ <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
	124	+#if ($servletDeployment)
	125	+ <classpathentry kind="con" path="WOFramework/JavaWOJSPServlet"/>
	126	+#end
	127	+ <classpathentry kind="output" path="bin"/>
	128	+</classpath>
	129	+
	130	+{{/code}}
	131	+
	132	+In addition to variables inside of Velocity templates, you can also use template variables in folder and file names. However, because $ is not allowed on some filesystems, we instead surround the variable names with "" (for instance $someVariable would be "someVariable" in the filename or path). As an example, the template above has an input named "basePackage" (of type Package) which, as we learned above, creates two variables: "basePackage" and "basePackage//folder". Since we are going to be using this variable to name (and define the path) of a folder in the Sources directory, we need to use the alternate version of the variable. Create a new folder in the Sources directory of the project templaet and instead of using "{{basePackage_folder}}{{/basePackage_folder}}" as the file name, we must use "basePackage//folder".
	133	+
	134	+= Special Circumstances =
	135	+
	136	+===== Flagging files to be skipped by Velocity =====
	137	+
	138	+If there are files in your template that should not be processed by Velocity as the project is being setup, you will need to end the file name with "binary" which will cause Velocity to strip the "binary" off the file name, but skip processing the contents of the file. Examples of files that you'd want to flag are:
	139	+
	140	+* EOGenerator Templates
	141	+* Custom builder .launch files.
	142	+
	143	+===== Using keypaths =====
	144	+
	145	+* If you need to call a method on a given variable, you need to include the "()" at the end of the method name. An eample is in the build.properties file. In order to get the lowercase version of the project name, you have to call "{{projectName.toLowerCase()}}{{/projectName.toLowerCase()}}"
	146	+
	147	+Happy templating