Pages like http://www.jboss.org/gatein/downloads/gateinportal.html or http://www.jboss.org/drools/downloads use a nice "Directory listing" paragraph. This paragraph mirrors a file system and keeps the download pages up-to-date without the actual page to be manually updated. This paragraph was introduced by Jozef Chocholáček, but in the next release (= 7.8.0 Magnolia) several enhancements and fixes were done. The release will go public on Wednesday December 5th at 2:00 PM (CET).
Latest release hightlight
This feature was present in the previous version, but it was completely overhauled. It is backwards compatible thought. You can place a hightlight to the new version of your product between the paragraph title and the directory listing. Originally the highlight text was hard-coded to "Looking for the latest version? Download". Now it is just a default text, but you can change it to whatever you want. Also originally it was possible to higlight just one link, now it is up to you how many of them you want to use.
How to set this up? First of all you need to have a file lastRelease.properties in the root directory of your project. If this file is found, it is not displayed in the paragraph, but its content is parsed and used to set the content of the paragraph instead. Why are those settings in the filesystem and not in the Magnolia paragraph dialog? It is likely the latest versions are generated and deployed by some automatic process. And while it is easy to just copy one more file to some directory, it would be much harder to modify things in a web form automatically.
OK. So we have this lastRelease.properties file. It is a classical property file, where on each line you write a key, "=" character and after it its value. The lastRelease.properties has following keys:
| Key | Description |
|---|---|
| lastRelease | A link to the page with the last release. The URL can be either absolute (in that case no processing is done on it) or relative. If it is relative a base URL is added to the link (in case of JBoss pages it is http://downloads.jboss.org). If this key is missing, the latest release will not be highlighted and just the directory listing will be displayed in the paragraph. |
| lastReleaseText | If ommited, this key defaults to "Looking for the latest version? Download ". If you specify it, your text will be displayed prior to the link on the web page. |
| lastReleaseURLText | While lastRelease specifies the URL to the latest release, the path might not be pretty for human readers. Therefore you can specify a text, that will be displayed in the web browser. If ommited, the paragraph tries to dig some pretty name from the lastRelease value, but the result will not be as nice as if you specify it yourself. |
If you need more links to the latest versions (i.e. your project has several parts and you want to highlight each part), now you can add numbers to the key after the name starting with 0 and increasing by one in the lastRelease.properties file. The paragraph will render all the highlights unless finds a missing number. So if you specify lastRelease0, lastRelease1 and lastRelease3 keys, the first two will be displayed, but lastRelease3 will be ignored, because lastRelease2 is not present.
The keys lastReleaseText and lastReleaseURLText have their numbered variants and of course the number binds all together. However the defaults are slightly different here, because the long texts are not good if used several times:
| Key | Description |
|---|---|
| lastRelease<n> | A link to the page with the last release. If ommited, lastRelease<n+1> and the higher will not be processed. |
| lastReleaseText<n> | The text prior to the link.It defaults to lastReleaseURLText<n> with ": ". If neither lastReleaseURLText<n> is specified, the default value of lastReleaseURLText<n> + ": " is used. |
| lastReleaseURLText<n> | Similar to the unnumbered lastReleaseURLText. |
Example:
lastRelease=http://absolutepath.some.org/dir/subdir
lastReleaseText=Download the newest version here:
lastReleaseURLText=Latest Release
lastRelease0=latest0
lastRelease1=latest1
lastReleaseText1=Latest release 1:
lastRelease2=latest2
lastReleaseText2=Latest release 2:
lastReleaseURLText2=Download
Will render as
What you can not see on the picture are the values of the links. So the first link (under Latest Release) will be as http://absolutepath.some.org/dir/subdir, because the path was absolute and therfore unchanged. The second highlight is not nice, because lastReleaseText0 and lastReleaseURL0 were not specified and latest0: latest0 is the best what the paragraph was able to dig out from it. The URL under latest0 will be http://downloads.jboss.org/latest0, because the link is relative. The remaining two highlights are better, because the values are specified.
Note: the numbered and unnumbered keys are independent. You can use just numbered, just unnumbered or both variants.
Enough about the last release highlights. I need to explain some other new feature before I will be able describe some magic you can do with those highlights.
More directory listing paragraphs on a single web page
The old directory listing paragraph was supposed to be alone on a web page. Also it interfered with another Magnolia paragraph, but it is another story. It was not mentioned anywhere, so some users put several directory listing paragraphs on a single page. When someone navigated within the directory structure displayed in the paragraph, that paragraph displayed the content of the chosen subdirectory (correct), but the other paragraphs reported errors, because they tried to search for the same subdirectory in their part of file system, but they did not have it.
Now the navigation is independent in each paragraph. Originally "dir" attribute was added to the URL of the download page. E.g. http://localhost:8080/exampleformpage.html?dir=java caused the paragraph to render the content of the "java" directory. Now it changed. The dir attribute now holds the identification of the paragraph. I.e. if we have two paragraphs on the single page, the URL might look like http://localhost:8080/author/exampleformpage.html?dir=01%3Ddownloads%3B00%3Djava%3B. The URL says, that in the paragraph 01 downloads subdirectory should be displayed and the paragraph 00 should display the java subdirectory. It looks horrible, but %3D is "=" and %3B is ";". So if you hover your mouse above the link in your browser, you will see something like http://localhost:8080/author/exampleformpage.html?dir=01=downloads;00=java; . I think that makes things clear.
The promised "directory listing magic"
In case you know how the dir parameter works, you may use this knowledge to construct the URL to your "latest release highlight" section. And if I speak about this feature as "latest release", the reason why you have it there may be completely different. I.e. if you have a project with several logical parts - one with a validation, second with a persistence or whatever.
The easiest way how to use it is to find the directory with the content you would like to highlight in the web browser. Copy the link and use it into your lastRelease.properties file. Keep in mind that that way you can set all the directory listing paragraphs of a single page.
Complete list of directoryListing paragraph changes in the new version
(just in the case someone cares).
- fixed crashes when serveral directoryListing paragraphs were on the same page
+ when date is selected as a sorting column, a file name is a secondary column
- fixed a problem with broken colors after sorting in directoryListing paragraph
- removed several possibilities to crash directoryListing paragraph by adding wrong paths
+ if more than just one directoryListing paragraph are present on a page, user can navigate independently in each. The system rembers the position in each paragraph instead of displaying an error
- fixed a problem with expanding of checksums of files, that have the same checksum (a completely different div on the page was expanded)
* newer version of Modeshape library is used
+ added some info about how to use the paragraph into Magnolia form of the paragraph.
- fixed a problem with spaces in the latest release highlight links.
