The bridge plugin - Part 4

Preparing for release and deployment

In the previous posts I demonstrated:

• How to set up the infrastructure for a data driven Bridge hand collection web site;
• How to create a plugin to support the expansion of macros creating the display; and
• How to create an application to support the user interface

To make the Bridge plugin and associated application available to others, the files need to be packaged and submitted to the repository. The process is well supported by the BuildContrib build script. I struggled whether to package the plugin and the app separate or together. For the time being I will package them together, since the app completely depends on the plugin. If it turns out to be the wrong choice, it is easy enough to split them.

Packaging for release is controlled by the MANIFEST file and supported by the DEPENDENCIES file. The MANIFEST list all files that must be included in the distribution. The DEPENDENCIES file lists the components that the released files depend on. Those components are commonly CPAN modules, but can also be other Foswiki components.

For the Bridge plugin the MANIFEST file contains the documentation for the plugin (Yep, it had to be written), the two perl modules and a default graphic, as well as 6 illustrations for the documentation.

MANIFEST file for BridgePlugin

data/System/BridgePlugin.txt 0644 Documentation page
lib/Foswiki/Plugins/BridgePlugin.pm 0444 Perl module
lib/Foswiki/Plugins/BridgePlugin/Board.pm 0444 Perl module
pub/System/BridgePlugin/bridgeboard.gif 0644 Default gif for board display
... 6 illustrations ...

The DEPENDENCIES file should include CPAN Try::Tiny, if we continue the implementation as described in the second blog. However, Bridge plugin would be the first to introduce the dependency. That is not a good thing. So I replaced the code with

  eval { $result =  $topicObject->get( 'FIELD', $fieldName )->{value} };
  return $result unless @_;

  return  "There is no '$fieldName' field in this topic" ; 

And was left without any dependecies and the DEPENDENCIES file stayed empty.

With the MANIFEST and DEPENDENCIES files in place, the release package is built using build.pl. My make instructions are attached to this posting (makefile). Two things are worth noting. Use the sudo to become the apache user. That avoids nasty surprises with permissions, either whilst installing or afterwards. And you must make sure the FOSWIKI_HOME and FOSWIKI_LIBS environment variables are set at the appropriate times. Otherwise you get "Can't find ..." whatever module.

Once the prod environment is installed, we can test the module again as installed. When all is well, it can be uploaded to the Foswiki repository.

The BridgeApp

Adding the Bridge application is a simple extension of the MANIFEST file.I chose to create a separate page (BridgeApp)for the documentation.

The MANIFEST file is large. The BridgeApp was created in the first blog using the Wiki Workbench Install. That command creates a new web, that includes all wiki and wiki workbench pages. Pages like WebPreferences for the web and TopicView for the wiki workbench. These are all to be included for the deployment of the BridgeApp. Below I just list the ones that are manually created specific to the BridgeApp, plus one example of the graphics attached to the documentation page.

Additions to the MANIFEST file for BridgeApp

data/System/BridgeApp.txt 0644 Documentation page
data/Applications/BridgeApp/BridgeHandsDataForm.txt 0644 Bridge application page
data/Applications/BridgeApp/BridgeHandsDataViewTemplate.txt 0644 Bridge application page
data/Applications/BridgeApp/BridgeHand.txt 0644 Bridge application page
data/Applications/BridgeApp/RenderApplicationDeployer.txt 0644 Bridge application page
data/Applications/BridgeApp/RenderBridgeHandNavigator.txt 0644 Bridge application page
data/Applications/BridgeApp/RenderBridgePracticeWebHomePage.txt 0644 Bridge application page
...
pub/System/BridgeApp/Hand6PlayTab.JPG 0644 Documentation graphics

The DEPENDENCIES file must list the dependency of the BridgePlugin on the WikiWorkbenchContrib.

DEPENDENCIES file for the BridgeApp

Foswiki::Contrib::WikiWorkbenchContrib,>=4.00,perl,Required

With those files in place, the installation proceeds just like a plugin.

Deploying the application

The Wiki Workbench does an excellent job supporting the creation of a new application. All components needed to create your own user interface against a collection of data are provided at the click of a button. But there is only piecemeal support for the deployment of the application in a web where the data will be collected. In the very first blog post, we created a new web (BridgePractice) and edited that web so that the application components were displayed on the desired pages. Would not it be nice if the application had a list of pages that needed to be copied into the data web and then deploy them there as the new web is created.

Well, the BridgeApp includes just such a page and uses the CopyContrib plus some wiki application processing to do just that. The page that implements this magic is the DeploymentList. The pages to be deployed in addition to the default pages created in a new web are listed in a wiki table. In our case there is only one: SeedWebHome that will replace the WebHome in the web used for data collection.

DeploymentList - pages to be deployed

| SeedWebHome | WebHome | stub |

This line instructs the deployment to copy Applications/BridgeApp.SeedWebHome to <new web>.WebHome as a stub. A stub is a Wiki Workbench topic type that is a reference only. In this case the <new web>.WebHome page will be a reference to Applications/BridgeApp.SeedWebHome

The Deploy button is defined in the RenderApplicationDeployer topic function. The function reads the data in the table on the DeploymentList page, formats it as input for the copy function provided by CopyContrib, and then posts it as a html request using a form. The actual command will read:

Copy command for BridgeApp deployment

/bin/copy/Applications/BridgeApp/RenderApplicationDeloyer
  --- with POST data ---
  mode=application
  source=SeedWebHome => BridgeApp [stub]
  template=_default
  onlynew=off
  forcenewrevision=on
  destination=<new web>

And the <new web> will be created with all the functionality required for immediate use. No more manual adjustments, just use the app.

The deployment functionality is packaged with the plugin. There are two additional files included in the MANIFEST and the CopyContrib must be listed in the DEPENDENCIES file.

Additions to the MANIFEST file for application deployment

data/Applications/BridgeApp/DeploymentList.txt 0644 Wiki workbench page
data/Applications/BridgeApp/SeedWebHome.txt 0644 Bridge application page
data/Applications/BridgeApp/RenderApplicationDeployer.txt 0644 Wiki workbench page

Additions to the DEPENDENCIES file for application deployment

Foswiki::Contrib::CopyContrib,>=3.00,perl,Required

There is more to say about the RenderApplicationDeployer page, but that should be the topic of a separate blog post.

That's it for the BridgePlugin and BridgeApp. When you download and install the application and the plugin, you will see there is more functionality than I have described here. I hope you have enjoyed reading about this journey. And you have a better understanding how to create your own wiki applications.

And when you do, I expect you will be able to upload your applications to the Foswiki repository.

• makefile: makefile