Committers,
I have
updated the ctwig docs in line with David's comments and made them
generic. I've not bothered with @version@ et al - in the context of where
ctwig is now it is not really relevant.
The
attached files can be added back - they came from the head not the 20 branch but
it shouldn't matter.
Change
descriptions are:
ctwig-installing.xml : removed references to specific
C2 versions
ctwig-why.xml : removed reference to when I installed
C2
ctwig-gettingstarted.xml - removed references to
specific C2 versions
ctwig-basic01.xml - fixed example source code error
where xml details not correct
Regards
Jeremy
-----Original Message-----
From: Jeremy Aston [mailto:[EMAIL PROTECTED]]
Sent: 21 November 2001 16:14
To: [EMAIL PROTECTED]; [EMAIL PROTECTED]
Subject: Re: Assistance with tidy of Ctwig docsHi David,
Absolutely. Are there any meta tags that can be used to indicate current version? If not I will change to something more generic.
As far as the differences go, I think another individual made some minor changes (can't find the mail at the mo). I will check, diff and update in the next day or so.
Regards
Jeremy
David Crossley <[EMAIL PROTECTED]> wrote:
Jeremy Aston wrote:
>
> Cool
> I had said to Stefano that I would pick that up. Was going to do it in the
next day or so but saved me a job! Anything else a new bod could do (new to
c2 mods not coding that is)?
> cheers
> jez
Actually Jeremy, there is something very important that you
would be ideal to help with. There are a lot of mentions in ctwig
about specific version numbers of releases (e.g. 2.0rc2) hardcoded.
These need to be fixed, as the documentation should only discuss
the current release. We really should only mention specific version
numbers when absolutely neccessary, and then be prepared to
change such mentions.
Also, i notice that the head branch and cocoon_20_branch have
differences between the ctwig docs.
regards, David
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
Do You Yahoo!?
Get personalised at My Yahoo!.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
<document>
<header>
<title>cTwIG - Cocoon Two Idiots Guide - Installing</title>
<authors>
<person name="Jeremy Aston" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Installing Cocoon 2">
<s2 title="Introduction">
<p>Installing C2 is not a complete nightmare. I found that following the instructions in the documentation worked just fine. The only issue here is that by following the instructions you end up with a WAR file and this is no good for development because you cannot add your own code or make changes to existing files without repackaging it all up.</p>
<p>To get around these problems you need to install it as an unpacked application and get your servlet engine to recognise it as such.</p>
<p>Please note the assumptions about platform, user knowledge and existing applications in the <link href="ctwig-why.html">Why?</link> section and also note thatw herever {TOMCAT_HOME}, {COCOON_HOME} or {APACHE_HOME} appears it should be replaced with the path it is installed into on your machine (e.g. d:\java\cocoon for {COCOON_HOME}).</p>
<p><strong>I'm really sorry, but at the moment these examples relate to the latest distribution, Tomcat 3.2.3 and Apache 1.3.19 on Windows 2000.</strong> It is probably all the same for any operating system (remember, that is the promise of Java and XML). I would like to do TC4/Unix notes but do not have the time at the momement. If you can help then please <link href="ctwig-contributing.html">contribute</link>.</p>
</s2>
<s2 title="Download Cocoon 2">
<p>The latest distribution for any operating system can be found in the <fork href="http://xml.apache.org/cocoon2/dist/";>Cocoon 2 distribution folder</fork>. This file contains the Cocoon code, samples, documentation and the Java libraries that enable the Cocoon to work such as Xerces and Xalan. When you have downloaded it then extract it to somewhere. This path becomes your {COCOON_HOME}.</p>
</s2>
<s2 title="Basic Configuration">
<p>Follow the instructions on building C2 as per the installation guide that comes with C2. It can also be found <fork href="http://xml.apache.org/cocoon2/install.html";>here</fork> as well. Obviously since you have got the ZIP distribution you do not have to do the CVS bit thus you can start at the Building Apache Cocoon 2 section. Do each of the following steps:</p>
<ul>
<li>Set JAVA_HOME</li>
<li>Create the WAR using
<code>.\build.bat -Dinclude.webapp.libs=yes webapp</code>
What this does is to create the web application and packaged cocoon.war under the {COCOON_HOME}/build/cocoon folder.
</li>
<li>Optionally make the SQL examples work out of the box. If you perform this step using
<code>.\build.bat -Dinclude.webapp.libs=yes -Dinstall.war={{TOMCAT_HOME}\webapps} install</code>
then it will basically copy the cocoon.war file across to the Tomcat webapps folder ready for immediate use.
</li>
<li>Add any additional components (I like FOP for example)</li>
</ul>
<p>Next, copy the xerces_xxx.jar to {TOMCAT_HOME}\lib, delete the tomcat jaxp jar and rename the parser.jar as instructuted.</p>
<p>An important point is that if you are running Tomcat as an NT service then you will need to change {TOMCAT_HOME}\conf\wrapper.properties to reflect the classpath changes. Make sure xerces is first in line, remove (or comment out) the jaxp and rename the parser.jar reference. This is all done with the wrapper.class_path bit.</p>
<p>If you did run the second build.bat command above or if you copy cocoon.war into {TOMCAT_HOME}\webapps then you can check that C2 is working. Restart Tomcat and http://localhost:8080/cocoon should work. Note at this point Apache is doing nowt - Tomcat is doing the http serving. If there are any problems then check that the tomcat classpath in wrapper.properties is correct and you have done the work in {TOMCAT_HOME}\lib as descibed above.</p>
<p>One other situation that came to light in C2 RC1 (as opposed to RC1a) was that the build file was including a reference to the LDAP transformer classes and since the JAR is not included then you would see an error when starting C2 along the lines of:</p>
<p>org.apache.cocoon.ProcessingException: Exception in Handler: org.apache.avalon.framework.component.ComponentException: Could not set up Component for hint: org\apache\cocoon\www\sitemap_xmap</p>
<p>This was resolved in C2 RC1a by making changing the offending include line in build.xml. Have a look and see. You will need to change this line if you want to use the LDAP transformer as per the instructions in the build.xml file.</p>
<p>One other good point about testing, especially if you are upgrading, is to delete the Cocoon working files in {TOMCAT_HOME}\work. If left in between upgrades, you can easily get precompiled code sent instead of the new pages being compiled and served.</p>
</s2>
<s2 title="Configure C2 to run in Unpackaged Mode">
<p>To enable you to easily develop your own C2 applications and configure C2 it must sit as an unpackaged application rather than as a packaged WAR file. To make this happen...</p>
<p>Stop Tomcat</p>
<p>Delete {TOMCAT_HOME}\webapps\cocoon.war.</p>
<p>Create {TOMCAT_HOME}\webapps\cocoon folder. If you performed the test above using the war then this folder will already exist and you can skip the next instruction.</p>
<p>Copy {COCOON_HOME}\build\cocoon\webapp\* to {TOMCAT_HOME}\webapps\cocoon</p>
<p>Restart tomcat and try http://localhost:8080/cocoon. The welcome page should come up!</p>
</s2>
<s2 title="Telling Apache about Cocoon">
<p>Note this assumes that mod_jk has been installed and configured.</p>
<p>Stop Apache and Tomcat</p>
<p>Make sure that {APACHE_HOME}\conf\httpd.conf has the following lines (assuming you are using the ajp12 adaptor) at the end:</p>
<source><![CDATA[
include "{TOMCAT_HOME}\conf\mod_jk.conf-auto"
JkMount /cocoon/* ajp12
]]></source>
<p>The first line includes the an Apache config file that Tomcat automatically generates. This has all the alias directives for each of the contexts in {TOMCAT_HOME}\conf\server.xml. The second line tells anything requested to /cocoon to be sent to Tomcat (and then onwards to Cocoon).</p>
<p>Restart tomcat THEN apache. The reason for this way round is apache relies on the {TOMCAT_HOME}\conf\mod_jk.conf-auto which is built by Tomcat everytime it starts.</p>
<p>You can then try http://localhost/cocoon. It should work!</p>
<p>You are now ready to look at the examples and start doing some <link href="ctwig-transformations.html">basic transformations</link></p>
</s2>
<s2 title="Other Configurations">
<p>I am hoping to include more details on other configurations over time. If you can help then please <link href="ctwig-contributing.html">contribute</link>. You can also check out other information in the <link href="ctwig-resources.html">resources</link> section.</p>
</s2>
</s1>
</body>
</document>
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd"> <document> <header> <title>cTwIG - Cocoon Two Idiots Guide - Why?</title> <authors> <person name="Jeremy Aston" email="[EMAIL PROTECTED]"/> </authors> </header> <body> <s1 title="Why?"> <p>If nothing else these pages form my own personal documentation of how to use C2 from the ground up. I run a team of developers and as much as I encourage them to jump into technology and problem solve themselves, I also want them to know when to ask for help and to do it before they have wasted hours of time banging their heads against brick walls. With a technology that is new to them, which C2 is, these pages can help them get more productive more quickly. I am learning C2 too so I don't want to fall into the same trap.</p> <p>When I installed C2 for the first time I wanted to write down what I did so my team could benefit. In the course of asking questions on the xml-cocoon-users mail list I realised that others were having the same problems and, more importantly, the answers were all there via the generous nature of more experienced list users. To support my team, the wider development community and pay back in kind the support of others I wanted to make my notes available.</p> <p>Given that I am still getting some basic stuff running these pages are going to be like a diary of my work for the first few weeks but I hope that something good comes out of it. If you find ways of doing things better, have your own notes, want to put me right on something or just want to stop it being a one man ego trip then please <link href="ctwig-contributing.html">contribute</link>.</p> <p>As a bit of technical background... I have been working for almost the past five years developing web based e-learning solutions, firstly a learning mangement system (Solstra - <fork href="http://www.solstra.com";>www.solstra.com</fork>), then an e-learning portal (easycando.com - <fork href="http://www.easycando.com";>easycando.com</fork>) and more recently content for <fork href="http://www.knowledgepool.com";>KnowledgePool</fork>. Right from day one, after trying and discarding ASP and Cold Fusion, we saw the need to use templates that could seperate logic from layout. We built our own Java based architecture then moved it from templates to servlets as that technology progressed. By using a property file based system along with classes that abstracted the HTML coding side, we built configurable, multi-lingual solutions. The basic method still contains weaknesses and I was keen to see how XML/XSL could help.</p> <p>About a year ago we developed some prototype code that used JSP, beans, XML and XSL. It worked quite well but then things changed, I moved jobs and did not do anything more other than mull things over in my head. More recently I have had to start architecting tools to help my company develop learning content and I revisited my earlier thoughts. I was reading a "Java and XML" by Brett McLaughlin (published by O'Reilly) and it talked about Cocoon. When I saw the taglib (logicsheet) idea I realised here was a platform I could work with. I tried 1.8 as it was production code and then moved to 2 because I saw the internationalisation capabilities and thought it is probably close to becoming a fully released product.</p> <p>I am now building more and more code and realising that sharing my experiences might help others. At worst it'll be how not to do it!</p> </s1> </body> </document>
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd"> <document> <header> <title>cTwIG - Cocoon Two Idiots Guide - Getting Started</title> <authors> <person name="Jeremy Aston" email="[EMAIL PROTECTED]"/> </authors> </header> <body> <s1 title="Getting Started"> <s2 title="What is Cocoon?"> <p>Cocoon is a framework for delivering web sites and applications that are based around XML technologies. In addition to being able to do XML and XSL transformations, it provides it's own page logic templating system called XSP which is basically analogous to ASP, JSP, PHP, CFM etc. Of course this is XML based as well.</p> </s2> <s2 title="Why use Cocoon?"> <p>For me it's because it really can help you develop applications that have content, layout and logic truly separated. ASP, JSP etc are all OK but for any one (like me) who has had to develop and support multi-lingual, branded, customisable and highly dynamic sites, they just do not cut the mustard. On top of that it is free, supported by proven open source development principles and augments other frameworks and platforms such as EJB.</p> </s2> <s2 title="What do I need to make it work?"> <p>Primarily you need a servlet engine. This would be something like (but not exclusively) <fork href="http://jakarta.apache.org/tomcat/index.html";>Tomcat</fork>, <fork href="http://www.jrun.com";>JRun</fork> or <fork href="http://www.weblogic.com";>Weblogic</fork>. This is because Cocoon is a servlet and needs the servlet engine. Most servlet engines provide a web (HTTP) server which is fine for development purposes but in most production environments you would want to sit the servlet engine on a web server such as <jump href="http://www.apache.org";>Apache</jump> or IIS. The only other usual requirement is the <jump href="http://java.sun.com";>Java SDK</jump>.</p> </s2> <s2 title="Where do I get it from?"> <p>Go to <fork href="http://xml.apache.org/cocoon2/";>http://www.apache.org/cocoon2/</fork> and download it from there. The latest distribution for any operating system can be foung in the <fork href="http://xml.apache.org/cocoon2/dist/";>Cocoon 2 distribution folder</fork>. The distribution that you can download from there contains the Cocoon code, samples, documentation and the Java libraries that enable the Cocoon to work such as Xerces and Xalan.</p> </s2> <s2 title="What assumptions have you made?"> <p>I assume no knowledege of Cocoon but:</p> <ul> <li> I do assume that the reader has a basic understanding of XML and what XSL is. For more information and tutorials about XML/XSL please go to somewhere like <fork href="http://www.xml.org";>www.xml.org</fork> or <fork href="http://www.xml.com";>www.xml.com</fork> </li> <li> I assume that Cocoon is to be configured on a Windows NT or 2000 machine, the machine has Apache 1.3.19, Tomcat 3.2.3 and Java 1.3 running </li> <li> I assume a basic familiarity with the above environment </li> <li> I hope that if you are working on a different environment you will find the time to <link href="ctwig-contributing.html">advise</link> me of any differences in process so I can augment the documentation. I also hope that if you find a mistake in the documentation here or you know of a better way of doing something then again you will <link href="ctwig-contributing.html">relay</link> your thoughts so I can make this resource as useful as possible. </li> </ul> </s2> </s1> </body> </document>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
<document>
<header>
<title>cTwIG - Cocoon Two Idiots Guide - Basic XML/XSL Transformation</title>
<authors>
<person name="Jeremy Aston" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Transformations">
<s2 title="Basic XML/XSL Transformation">
<p>IMHO the most basic thing you will want to do is perform an XSL transformation on an XML file. A typical example of this is to render some XML as an HTML page using an XSL stylesheet.</p>
<p>Take the following XML file (<fork href="sample/transformations/basic01/basic01-01.xml">basic01-01.xml</fork>):</p>
<source><![CDATA[
<?xml version="1.0"?>
<page>
<title>Basic XML/XSL Transformation Example - BASIC01-01.XML</title>
<greeting>Hello World</greeting>
</page>
]]></source>
<p>And use the following XSL to transform it to some HTML (<fork href="sample/transformations/basic01/basic01-01.xsl">basic01-01.xsl</fork>):</p>
<source><![CDATA[
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0">
<xsl:template match="page">
<html>
<head>
<title><xsl:value-of select="title"/></title>
</head>
<body>
<h1><xsl:value-of select="title"/></h1>
<p><xsl:value-of select="greeting"/></p>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
]]></source>
<p>Hopefully the basic XSL makes sense however the key to getting this served is to change setting in the sitemap.xmap file. It is this file that determines what and how gets served. The sitemap is very powerful and can be configured to do some very efficient things, however we will start with slightly longwinded but simple examples so the concepts are there to be built on.</p>
<p>You can add sections into sitemap.xmap file that comes with C2. This has things called "pipelines" already set up. To be able to see the result of transforming the above files together you just need to add the following code into the last "pipeline" section:</p>
<source><![CDATA[
<map:match pattern="ctwig/basic01-01.xml">
<map:generate type="file" src="ctwig/basic01-01.xml"/>
<map:transform type="xslt" src="ctwig/basic01-01.xsl"/>
<map:serialize/>
</map:match>
]]></source>
<p>What this construct does is to tell C2 to do something when it recieves a request for <strong><code>ctwig/basic01-01.xml</code></strong>. The "something" that C2 will do is pass the <strong><code>ctwig/basic01-01.xml</code></strong> file through a "file" generator. This basically parses the XML. The result parsed stream then gets transformed using <strong><code>ctwig/basic01-01.xsl</code></strong> and rendered.</p>
<p>Calling <fork href="http://localhost:8080/cocoon/ctwig/basic01-01.xml";>http://localhost:8080/cocoon/ctwig/basic01-01.xml</fork> will result in a simple HTML page being rendered.</p>
</s2>
<s2 title="Simple Wildcards in the Sitemap File">
<p>The above sitemap map construct works but you can imagine the overhead if we had to add this code for every single XML/XSL transformation we wanted to do. C2 makes things easier by allowing wildcards in the pattern matching argument. If the above section is replaced with the following:</p>
<source><![CDATA[
<map:match pattern="ctwig/*.xml">
<map:generate type="file" src="ctwig/{1}.xml"/>
<map:transform type="xslt" src="ctwig/{1}.xsl"/>
<map:serialize/>
</map:match>
]]></source>
<p>then C2 will substitutue the <strong><code>{1}</code></strong> meta-tag with the whatever is in the wildcard section of the request. This means that is every XML file has a corresponding XSL file with the same filename (before the extension) then requesting the XML file will result in it being served.</p>
<p>This also allows us to do a kind of request re-writing function. Take the following sitemap construct:</p>
<source><![CDATA[
<map:match pattern="ctwig/*.html">
<map:generate type="file" src="ctwig/{1}.xml"/>
<map:transform type="xslt" src="ctwig/{1}.xsl"/>
<map:serialize/>
</map:match>
]]></source>
<p>This allows us to request an HTML file from the ctwig folder. What will actually happen though is that C2 willtake the wildcard portion and use that to look for XML and XSL files with the same filename and use them to generate the response stream contents. For example; <fork href="http://localhost:8080/cocoon/ctwig/basic01-01.html";>http://localhost:8080/cocoon/ctwig/basic01-01.html</fork> will cause C2 to look for <strong><code>ctwig/basic01-01.xml</code></strong> and transform it with <strong><code>ctwig/basic01-01.xsl</code></strong> to produce the final page.</p>
</s2>
<s2 title="Using a Single XSL File">
<p>Consider a scenario where you have multiple XML files which are you wish to transform in a common fashion (for example into HTML). If your XML has been designed well and follows a common DTD there is no reason why one XSL file can transform all the XML files. Many of the C2 examples do this, using one, single, common XSL file for rendering all the examples to HTML and another for transforming them into a source code view. This again is achieved using the sitemap file with a construct similar to the following:</p>
<source><![CDATA[
<map:match pattern="ctwig/*.html">
<map:generate type="file" src="ctwig/{1}.xml"/>
<map:transform type="xslt" src="ctwig/file2html.xsl"/>
<map:serialize/>
</map:match>
]]></source>
<p>Here, a request for an HTML page will look for a corresponding XML file and transform it using <strong><code>ctwig/file2html.xsl</code></strong>.</p>
</s2>
<note>TODO: PROVIDE AN EXAMPLE.</note>
</s1>
</body>
</document>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
