February 20, 2007

Creating an Mylar Connector Plugin for Jotspot

Creating an Mylar Connector Plugin for Jotspot

Jotspot is a wiki system that allows you to create forms and code for your wiki pages. My current project uses it for project planning and story (agile) management. It was recently purchased by Google and during their migration to Google's infrastructure new accounts are on hold, but should eventually be opened up. This is how I created a connector for our project hosted there. The intent is to give an overview of what needs to be implemented and where. I won't go through all the detail for each step, for example when it is time to query the repository for tasks I'll show what needs to happen upto and including the method call, but I won't show the details of the connection to Jotspot. Hopefully this will enable you to create your own connectors to your repositories.

Plugin Structure

The Mylar documentation suggests creating two plugin projects to implement your repository connector, the *.ui project and the *.core project. They also recommend modeling your connector after the Trac connector. For this connector I created the following two plugin projects and included the Trac plugin projects for reference:

Add Repository

The first step is to get the Mylar UI to recognize your repository when you select add repository. This shows up in the Task Repositories view:

Click the add repository icon. This launches this dialog box:

You can see the Jot Repository Item added by this project. The com.eclipse.mylar.jot.ui plugin will contribute all the extensions and reference com.eclipse.mylar.jot.core as needed. First we need to do some initial setup. When you created the *.ui plugin it should have opened the plugin manifest editor. Fill in some appropriate values.

The next step is to add the dependencies, using the Trac UI plugin as a reference:

The org.eclipse.mylar.jot.core will only be available after you've created that project. This should cover the classes referenced from the UI. Now onto the functional part, adding the extension that will list Jot as a repository in the Add Repository wizard. click the Add button and select org.eclipse.mylar.tasks.ui.repositories.

Now add a new connectorCore to that repository connector:

Edit the Details as follows:

The JotRepositoryConnector is a new class in the *.core project. You can click on the class hyperlink to create this class and extend org.eclipse.mylar.tasks.core.AbstractRepositoryConnector. Implement the getLabel() and getRepositoryType() to return "Jot Repository" and "jot" respectively. We now have Jot showing up in the Add Repository wizard.

Unfortunately nothing happens when you click next. To get this to work a JotRepositoryUi class must be added. Right click on the *.repositories extension and click new -> connectorUi. Click the class hyperlink and create a new JotConnectorUi class that extends org.eclipse.mylar.tasks.ui.AbstractRepositoryConnectorUi. Setting the icons here will add the icon to the Add Repository wizard.

When the next button is clicked the JotRepositoryConnector.getRepositoryType() is called checked against the same call on JotConnectorUi. This associates the to classes, if they match the icons are used and when next is clicked in the wizard the JotConnectorUi.getSettingsPage() is called as the next step in the repository setup. To show the settings page getSettingsPage() must return something that extends org.eclipse.mylar.tasks.ui.wizards.AbstractRepositorySettingsPage. Create a new class called JotRepositorySettingsPage that extends AbstractRepositorySettingsPage. You'll need a constructor that takes AbstractRepositoryConnectorUi as a parameter. In this constructor pass along the AbstractRepositoryConnectorUi with a title and description string to super. The only method you need to implement to get things working is to implement the isValidUrl() method. Once this is done you can successfully add the repository:

List Tasks

For this repository to really be useful, it needs to be able to query for a list of tasks, create a new task and update an existing task. When New Repository Task is clicked, each repository (AbstractRepositoryConnector) has its canCreateNewTask() method called if it returns true it is listed in the available repositories.

When Next is clicked JotRepositoryUi.getNewTaskWizard() is called. This method must return a valid wizard with at least one WizardPage added in the Wizard.addPages(). That WizardPage must add at least one control in its createControl method. It is up to you to generate the appropriate form on the page. When finish is available the Wizard.canFinish() should return true. When finish is clicked the Wizard.performFinish() method is called. This should complete the wizard. Both the NewTracTaskWizard and the NewWebTaskWizard open an editor on the wizard's finish.
(In Progress)


Akila said...

This is the type os tutorial i like. Small and very usefull. Tks

It save my time.

Jacob said...

This was very helpful, but it would be great if you could finish the tutorial.

Anonymous said...

This is very well written, but unfortunately yet unfished.
I'd like to ask you if you would consider finishing this great tutorial, please.

Anonymous said...

I really feel this kind of posts should be a part of the formal way of documentation for open source. This way it makes open source really much understandable and make our side stronger ;-)

Anonymous said...

This is really good tutorial kind of article. Simple and to the point.

S7 Software

Tejas bhojak said...

I was really getting frustrated while i was integrating mylyn for my own connector, but this tutorial was really great, really helpful.

Thanks a lot :) .

Anonymous said...

Your blog keeps getting better and better! Your older articles are not as good as newer ones you have a lot more creativity and originality now keep it up!

Anonymous said...

I inclination not agree on it. I think warm-hearted post. Especially the designation attracted me to be familiar with the unscathed story.

Anonymous said...

Amiable brief and this fill someone in on helped me alot in my college assignement. Thanks you as your information.