Tuesday, July 1, 2008

How to build a Bookvar addin



In this short post I'll try to give you a brief introduction of how you can build your own addin for Bookvar. We have been receiving some requests to include export to plain text functionality and thus I decided to build a sample addin that does it.

Before I continue I'd like to mention that the following content is mostly for developers. Non-developer folks will understand very little of it and may not find it interesting. However, you can scroll directly to the bottom of the post. There, you will find a link from which you can download the addin and also instructions for deployment.




Before you start building your magnificent addin you need to have a couple of prerequisites installed.


Visual Studio 2008



In order to create any kind of addin for Bookvar you need to have Visual Studio 2008 installed. There is no limitation of what kind of Visual Studio edition you use - you can use the free Express edition. You can get it from:



Bookvar installation



To test and work with your addin you need to have Bookvar installed. You can get it directly from:



The Process of creation


Initial project creation


To start with you need to create a Visual Studio project that you are going to work on. The type of project that you have to choose is Class Library project type:



Assembly references


Once you have created the project you need to add some assembly references to it.

First you need to add the Bookvar assemblies that provide class infrastructure for your addin. The assemblies are:




You can find these assemblies in Bookvar's installations folder (by default it is 

C:\Program Files\AVAXO\Bookvar).

Additionally you need to reference some other .NET Framework assemblies:




When you are done adding assembly references you are ready to start coding.


The actual code


By default Class Library projects come with one dummy class file called Class1.cs. You can either rename the file (which will rename the class in it) or delete it and create a new one with the name you like. I called mine ExportToPlainTextAddin.cs. It will be the only class that I intend to create for this addin, however you can have as many as you need.

The next step is to add some using statements, attributes and inherit a base class. After that my class declaration looks more like this:

    1 using System;

    2 using System.AddIn;

    3 using System.IO;

    4 using System.Text;

    5 using System.Windows.Forms;

    6 using Bookvar.AddIns.AddInViews;

    7 using Bookvar.Common;

    8 using Bookvar.ObjectModel;


   10 namespace ExportToPlainText

   11 {

   12     [AddIn("Export To Plain Text Addin", Version = "")]

   13     public class ExportToPlainTextAddin : BookvarAddinView


The base class for my addin is BookvarAddinView. It is abstract so you need to implement (override) one property and one method:


 public override void Execute(Topic topic)

 public override AddinInfo Info


The Info property is of type AddinInfo. It has some properties that are used for visualizing the addin button in the ribbon toolbar. The most interesting one is Image as it is used for displaying the icon for the addin. You need to assign a byte array to it that represents the image you want to show. The best way is to have the image embedded as a resource into the addin assembly and extract it from there.


   77 public override AddinInfo Info

   78 {

   79     get

   80     {


   82         AddinInfo info = new AddinInfo

   83         {

   84             Name = "Plain Text",

   85             Group = "Export",

   86             Description = "Exports a mind map to a plain text file",

   87             Image = AssemblyUtility.LoadImageFromResources(

   88                 typeof(ExportToPlainTextAddin).Assembly,

   89                 "ExportToPlainText.Notepad30.png")

   90         };


   92         return info;

   93     }

   94 }


The method you need to override is void Execute(Topic topic). It is called every time the addin is executed. Here, we meet a new type called Topic. It represents mind map topic with all of its properties like notes, hyperlink, attachments etc. For now we will need mainly on the Name and Note properties as we are going to export only those to a text file.

In my addin I'm going to show a SaveFileDialog first and if the user enters a name of a file, I'll save the content of the mind map in that file. Here is how my Execute method looks like:


   21 public override void Execute(Topic topic)

   22 {

   23     SaveFileDialog fileDialog = new SaveFileDialog

   24     {

   25         Filter = "Plain Text (*.txt)|*.txt|All Files (*.*)|*.*"

   26     };

   27     if (fileDialog.ShowDialog() == DialogResult.OK)

   28     {

   29         string fileToExportTo = fileDialog.FileName;

   30         string exportedText =

   31                     GetTopicTextContent(topic, String.Empty, 0);

   32         File.WriteAllText(fileToExportTo,exportedText);


   34         MessageBox.Show("Map exported successfully!",

   35                 "Success",

   36                 MessageBoxButtons.OK,

   37                 MessageBoxIcon.None);

   38     }


   40 }


In this method I'm calling a method called GetTopicTextContent. It runs through the topic's children recursively and returns its text representation. I'm not going to write that method's code here as it is not showing anything interesting. However, if you want to see it I'll attach a link to the source code of this addin for download.


Testing and deployment


In order to test whether your addin works you need to put it in action. To do this, you need to create a separate folder under the addins folder of Bookvar (by default it is situated here - C:\Program Files\AVAXO\Bookvar\Addins). In my sample the folder is called ExportToPlainText. Once you build your addin project, you need to copy from its bin directory all files except one dll to the newly created folder. The dll you have to not have copied is the Bookvar.Addins.AddInViews.dll.

It is a bit sloppy to copy assemblies every time you build, however except for the ExportToPlainText.dll all others will not change and so there is no need to copy them every time. For the ExportToPlainText.dll you can use a post build event commands to copy it automatically. Have in mind that if the Bookvar is running and has loaded your addin, you won't be able to override it.

Once you have your addin finished you can pack it up in a simple XCopy installer that will just copy your folder to Bookvar's Addin folder.




The compiled and ready for work version of the addin can be downloaded from here and the source code for it from here.


Installation instructions


To get the addin to work you just need to extract the folder that is contained into the zip to Bookvar's addin folder (by default it is - C:\Program Files\AVAXO\Bookvar\Addins) and start Bookvar and have fun.

P.S.: If you start developing your own addins we encourage you to send them to us so we can include them in future releases.