Lenya fonts/colours/formats

Are all controlled by CSS, of course. The CSS for the test publication is in
publication-root/resources/shared/css/page.css

You can muck around with formats in here and they will be picked up straightaway... by default there is quite an extensive set of styles defined e.g. breadcrumbs etc. E.g. I just changed the background-color of the body tag and it's picked up immediately...

The page header for your predefined page style is in publication-root/xslt/page2xhtml.xsl - just update the relevant elements in here and you have changed the header. Once again, these changes are picked up straightaway - so they are not subject to the edit/review process (makes sense really).
I just grabbed the image from the Jeannot site and pulled it into the page template - works fine, although it throws out the formatting a bit, but that's to be expected as the default publication isn't designed to have an 800x200 pixel banner at the top... so I tried shrinking it to half size in the template file IMG tag - and that works no problem...

Lenya Publications

The default Lenya installation has a Default publication. To create a new test publication to play with, it is as simple as copying the directory structure from $TOMCAT/webapps/lenya/lenya/pubs/default to $TOMCAT/webapps/lenya/lenya/pubs/your-test-publication-name.
This will automatically be picked up by the running Lenya code and you should see another instance of the Default Publication appear in the window at http://localhost:8080/lenya - look inside the new directory you created.
First thing to notice is publication.xml - this contains various useful nodes like
lenya:name - the name which will appear on the main navigation bar
and other stuff.

Now you can get going with authoring this new publication - like on a Wiki - log in with appropriate authorization and you can create/amend pages. NB: using the Kupu editor - be careful of using the Browser Back button, it seems to cause problems... Be generally careful of hitting F5 - I haven't quite worked out how Refresh is handled - I thought I'd lost some content but then it came back...

Publication also needs figuring out - and I don't know how to delete pages - although pages I haven't updated seem to have disappeared from the menubar ???:(

Lenya Workflow

OK so having played around with editing a document, next thing to do is to Publish it.
As the document author/editor, you use Workflow->Submit to submit the added/amended document for review by a reviewer. Then you have to logout (File->Logout) and login as a user with reviewer authority (by default there is a user "alice" pw="levi" who is defined as a reviewer. The reviewer then reviews the document, then Workflow->Publish to push it to the live site (or Workflow->Reject) to push it back to the author. Note that, in the case of new documents, you may need to publish or republish the parent document, which involves Submitting then Publishing it (you can't just do Publish on the parent document, it won't work, presumably coz the parent needs to be in the publication workflow first...). If something goes wrong on live, you can do Tools->Rollback to go back to a previous version, which are all stored on the site. Hmm - I can't find the Tools menu though... where is it?

Lenya user management

See the Admin tab to view/update users. Predefined groups are admin, editor and reviewer. I assume these roles are used programmatically to determine what a user can do...

Now the hard work begins. Need to figure out in depth how this CMS would work. How to define document templates to allow a content-driven site with a consistent look and feel... etc.

Lenya editors progress

Bitflux, as far as I can make out, only works with Mozilla, which I don't have and can't be bothered with for now! IE is based on Mosaic however, so that should work - and it does, but I had the release 1.1 Beta version downloaded, which doesn't appear to have the Lenya hooks in it. However the 1.0.3 version works fine.

Lenya editors

You have a choice of the following: HTML Forms, Bitflux and One Form.
According to the docs, HTML Forms "is a good choice for users of Mosaic", Bitflux "is a good choice for users of Mozilla" and One Form is for "the power user who needs all the control".

The Edit menu actually gives me 4 options: Kupu, BXE (which is Bitflux), "Forms" and "one Form".

Here are my initial reactions to them (I am using IE6):

• Kupu:
  Wasn't initially installed. You have to get it from here, and it's only available as a tgz file (but WinZip can handle that!). So I did, but I got an error straight away: "Unable to get transformer handler for file:/C:/jakarta-tomcat-5.0.25/webapps/lenya/lenya/resources/kupu/apache-lenya/kupumacros-xhtml.xsl". So maybe I'll come back to this one... Maybe I have to restart Tomcat, I haven't tried that yet.
  



• BXE/Bitflux:
  I got a similar message as for Kupu on trying to invoke this. So now I have to download Bitflux from here. Which I did. Will try to restart Tomcat this time, see if that helps. Well I got a blank page instead of the "Bitflux is not installed" message...
  



• Forms:
  OK let's try "Forms". Hurrah, actually got an editor page rather than an error this time. This one looks quite XML-focused though. Not that great for a non-techie user. It allows you to insert, update and delete XML elements in the document. You have a choice of some predefined elements types like lists and paragraphs, headings and tables.
  



• One Form:
  This one worked as well. It really does just give you the raw XHTML though.
  

Think I will try to get Bitflux (at least) working - as there will be a need for a user-friendly editor... Once you've updated a document you then have to go thru the publishing workflow, but I haven't got that far yet...

Lenya setup from scratch

1. 
   Starting point for Lenya is http://cocoon.apache.org/lenya.
   There are some useful docs but it's pretty sketchy and assumes a lot.
   



2. 
   First you need a JDK - you probably already have one of these! - and Tomcat.
   See http://java.sun.com/j2se/1.4.2/download.html for the JDK, and see http://jakarta.apache.org/tomcat for Tomcat.
   You need to set JAVA_HOME and CATALINA_HOME for these, once installed. Tomcat 5.0.25 is the latest and greatest at the moment. Might need to update your PATH as well to include the new tomcat/bin folder?
   Setting up Tomcat should be fairly easy. This is what I normally do (and I'm getting quite experienced at this!!): Unpack the distribution to /usr/java/tomcat or c:\jakarta-tomcat-5.0.25 if you're on Windows, set the environment variables. Run \bin\startup.bat or ./bin/startup.sh and you should see it start up and then you should be able to see a default page at http://localhost:8080/ . Once Tomcat is working, make sure you've got Ant.
   



3. 
   Now you need the build tool, if you haven't got it already. See http://www.apache.org/dist/ant for this. Download and extract the distribution to (e.g.) c:\apache-ant-1.6.1 . Set ANT_HOME to c:\apache-ant-1.6.1 .
   



4. 
   Next you need Cocoon. Go to http://cocoon.apache.org/ and download the distribution. Unpack it to (e.g.) c:\cocoon-2.1.5 . In the root directory you will find the build script: run it with build.bat or ./build.sh. This can take quite a while as it builds the whole Cocoon framework from scratch. Last time I did it the total build time was 15 minutes.
   



5. 
   When it's finished, start Cocoon as a servlet (command: "cocoon servlet") and try to hit the default URL: http://localhost:8888. A new window will open and report the Cocoon startup process... check that the bits you need are in place. To shut it down use the "shutdown" command. Something I noticed is that there is no JMS server, so if you want to use Java messaging apps, you need to find one... I think you get this listener on port 8888 because it uses Jetty by default - but when we get to the Lenya install we find ourselves back on Tomcat, but we ain't there yet...
   



6. 
   OK that means you've got Cocoon working. But actually you next need to get Lenya itself and recompile Cocoon with the Lenya properties, so it might be worthwhile not compiling Cocoon the first time at all. On the other hand, it's good to know that you've created a working Cocoon installation first, before proceeding...
   



7. 
   For Lenya itself, follow the instructions at http://cocoon.apache.org/lenya/installation/source_version.html. This tells you to do the following.



8. 
   I had some trouble finding the Lenya distribution, so I ended up downloading one of the nightly builds from http://cvs.wyona.org/nightly-builds/. The main distribution directories listed at http://www.apache.org/dyn/closer.cgi/cocoon/lenya/ didn't appear to contain anything when I looked. I found a distribution via Google but on some weird site, so I didn't risk that, so ended up with the nightly build off wyona.org, which seem to be the organization most closely involved with Lenya.
   



9. 
   How to build from the Nightly Build distribution: a) extract the distribution to c:\cocoon-lenya (NB the root folder in the archive is just root, so don't forget to create a directory cocoon-lenya to receive it). Although I can't find any source in the distribution that I've got... but there is a build script, I wonder what that does... Hmm just tried it, it tries to start something on port 8888 which I already have in use with Cocoon. I guess it tries to use Jetty by default. But let me try the Tomcat webapp. I guess I don't need to see the source after all - yet...
   



10. 
    There appears to be a (30 megabyte!) lenya.war file in the distribution - haven't tried it yet but I guess that means you run it as a webapp under Tomcat. Does that mean that no other configuration is required?? 2 things: copy the lenya.war to the Tomcat webapps directory, and copy the endorsed libraries to Tomcat/common/endorsed. The endorsed libs are the JARs for Xalan 2.5.0 and Xerces 2.6.1 plus the xml-apis.jar. These appear to be the necessary versions - not sure if it's obligatory to put them in common/endorsed rather than common/lib, or indeed what the difference is... I already had versions of these JARs in my common/endorsed (can't remember which project I added those for... perhaps Hibernate??), but I don't know which are newer. Hope I don't screw up my Hibernate config...
    



11. 
    So - having put the lenya.war into the Tomcat directory, it just worked out of the box. Does that mean that all the stuff I did before, building Cocoon etc., wasn't needed? Sigh... Anyway, I want to have a basic play with Lenya and see what it's all about first... I can see the homepage at http://localhost:8080/lenya - but I feel like defining a new publication, configuring it, etc, will be another matter. Although there are some FAQs/tutorials at http://cocoon.apache.org/lenya/docs/ and in the Cocoon community Wiki at http://wiki.cocoondev.org/Wiki.jsp?page=Lenya. I also still have Cocoon itself running at http://localhost:8888 so I can have a look into that too...
    

Further Struts hints...

• Use cases/user stories. Have they been clarified?



• Now make sure your datamodel is clear first. I.e. down to the table and field level, and associations between tables, one-to-many, etc.



• Once that is clear, you know how many tables you are dealing with. Draw the associations between tables: i.e. which tables have a "has-a" relationship with others. E.g. a "Project" has-a "Task".



• Draw a diagram showing the Model (i.e. all the tables) and the Views (i.e. all the Views which have been requested). Show which Actions result in which Views.

My Struts notes

Time to try and get some of my notes down on paper, before I go and forget it all. I've developed a good understanding of how it all fits together... it's now a case of remembering it.

Here are the notes I've taken as I went along, focusing on the Struts example webapp... rather unstructured. You will notice that it is full of places which don't work as HTML, coz try as I might I couldn't figure out a nice clean way to paste in text which might contain code/XML/HTML fragments without risking it being eaten by the browser...ahem...


Words of Wisdom:

Here are some further things which have become important, if I was starting a project again:

• Start with your Use Cases. Structure the webapp using one Action per use case, OR... one Action per entity, and then have a parameter on the action form for each entity which tells which of the CRUD sub-actions we are doing (CRUD=Create, Retrieve, Update, Delete).



• Extend Actions from a GenericAction class, which will extend the Struts Scaffold BaseAction - allows you to call preProcess(), executeLogic() and postProcess(), and have common pre- and post-processing done only once, rather than in each Action class.



• Predefine all your ActionForms in struts-config.xml, to match up with your database entities (or at least, the ones you want to be able to change from the web-tier). Each property of the database entity should have a property in the ActionForm.



• I used the Hibernate O/R Mapping. It worked quite well. I still need to get to understand all the bits and pieces though. For Configuration, you need a hibernate.cfg.xml, and a DBEntity.cfg.xml for each mapping. Each of these mappings needs to be backed up with a Java class, as a POJO/bean, with getters and setters for each property.



• To handle the fact that - logically - each DBEntity1 instance contains a DBEntity2 instance, you would do something like defining the POJO for DBEntity1 with an instance variable of the DBEntity2 class. Then in the Hibernate config, put a many-to-one element in the DBEntity2 class, pointing it at the key for DBEntity1. The Hibernate docs say fairly clearly how to do this.

Can't think of anything else right now... to be Continued!