Active development of JAMWiki has ceased, and bug fixes and support will be limited at best. If you are interested in taking over management of JAMWiki please send an email to the jamwiki-devel mailing list.

Tech:MagicWord Enhancements supporting YUI Integration

ktip.png This page (and all pages in the Tech: namespace) is a developer discussion about a feature that is either proposed for inclusion in JAMWiki or one that has already been implemented. This page is NOT documentation of JAMWiki functionality - for a list of documentation, see Category:JAMWiki.
Status of this feature: NOT IMPLEMENTED.


There is a desire to use YUI capabilities on JamWiki article pages to allow for more rich, feature full javascript interations with datatables and other YUI capabilities.

At present, YUI Datatables allows a user to modify some value on the page, click 'Save' and have that element be modified directly on the screen. This would be of immense convenience for people needing to make a number of small incremental changes frequently.


The problem is that when attempting to use YUI Datatable to directly modify values on a wiki article page, the save button provided by YUI Databables only modifies the values in the current HTML page, but not the Wiki's source. The resolution to this problem is to directly connect, through Javascript, the Save command to the Special:Edit servlet to allow for the modification to be committed in the article's source. (For more information about how YUI Datatables works, please navigate to their page and review. It will help make things a bit more clear.) This is at present only possible by obtaining certain hidden variables from the Special:Edit servlet for the page in particular.

Currently there are no known methods to expose this information for display on the main article page; as a result, one has to look at the edit servlet output to determine what values are needed to be able to submit to the edit servlet from the article page directly.

Rejected Solutions

One possible method would be to write a Javascript html parser that would screen scrape the Special:Edit page to obtain the hidden variables and their values when the article page is loaded. This is rejected as a solution since screen scraping is a very bad idea in general: it causes additional server load and could potentially become a maintenance headache when and if the Special:Edit servlet page changed.

Another proposed solution was to add hidden input variables on the main article display page itself, allowing for Javascript in the article page to obtain the values from the document object. This was considered merely a quick hack and still required additional Javascript to parse the current page.

Proposed Solution

The proposed modification, provided by Ryan Holliday, is to add a few MagicWords into JamWiki to allow for YUI Datatable integration to happen smoothly and without needlessly screen-scraping the Special:Edit page for the current article to obtain the following hidden variables for the submission:

  • <input type="hidden" name="topic" value="CurrentTopicPage" />
  • <input type="hidden" name="lastTopicVersionId" value="4216" />
  • <input type="hidden" name="section" value="" />
  • <input type="hidden" name="topicVersionId" value="" />

Since MagicWords are simply a form of server side keyword substitution, this is a very elegant solution. If these values were directly available via MagicWords, then a wiki article author could add them directly to the Javascript that is run when the user clicks the 'Save' button provided by YUI Datatable. The MagicWord is substituted for the actual value the author was looking for, and this is all done before the HTML page is rendered by the browser, making this a very convenient method indeed.

Technical Implementation

Ryan suggested that I first check into /jamwiki-core/src/main/java/org/jamwiki/parser/jflex/

I will post additional details as I get started with this project.

I have implemented RevisionID. It was already practically complete. All I needed to do was access the topicRevisionID in the MagicWordUtil class itself. That was trivial, and ready to be committed into svn.

The problem I am currently at is implementing the sectionId. The sectionId is much harder to implement in light of current architecture. The big plan I had to implement this was to be able to use a MagicWord in any topic section and have it resolve the sectionId for the section it happened to be in. The problem is that sectionId is not an intentionally managed value. The sectionId is determined at parse time as the application parses the content, it happens to count the number of ==Section== blocks there are, and increments the value as it finds them while it builds the Edit link.

In order to obtain this sectionId and make it available to the MagicWordUtil class at it processes the MagicWords, I would have to add a field to the Topic class to store the sectionID as the parsing of the page takes place. That seemed the most straightforward way to handle this. The problem is that I'm not entirely sure if that would even work since I don't know if Magic Words get parsed before or after the sectionId's are determined.

While this is not an ideal situation, but I am at present not interested in implementing the sectionId feature completely because I would have to do something fairly radical to accomplish this, I fear.

I also do not technically need this feature to implement the YUI datatable either. I can simply submit the entire page and that will suffice for my purposes at the moment.

Any thoughts or reviews of this analysis is greatly welcome.

This sounds reasonable - I suspected the topicRevisionId changes would be fairly straightforward. For sectionId, there is currently an open bug report that would necessitate making many of the changes needed for the functionality you've outlined, so if/when that gets done we can revisit creating a magic word to expose that variable. -- Ryan • (comments) • 05-Apr-2009 12:13 PDT

Potential Issues

Ryan would prefer that any modifications to the parser be consistent with MediaWiki, and this should be ensured before merging to the trunk. Additionally, any new MagicWords should follow the syntax provided by MediaWiki.



In progress. Please review and feedback is always welcome! -- Shaka 1-Apr-09 6:10 DST