 |
Home | Changes | Index | Search | Go
Introduction
It is probably a little known fact, but the entire SwingLabs.org website is stored in CVS for the swinglabs.dev.java.net project. In the root directory are two different web directories: www and website. The www directory is the standard java.net www directory that makes up the "normal" java.net web page (what you see when you go to http://swinglabs.dev.java.net).
The other directory is the one we are interested in. It creates the WAR file distribution for http://swinglabs.org. While anybody can compile and build the website, access to the physical machine on which deployments are done is restricted.
Below is a primer that should be enough to get anybody started with hacking on the website. The intent is to open the gates here, as it were, so we can get more contributions for documentation, tutorials, code clips, screenshots (oh boy, could I use screenshots), etc. It will also be posted on SwingLabs.org (any takers?) for future generations (or the wiki, I don't mind either).
There has been a lot of talk previously about when something should go on the wiki vs. SwingLabs.org vs. the project websites. I want to see all "user" facing documenation on SwingLabs.org. When one of us goes to a JUG or conference, or posts a blog or forum posting (say, on JavaLobby?, slashdot, etc) and need a reference to SwingLabs -- SwingLabs.org is it. So we need to really get this website full and robust.
The complete sources for the SwingLabs.org website reside in the public CVS server for swinglabs.dev.java.net. It is located in the "website" subdirectory. (https://swinglabs.dev.java.net/source/browse/swinglabs/website/)
The website directory contains a complete NetBeans webapp project. For those not using NetBeans, you should be able to easily build the project using the ant build.xml script.
SwingLabs.org contains some (very little, actually) Java source code for modeling the tutorial pages, news items, build artifacts, and the "harvester" (ie: store). These models are subsequently used by JSPs to generate the appropriate HTML output. There is one Servlet (StoreDownload?), all other dynamic content is driven by JSPs.
We use JSPs to build all the boilerplate around what is otherwise a normal HTML file (except for tutorials, the download page, the news page, and the store). We use JSP includes to achieve our template effect.
Oh, and of course swinglabs.css is used for both visual state (colors etc) and positioning. However, CSS positioning is a pain (IMO), so there are times I revert to good ole HTML tables. Oh well.
Basics
Here is an example of the simplest JSP. This JSP get's all the SwingLabs colors, background, title area, footer, etc:
<%@page contentType="text/html"%>
<%@page pageEncoding="UTF-8"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>SwingLabs Demos</title>
<link rel="stylesheet" type="text/css" href="swinglabs.css" />
</head>
<body>
<div id="container">
<div id="stitch-hack">
<jsp:include page="includes/header.jsp" />
<div id="content">
<div class="section">
<h3>Hello!</h3>
</div>
</div>
<jsp:include page="includes/footer.jsp" />
</div>
</div>
</body>
</html>
Notice that we are using the XHTML doctype declaration. Please do your best to ensure that each page validates as XHTML (I'm not saying they all do right now, but that's the general goal). I'd love to see Flying Saucer (http://xhtmlrenderer.dev.java.net) viewing the SwingLabs.org website 
Everything else in this document is boilerplate, except for the <div class="section"> element. "section" is a special class that, when used with the swinglabs.css file, get's a consistent look to different logical sections in the document.
Tutorials
Tutorials have a special XML format that is used. This is open for discussion (docbook or some such was suggested earlier, and I would love to see a prototype of this approach).
Here is the basic shell:
<?xml version="1.0" encoding="UTF-8"?>
<tutorial>
<title>JXLoginPane Tutorial</title>
<intro><![CDATA[
<p>This tutorial shows how to use the JXLoginPane and the
...
APIs.</p>]]>
</intro>
<steps>
<step>
<title>Quick JDBC Example</title>
<contents><![CDATA[
<p>Let's jump into our first example: connecting to a
JDBC Database. For this example, I'm
...
]]></contents>
</step>
<step>
<title>JXLoginPane Overview</title>
<contents><![CDATA[
...
]]></contents>
</step>
</steps>
</tutorial>
This file format is very basic. The /tutorial.jsp JSP will take this XML file, parse it into some beans, and then construct the proper HTML page. Alternatively, we could discuss using docbook or some other format, and then translating the XML into HTML via XSLT at runtime. I don't have time to work on this problem, but would be very interested in seeing a solution to this.
News Items
News items are shown on the SwingLabs.org front page. For a while it was Aerith, now it's about Painters. We need lots of news items! And we need to cycle through them regularly. I haven't written an news-archive.jsp file yet, but one needs to be written.
News items are defined in much the same way as tutorials. A news item is essentially:
<?xml version="1.0" encoding="UTF-8"?>
<news>
<title>Painters</title>
<subtitle>SwingX Painters</subtitle>
<date>10-25-2006</date>
<intro><![CDATA[
<p>The SwingX project has been exploring the use
...
</p>]]></intro>
<download>http://swingx.dev.java.net</download>
<more>http://forums.java.net/jive/forum.jspa?forumID=73</more>
<photo>/news/oct-25-2006/images/painterdemo.small.png</photo>
</news>
Code Clips
This is a new category (actually, I've had code-snippets in there for a while, but now they are a top level "type"). These are still really rough, and haven't really been implemented fully, but the idea is simple. I want a repository of cut-copy-paste code snippets. I'd like a simple web service for it as well, such that IDE modules could be written to take these code snippets and make them available in the IDE. They could do anything, from connecting to a JDBC driver to specialized painting code.
Lay of the Land
Now that I've talked about some of the pieces going into the website, I want to also give a description of the organization of the website itself. I think it makes good sense, but if you disagree, let me know!
/index.jsp
This is the main page, referred to as "Home" in the title bar
/faq.jsp
The FAQ page, also on the title bar
/projects.jsp
A page describing in more detail the SwingLabs projects. Most of the SwingLabs projects are missing -- not because I want to omit them, but because I haven't found the time to update the page with descriptions of all the sub projects. There is a huge opportunity here to contribute!
/screenshots.jsp
This page seriously needs to be reworked. Simply, one big HTML page with screenshots. We may want to instead let it be a main page and partition different types of screenshots (app shots, component shots, painter shots) into different sub pages. The images for this page is in the /screenshots directory
/downloads.jsp
The downloads page. I need a downloads-archive.jsp where old builds can be put. Right now, we just list all the downloads available. Cruise control creates these builds each week. In theory, a cron job moves those builds to a download area on Java.net and updates the /posted.txt file in the website. The downloads JSP then creates the page dynamically based on this file. Last week when things were hosed with this page, the posted.txt file was hosed. Once that was straitened out, no problem. You'll notice that posted.txt is out of date (the one in CVS). The cron job that runs monthly should also, perhaps, update CVS with the current posted.txt.
/demos.jsp
Also needs a LOT of work. Demo's are really where we shine as a community, but our page stinks. We need screenshots, descriptions, web start links, and maybe applets. I'd like to see a lot of the small demo's contributed by the community also posted here (with permission, of course). Help!
/contact.jsp
The "Contact Us" page. Needs work (have I mentioned that?), but pretty simple to grok.
/documentation.jsp
This page contains links to blogs, articles, tutorials, and general documentation for SwingLabs components and/or Swing and programming in general. I want it to be a complete one-stop page for people who are programming Swing. Hence, not just about the toolkit, but about general problems with programming rich client applications. I have a more recent rev of this in CVS now than what is on the website, I'll update the website tomorrow with the latest
Documentation is big enough to warrant an additional breakdown.
/docs/code-clips
This directory contains an index.jsp file that points to various code clips. The servlet that is written (!!) to expose code clips as a web service will also be in this directory (http://swinglabs.org/docs/code-clips/ws). Probably most of the clips won't actually be in this directory, they are just pointed to from here.
/docs/components
The /docs/components directory contains additional directories, one for each component in SwingLabs. Within these sub directories are tutorial files, index files, screenshots, etc as make sense. These are intended to be visual or non-visual components, but not frameworks. That is, the action framework, highlighter systems, filters, painters, etc belong elsewhere. In fact, they belong in:
/docs/frameworks
Withing the /docs/frameworks directory is a sub directory for each "framework" documented within SwingLabs. For example, there is a "painters" sub directory. Put code clips, screenshots, tutorials, etc within these sub directories.
/docs/ide
This directory is for putting IDE specific documentation. Right now we only have NetBeans represented (and it's out of date). I'd like to see Ecilpse and IntelliJ? also represented here.
/docs/project
General project documentation. This directory is where this "Hacking on SwingLabs.org" document will go (or at least be referenced from, towards the wiki).
|