Products > Mockups > Online Help > Mockups for XWiki Help

Balsamiq Mockups for XWiki Help

Welcome to the online help of Mockups for XWiki

This page contains installation, registration, upgrading and uninstallation instructions for Mockups for XWiki.

The main Balsamiq Mockups help page is here.

Installation Instructions
Registration Instructions
Upgrading Instructions
Creating a New Mockup
Editing a Mockup
Deleting a Mockup
Mockup's History
Rolling Back
Moving a Mockup
Uninstalling Instructions

Installation Instructions

Installing Mockups for XWiki requires administration priviledges and a restart of XWiki.

The process is fairly simple and should take less than 10 minutes.

The following instructions assume you have already installed XWiki 1.2 or later. If that is not the case please go to xwiki.org for instructions on how to download and install XWiki on your computer.

Note: "<xwiki-home>" below denotes your XWiki installation directory, and "xx.yy" stand for the minor version numbers of the file you downloaded.

Download Mockups for Xwiki from here.
Unzip the file you downloaded in a directory of your choice. The zip contains 3 files: a JAR, a XAR and a README.txt file.
Shutdown your XWiki instance with <xwiki-home>/stop_wiki.sh (or stop_wiki.bat)
Copy the mockupsXWiki-1.xx.yy.jar file to <xwiki-home>/webapps/xwiki/WEB-INF/lib/ directory.

Edit <xwiki-home>/webapps/xwiki/WEB-INF/xwiki.cfg to add the following to the xwiki.plugins list:

           com.balsamiq.xwiki.plugins.mockups.MockupsPlugin

Watch the commas and slashes, the list might look like this after you are done:

xwiki.plugins=\
           com.xpn.xwiki.monitor.api.MonitorPlugin,\
           com.xpn.xwiki.plugin.calendar.CalendarPlugin,\
           ...
           com.xpn.xwiki.plugin.watchlist.WatchListPlugin,\
           com.balsamiq.xwiki.plugins.mockups.MockupsPlugin

Edit <xwiki-home>/webapps/xwiki/WEB-INF/hibernate.cfg.xml to include the following in the  section:
```
           <mapping resource="mockups.hbm.xml"/>
```
Edit <xwiki-home>/webapps/xwiki/WEB-INF/struts-config.xml to include the following right before the tag at the end of the file (you'll see a similar tag for the CaptchaServicePlugin):
```
           <plug-in className="com.balsamiq.xwiki.plugins.mockups.struts.MockupsStrutsPlugin"/>
```
Restart your XWiki instance (with <xwiki-home>/start_wiki.sh or <xwiki-home>/start_wiki.bat).
Login as Admin. Go to the Administration panel (Administration / Administrate wiki) and choose Import. Browse to the mockupsXWiki-pages-1.xx.yy.xar file and attach it. Click on the mockupsXWiki-pages-1.xx.yy.xar link and click on the "Import" button to finish the import. You should see a "5 Document(s) installed" message.
Go to the Administration panel and click on the Panel Wizard. Open the "Tools" menu, then drag the Balsamiq Mockups panel to the right column of your layout (we suggest placing it right under the "Create" panel) and click on the "Save the new Layout" button when you are satisfied with the placement.

That's it! You can now start creating UI Mockups on any page page you have edit rights to. The 30-day trial period starts as soon as you install the product. During the trial, anyone with edit rights can add and edit mockups. If you bought a license, look at the Registration Instructions below.

Registration Instructions

During the trial period, anyone with edit rights can add and edit mockups. Once you register your Mockups for XWiki copy, only members of the BalsamiqMockupsEditors group will be able to do so, while everyone else will be able to view mockups but not edit them.

To register your Mockups for XWiki license:

There are two ways to view and edit the licensing page for Mockups for XWiki:
- you can manually go the following URL:
  <yourdomain>/xwiki/bin/view/Mockups/MockupsLicenseInfo
- you can get to the mockups editor as an admin (add or edit a mockup), then select the Help / Licensing Information menu item.
Enter the license information you received via email (make sure you copy and paste, it's case-sensitive), and click on the update button to save it. You will notice the page update with the new information. An invalid license will simply be ignored.
Create the mockups editors group: go to the Administration panel and choose Groups. Click on "Add new group" and create a "BalsamiqMockupsEditors" group (case-sensitive, we suggest you copy and paste the name rather than typing it). Edit the group to add users to it. The number of editors in this group must be less or equal than the number of authorized users in your license.

Upgrading Instructions

Shutdown your xwiki instance with <xwiki-home>/stop_wiki.sh (or stop_wiki.bat)
Delete any mockupsXWiki-*.jar files in your <xwiki-home>/webapps/xwiki/WEB-INF/lib/ directory
Copy the new mockupsXWiki-1.xx.yy.jar file to <xwiki-home>/webapps/xwiki/WEB-INF/lib/ directory.
Restart your XWiki instance (with <xwiki-home>/start_wiki.sh or <xwiki-home>/start_wiki.bat).
Update the plugin's pages. Login as Admin. Go to the Administration panel (Administration / Administrate wiki) and chose Import. Browse to the new mockupsXWiki-pages-1.xx.yy.xar file and attach it. Click on the mockupsXWiki-pages-1.xx.yy.xar link and click on the "Import" button to finish the import. You should see a "5 Document(s) installed" message.

Creating a new mockup

To add a UI mockup to your page simply click on the "Add UI Mockup" button found in the "Balsamiq Mockups" panel:

This will take you directly to the Balsamiq Mockup editor. Once you are happy with your mockup, just select "Save and Close" from the Mockup menu, and you'll be asked to give it a unique ID. This is required and allows you to include more than one mockup on the same page.

Once you name your mockup you'll be taken back to XWiki, with your mockup placed at the top of the page. To move it down to your preferred location, just edit the page, find the #mockup("your_mockup_name") macro definition at the top, cut it, scroll down to where you want your mockup to be and paste. Save the page and you're done!

Editing a mockup

If you have editing rights on the wiki page that contains a mockup, you'll see a "edit this mockup" link right under the mockup image.

Simply click on the link and you'll be taken to the editor. Click "Save and Close" or "Discard changes" to go back to XWiki.

Deleting a mockup

To remove a mockup from a page, simply edit the page, find the appropriate #mockup macro, delete it and save the page again. You might also want to delete the mockup's BMML and PNG attachment files from the page.

Looking at a mockup's history

Each ui mockup is saved as two separate attachments, one for the PNG image and one for the BMML representation of the mockup. XWiki supports versioning of attachments, and Balsamiq Mockups takes advantage of it so that you can see how your mockup evolved over time, or roll back to a previous version.

Rolling back to a previous version of a mockup

This is a bit tricky but it can be done. Go to the attachments view for your page, find the mockup you want to roll back, get the BMML for the version you want to roll it back to and copy it. Now you can go back to the page, edit the mockup and import your old BMML via the "Import" dialog.

Moving a mockup on a page

To move a mockup to a different location on a page you edit the page, find the #mockup("your_mockup_name") macro definition for the mockup you want to move, cut it, scroll down to where you want your mockup to be and paste. Save the page and you're done!

Uninstalling Instructions

Shutdown your xwiki instance with <xwiki-home>/stop_wiki.sh (or stop_wiki.bat)
Delete any mockupsXWiki-*.jar files in your <xwiki-home>/webapps/xwiki/WEB-INF/lib/ directory

Edit <xwiki-home>/webapps/xwiki/WEB-INF/xwiki.cfg and remove this line:

           com.balsamiq.xwiki.plugins.mockups.MockupsPlugin

Watch the commas and slashes, the list might look like this after you are done:

xwiki.plugins=\
           com.xpn.xwiki.monitor.api.MonitorPlugin,\
           com.xpn.xwiki.plugin.calendar.CalendarPlugin,\
           ...
           com.xpn.xwiki.plugin.watchlist.WatchListPlugin

Edit <xwiki-home>/webapps/xwiki/WEB-INF/hibernate.cfg.xml to remove the following in the  section:
```
           <mapping resource="mockups.hbm.xml"/>
```
Edit <xwiki-home>/webapps/xwiki/WEB-INF/struts-config.xml to remove the following right before the tag at the end of the file (you'll see a similar tag for the CaptchaServicePlugin):
```
           <plug-in className="com.balsamiq.xwiki.plugins.mockups.struts.MockupsStrutsPlugin"/>
```
Go to /xwiki/bin/view/Mockups/DeleteMockupsPages and click on the "Delete" button to remove the Mockups for XWiki wiki pages.
(Optional) Delete the BalsamiqMockupsEditors user group from your Administration UI.