Building on XoWiki
You have a working installation of OpenACS running. You installed packages such as XoTcl-Core and XoWiki successfully. Now youâd like to extend on XoWiki with your own OpenACS application.
Hereâs a short summary of what to do in order to get started building on XoWiki.
What I cover here: (1) Creating a new package (2) Setting up dependencies and provides (3) The parameter page (4) Prototype Pages (5) Templates All relevant files are also available via github at:Â https://github.com/michaelfeurstein/xowiki-sample-app.gitÂ
Step (1): Create a new package
Go to ACS Site-Wide Administration and itâs Package Manager. At the bottom you can Create a new package
Choose a short readable package key and name. Choose to inherit from templates in order extend on XoWiki. You specifically donât want to implement subsite semantics (just on a sidenote). Everything else is up to you.
If everything went accordingly, youâll get a screen listing all the details for your new package.
Next to other packages you will now have a dedicated package in your packages folder of your openacs distribution:
(2) Setup Dependencies and Provides
We want to extend on XoWiki, therefore we need to somehow specify that somewhere. On the summary page of your newly created package scroll down and click Dependencies and Provides
Click âAdd a service extended by this packageâ and select XoWiki.
After setting up the extension you will now be able to build on XoWiki. What does this mean. Basically two things:
Reusability & Extendibility: By extending XoWiki you will benefit from all features already present within the XoWiki package, thus reusing XoWiki technology. On top of that you can extend functionality in order to customize your XoWiki based application or build new features which are not present in XoWiki.
(3) Parameter Page
When looking at the parameter page, you will now be able to use parameters based on the XoWiki application and you can define separate parameters for specifically for your package:
In order to setup custom parameters, go to ACS Site-Wide Administration / Package Manager and click on the name of your package (Xowiki Sample Application). There, you can click on Parameters under the Manage headline:
Simply click âAdd new parameterâ to specify details for your parameter.
This will result in an entry on the parameter page of XoWiki Sample Application
You can access this parameter via the XoWiki procedure called get_parameter
An example would be
set title [$package_id get_parameter PackageTitle [$package_id instance_name]]
(4) Prototype Pages
Read up on Prototype Pages in the official XoWiki Documentation
Create a prototype directory and index.page file in your XoWiki Sample Application folder (xowiki-sample-app/www/prototypes/index.page). It should contain the following basic setup to get started:
You basically define a starting point for your wiki. A simple index page. If you delete it, it will be created automatically from the prototype defined in your XoWiki Sample Application. The convenience here, is that you can define your own custom index page with your package - this might come in handy when deploying your application and providing a starting point. You can edit this page with your wiki and customize it to your likes.Â
(5) Templates
Templates are based on ACS-Templating. The documentation can be found here.Â
To get started simply copy the structure from your xowiki folder over to your xowiki-sample-app. You need a template folder located in resources: /xowiki-sample-app/resources/template. Now copy over view-default.adp from xowiki into your empty templates folder. In order to demonstrate functionality remove the title in the template and name the file view-example.adp
Note that I only changed things around at the adp placeholders. The top stuff concerns xowikiâs menu structure, which you can also customize in this case. For example to include or hide additional links for users.
Now all you need to do is specify that you are using view-example.adp as your template file in the parameter page of your sample application. (Default Setting: view-default)
When refreshing your index page from the sample application the title should be gone. (demonstration wise)
With this setup you can start designing your website based on XoWiki in a separate package (xowiki-sample-app).
If you need a fresh slate to work with you can also issue a pull request from this xowiki-sample-app via github after creating a new OpenACS application.
https://github.com/michaelfeurstein/xowiki-sample-app.git
Thatâs it for this post :-)














