summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorpelder2006-05-24 16:26:54 (EDT)
committer pelder2006-05-24 16:26:54 (EDT)
commit5097864833e1998fcfca4484fec648874be475c1 (patch)
tree7d47523c2ba87b1fdf29110c8f3027c1e6064611
parent06878ec7852c0d73d0e8cffaa70350d77fe6751c (diff)
downloadorg.eclipse.jet-5097864833e1998fcfca4484fec648874be475c1.zip
org.eclipse.jet-5097864833e1998fcfca4484fec648874be475c1.tar.gz
org.eclipse.jet-5097864833e1998fcfca4484fec648874be475c1.tar.bz2
[143581] Provide "Getting Started" documentation for JET.
-rw-r--r--doc/org.eclipse.jet.doc/build.xml2
-rw-r--r--doc/org.eclipse.jet.doc/gettingStarted/commonTags.xhtml66
-rw-r--r--doc/org.eclipse.jet.doc/gettingStarted/deployingTransforms.xhtml36
-rw-r--r--doc/org.eclipse.jet.doc/gettingStarted/essentialXPath.xhtml51
-rw-r--r--doc/org.eclipse.jet.doc/gettingStarted/index.xhtml24
-rw-r--r--doc/org.eclipse.jet.doc/gettingStarted/newProject.xhtml24
-rw-r--r--doc/org.eclipse.jet.doc/gettingStarted/runningTransforms.xhtml29
-rw-r--r--doc/org.eclipse.jet.doc/gettingStarted/transformStructure.xhtml34
-rw-r--r--doc/org.eclipse.jet.doc/toc.xml8
9 files changed, 272 insertions, 2 deletions
diff --git a/doc/org.eclipse.jet.doc/build.xml b/doc/org.eclipse.jet.doc/build.xml
index ee9ba0a..53cfef6 100644
--- a/doc/org.eclipse.jet.doc/build.xml
+++ b/doc/org.eclipse.jet.doc/build.xml
@@ -73,7 +73,7 @@
<zip destfile="doc.zip" compress="true">
<!-- Add new folders for documentation zip here. -->
<zipfileset dir="images" prefix="images"/>
-<!-- <zipfileset dir="gettingStarted" prefix="gettingStarted"/> -->
+ <zipfileset dir="gettingStarted" prefix="gettingStarted"/>
<!-- <zipfileset dir="tasks" prefix="tasks"/> -->
<!-- <zipfileset dir="concepts" prefix="concepts"/> -->
<zipfileset dir="references" prefix="references" excludes="**/internal,**/internal/**,**/*.internal.*,**/*.internal.*/**"/>
diff --git a/doc/org.eclipse.jet.doc/gettingStarted/commonTags.xhtml b/doc/org.eclipse.jet.doc/gettingStarted/commonTags.xhtml
new file mode 100644
index 0000000..51da6fc
--- /dev/null
+++ b/doc/org.eclipse.jet.doc/gettingStarted/commonTags.xhtml
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
+<title>Common JET Tags</title>
+</head>
+<body>
+<h2>Common JET Tags</h2>
+<p>JET includes four <b>tag libraries</b>, which are collections of related tags. These are:
+<ul>
+ <li> Control tags - used for accessing the input model, and controlling template execution.</li>
+ <li> Format tags - used to alter (format) text in templates according to certain rules. </li>
+ <li> Java tags - special tags useful to generating Java code.</li>
+ <li> Workspace tags - used for creating workspace resources, such as files, folders and projects.</li>
+</ul>
+</p>
+<p>Although there are many tags available, only a few are needed to get started.
+These tags are either control or workspace tags</p>
+<h3>Most common control tags</h3>
+<p>Control tags usually access the input model, and either produce a value, or cause an action based on the information
+extracted from the input model. The control tags access the input model via <b>XPath expressions</b>.
+(See <a href="essentialXPath.xhtml">Essential XPath</a>).
+Three control tags are used frequently:
+<ul>
+ <li> <code><a href="../references/taglibs/controlTags/getTag.html">c:get</a></code> - Write a value from the input model into the expanded template.</li>
+ <li> <code><a href="../references/taglibs/controlTags/getTag.html">c:iterate</a></code> - Traverse elements in the input model and evaluate the contained template text once for each element. </li>
+ <li> <code><a href="../references/taglibs/controlTags/getTag.html">c:set</a></code> - create or set an attribute on a model element. This is frequently used to store the result of a calculation. </li>
+</ul>
+
+</p>
+<h3>Most common workspace tags</h3>
+<p>Three workspace tags are used frequently:
+<ul>
+ <li> <code><a href="../references/taglibs/workspaceTags/fileTag.html">ws:file</a></code> - Write a workspace file, settings its contents to the result of expanding a template.</li>
+ <li> <code><a href="../references/taglibs/workspaceTags/folderTag.html">ws:folder</a></code> - Create a workspace folder. </li>
+ <li> <code><a href="../references/taglibs/workspaceTags/projectTag.html">ws:project</a></code> - Create a workspace project. </li>
+</ul>
+</p>
+<h3>Accessing model elements within tag attributes</h3>
+<p>Frequently, templates must use a model value in a tag's attribute. For example, the name of a generated file
+might depend on a value from the input model. To do this, the <code>main.jet</code> template would require a <code>ws:file</code> that looks like:
+<br/><br/>
+<samp>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;ws:file template="..." path="... value from the model..."/&gt;
+</samp>
+<br/><br/>
+Because JET does not permit one XML tag to be embedded in an attribute value of another, JET provides
+<b>Dynamic XPath Expressions</b>, which can be used only in tag attribute values. The format of a dynamic
+XPath expression is:
+<br/><br/>
+<samp>
+&nbsp;&nbsp;&nbsp;&nbsp;{<i>XPath expression</i>}
+</samp>
+<br/><br/>
+So, the <code>ws:file</code> tag above would be written as:
+<br/><br/>
+<samp>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;ws:file template="..." path="{<i>XPath expression</i>}"/&gt;
+</samp>
+<br/><br/>
+</p>
+</body>
+</html>
diff --git a/doc/org.eclipse.jet.doc/gettingStarted/deployingTransforms.xhtml b/doc/org.eclipse.jet.doc/gettingStarted/deployingTransforms.xhtml
new file mode 100644
index 0000000..084e564
--- /dev/null
+++ b/doc/org.eclipse.jet.doc/gettingStarted/deployingTransforms.xhtml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
+<title>Deploy a JET Transforms</title>
+</head>
+<body>
+<h2>Deploying JET Transforms</h2>
+<p>Once a JET transform is complete, it can be shared with other users. There are a number of possibilities:
+<ul>
+ <li> Share the JET Project via a Team environment </li>
+ <li> <a href="#exportProject">Export the JET Project</a> to a "Deployable JAR", and place it in a common file system location, and have
+ others reference that location in the Preferences dialog (Preference category <b>EMFT JET Transforms</b>.</li>
+ <li> Use the <a href="../references/extensionpoints/org_eclipse_jet_deployedTransforms.html">org.eclipse.jet.deployedTransforms</a>
+ extension point to share an exported JET Project via a standard Eclipse plug-in.</li>
+ <li> Include the JET Project in an Eclipse Feature. (JET Projects are Eclipse plug-ins.)</li>
+</ul>
+The latter two options require some knowledge of the Eclipse Plug-in Development Environment (PDE).
+</p>
+<h3>Exporting a JET Project a Deployable JAR</h3>
+<p>
+Creating deployable JET transforms makes use of the Eclipse PDE Deployable plug-ins export wizard:
+<ul>
+ <li> Right-click over the JET project, and choose <b>Export...</b>. </li>
+ <li> Select <b>Plug-in Development -&gt; Deployable plug-ins and fragments</b>, and click <b>Next</b>. </li>
+ <li> Click <b>Browse...</b> to select the directory to contain the exported JAR file.</li>
+ <li> Click <b>Finish</b>.</li>
+</ul>
+The JAR file will be exported to a subdirectory called <code>plugins</code>. The JAR file itself will be of the form:
+<br/><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<code><i>id</i>_<i>version</i>.jar</code>.
+</body>
+</html>
diff --git a/doc/org.eclipse.jet.doc/gettingStarted/essentialXPath.xhtml b/doc/org.eclipse.jet.doc/gettingStarted/essentialXPath.xhtml
new file mode 100644
index 0000000..14060cd
--- /dev/null
+++ b/doc/org.eclipse.jet.doc/gettingStarted/essentialXPath.xhtml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
+<title>Essential XPath</title>
+</head>
+<body>
+<h2>Essential XPath</h2>
+<p>
+JET implements the <a href="http://www.w3.org/TR/xpath">W3C XPath 1.0 Specification</a>, with a few minor exceptions.
+Although the XPath language is rich, there are only a small part of the XPath language that is required to use most
+JET tags.
+</p>
+<p>XPath (and JET) assumes that it is working on a model that has a tree structure. While this
+certainly include XML documents (the X in XPath), it can include many other kinds of models as well. Out of the box,
+JET supports XML documents and any model that is represented by EMF.
+(See <a href="http://www.eclipse.org/emf">Eclipse Modeling Framework</a>).
+</p>
+<p>A major element of XPath is the <b>path expression</b>. These are similar to file system paths.
+<ul>
+ <li> An path is a series of <b>steps</b> separated by forward slashes (/).</li>
+ <li> The steps are evaluated from left to right, and generally decend the model's tree as they do so. </li>
+ <li> Each step generally identifies tree nodes by their name (although other possibilities exist).</li>
+ <li> Steps may have an optional filter condition which is written in square brackets ([ and ]) at the end of the step.</li>
+ <li> An initial slash (/) indicates an expression starts at the root of the model tree.</li>
+ <li> Path expressions can also start with a variable, which is a name preceded by a dollar sign ($).
+</ul>
+</p>
+<p>XPath also supports general mathematical, boolean and comparison expressions as well as function calls.</p>
+<p>JET tags that use XPath expressions have common characteristics:
+<ul>
+ <li>Variables are defined by several JET tags - look for a <code>var</code> attribute. They may also be defined by
+ the <code><a href="../taglibs/controlTags/setVariableTag.html">c:setVariable</a></code> tag.</li>
+ <li> JET tags requiring a path expresion have a <code>select</code> attribute.</li>
+ <li> JET tags requiring a boolean expression have a <code>test</code>.</li>
+ <li> Any tag attribute may include a dynamic XPath expression - an XPath expression surrounded by braces ({ and }).</li>
+</ul>
+</p>
+<p>The following tutorials provide a quick introduction to XPath expressions. The first tutorial allows you to
+type expressions, and see their results!
+<ul>
+ <li> <a href="http://www.zvon.org/xxl/XPathTutorial/General/examples.html">http://www.zvon.org/xxl/XPathTutorial/General/examples.html</a> </li>
+ <li> <a href="http://www.w3schools.com/xpath/xpath_intro.asp">http://www.w3schools.com/xpath/xpath_intro.asp</a> </li>
+</ul>
+
+</p>
+</body>
+</html>
diff --git a/doc/org.eclipse.jet.doc/gettingStarted/index.xhtml b/doc/org.eclipse.jet.doc/gettingStarted/index.xhtml
new file mode 100644
index 0000000..c245fbe
--- /dev/null
+++ b/doc/org.eclipse.jet.doc/gettingStarted/index.xhtml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
+<title>Getting Started</title>
+</head>
+<body>
+<h2>Getting Started</h2>
+<p>JET is a tool for generating one or more files from a model using <b>templates</b>. Templates are a mixture of
+text and JET commands (know as <b>tags</b>). The tags extract information from a model, and place it into the expanded
+template. JET then writes the expanded template to the Eclipse workspace. A collection of JET templates is called a
+<b>transform</b>. Each transform is created as a separate JET project.</p>
+<p>You can start learning JET by <a href="newProject.xhtml">creating a JET project</a>,
+understanding the <a href="transformStructure.xhtml">structure of a JET project</a>
+and learning the <a href="commonTags.xhtml">most common JET tags</a>.
+JET transforms extract information from an input model via XPath expressions. You can learn the basics of XPath
+by reading <a href="essentialXpath.xhtml">Essential XPath</a> </p>
+<p>In order to test your JET transform, see <a href="runningTransforms.xhtml">Running JET Transforms</a></p>
+<p>Once completed, you can share your transform with others. See <a href="deployingTransforms.xhtml">Deploying Transforms</a>.</p>
+</body>
+</html>
diff --git a/doc/org.eclipse.jet.doc/gettingStarted/newProject.xhtml b/doc/org.eclipse.jet.doc/gettingStarted/newProject.xhtml
new file mode 100644
index 0000000..b03f8db
--- /dev/null
+++ b/doc/org.eclipse.jet.doc/gettingStarted/newProject.xhtml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
+<title>Create a JET Project</title>
+</head>
+<body>
+<h2>Create a JET Project</h2>
+<p>JET Transforms are created with a New Project Wizard.
+<ul>
+<li>From the menu, choose <b>File -&gt; New -&gt; Project...</b></li>
+<li>Choose the wizard <b>EMFT JET Transforms -&gt; EMFT JET Transform Project</b></li>
+<li>Click <b>Next</b></li>
+<li>Supply a project name. The name should be a letter follows by letters, numbers, hyphens and dots.</li>
+<li>Click <b>Finish</b></li>
+</ul>
+</p>
+<p>To learn more about the newly created project, see <a href="transformStructure.xhtml">JET Transform Structure</a>.</p>
+<p>To run the new transform, see <a href="runningTransforms.xhtml">Run a JET Transform</a>.</p>
+</body>
+</html> \ No newline at end of file
diff --git a/doc/org.eclipse.jet.doc/gettingStarted/runningTransforms.xhtml b/doc/org.eclipse.jet.doc/gettingStarted/runningTransforms.xhtml
new file mode 100644
index 0000000..8636d6b
--- /dev/null
+++ b/doc/org.eclipse.jet.doc/gettingStarted/runningTransforms.xhtml
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
+<title>Run a JET Transform</title>
+</head>
+<body>
+<h2>Run a JET Transform</h2>
+<p>JET Transforms can be run via the Eclipse Run menue:
+<ul>
+ <li> Select <b>Run -&gt; Run...</b> from the menu. </li>
+ <li> Provide a name for the configuration (so you can re-run it quickly). </li>
+ <li> Select the <b>JET Transform</b> category, and then click 'New' button. </li>
+ <li> Browse for the input file, and select the desired transform from the <b>ID</b> drop down.</li>
+ <li> Click <b>Run</b>.</li>
+</ul>
+The transform will execute, and produce some output in a console view.
+</p>
+<p>For XML documents in a transform project, there is a launch short cut that lets you configure a JET transform quickly:
+<ul>
+ <li> Right click over the document, and choose <b>Run As-&gt;Input for JET Transform</b> </li>
+</ul>
+This will create a run configuration (if necessary), and then launch it.
+</p>
+</body>
+</html>
diff --git a/doc/org.eclipse.jet.doc/gettingStarted/transformStructure.xhtml b/doc/org.eclipse.jet.doc/gettingStarted/transformStructure.xhtml
new file mode 100644
index 0000000..077ce94
--- /dev/null
+++ b/doc/org.eclipse.jet.doc/gettingStarted/transformStructure.xhtml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
+<title>JET Transform Project Structure</title>
+</head>
+<body>
+<h2>JET Transform Project Structure</h2>
+<p>The new transform includes two templates, in a directory called <code>templates</code>:
+<ul>
+ <li> <code>main.jet</code> - which serves an entry point to the transform, and generally invokes one
+ or more templates that write content.</li>
+ <li> <code>dump.jet</code> - which merely writes the input model to a file <code>dump.xml</code> in the
+ JET project's root. The dump.jet template is invoked by <code>main.jet</code>.</li>
+</ul>
+</p>
+<p>Other files found in the project are:
+<ul>
+ <li> <code>META-INF/MANIFEST.MF</code> - the project 'manifest', which declares unique identifier of the
+ transform (which, by default, is the project name, too). </li>
+ <li> <code>build.properties</code> - a text file that defines information for correctly building a
+ distributable version of the transform.</li>
+ <li> <code>plugin.xml</code> - a supplement to MANIFEST.MF, which declares additional information about the
+ transform.</li>
+ <li> <code>sample.xml</code> - an XML document that can be used as test input to the transform.</li>
+</ul>
+</p>
+<p>JET Templates are automatically compiled into Java classes. By default, these are hidden from view by
+a Package Explorer filter.</p>
+</body>
+</html>
diff --git a/doc/org.eclipse.jet.doc/toc.xml b/doc/org.eclipse.jet.doc/toc.xml
index ceb9c14..6192db3 100644
--- a/doc/org.eclipse.jet.doc/toc.xml
+++ b/doc/org.eclipse.jet.doc/toc.xml
@@ -5,8 +5,14 @@
<topic label="What's New">
<anchor id="whatsnew"/>
</topic>
- <topic label="Getting Started">
+ <topic label="Getting Started" href="gettingStarted/index.xhtml">
<anchor id="gettingstarted"/>
+ <topic label="Create a JET Project" href="gettingStarted/newProject.xhtml"/>
+ <topic label="JET Transform Structure" href="gettingStarted/transformStructure.xhtml"/>
+ <topic label="Common JET Tags" href="gettingStarted/commonTags.xhtml"/>
+ <topic label="Essential XPath" href="gettingStarted/essentialXPath.xhtml"/>
+ <topic label="Run a JET Transforms" href="gettingStarted/runningTransforms.xhtml"/>
+ <topic label="Deploy a JET Transforms" href="gettingStarted/deployingTransforms.xhtml"/>
</topic>
<topic label="Concepts">
<anchor id="concepts"/>