Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Corona HowTo: Add a new page to Project Container View"

(Per repository page)
(obsolete)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''UNDER CONSTRUCTION'''
 
  
The [[Corona Project Container View|Project Container View (PCV)]] can be easily extended to contain new pages. Even the default pages are added by extension mechanism.
 
 
First thing to note is that there are two kinds of pages:
 
* per project container
 
* per repository
 
 
The ''per project container'' pages displays information that are not connected with any repository, but rather with project container itself. This pages are displayed for every project container, no matter what it contains. The ''per repository'' pages in contrast show information defined in a repository. This kind of page is displayed only if the page matches a repository defined in the project container.
 
 
The later sections shows step-by-step how to add your own PCV page.
 
 
== Define extension ==
 
Firstly you need to provide an extension to Corona PCV page extension point. This step is required no matter if you provide a ''per project container'' or ''per repository'' page. To achieve it, do following:
 
# Open plugin.xml editor.
 
# Switch to ''Dependencies'' tab.
 
# Add ''org.eclipse.corona.container.project.ui'' to ''required plug-ins''.
 
# Switch to ''Extensions'' tab.
 
# Click the ''Add'' button and select ''org.eclipse.corona.container.project.ui.page'' and click ''Finish''
 
 
Save changes to the plugin.xml. This point will be taken as start point for both adding ''per project container'' and ''per repository'' page.
 
 
== Common interfaces for pages ==
 
Both types of pages are in fact extended Eclipse view. They implement a specialized interfaces which are in fact extension of three basic Eclipse interfaces:
 
* [http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/IViewPart.html ''org.eclipse.ui.'''IViewPart'''''] is default for Eclipse to create views.
 
* [http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/runtime/IExecutableExtension.html ''org.eclipse.core.runtime.'''IExecutableExtension'''''], which is used to provide extension point element that was used to create instance.
 
* [http://bundles.osgi.org/javadoc/r4/org/osgi/service/event/EventHandler.html ''org.osgi.service.event.'''EventHandler'''''] used to deliver [[Corona Design Collaboration|collaboration events]] that take place in the project container for which the page was created. You do not need to register/unregister yourself for events - it will be done for you.
 
 
The class must also provide a default public constructor. For both classes there are abstract default implementations that provide default implementations to most methods.
 
 
== Per project container page ==
 
You have plugin.xml editor opened on ''Extensions'' tab. Now, we need to create the page. So do fallowing:
 
# Right-click ''org.eclipse.corona.container.project.ui.page'' in ''All Extensions'' list.
 
# Select ''New -> projectPage'' from the pop-up menu.
 
# On the right side in ''Extension Element Details'' fill the page information:
 
#* 'id' - the unique identifier of the page within the Eclipse installation. It should be prefixed with our plugin name to ensure uniqueness.
 
#* 'name' - the name of the page, which will be displayed in the page tab; used for UI only.
 
#* 'class' - the full qualified name of class that implement the page; the class must implement ''org.eclipse.corona.container.project.ui.view.page.'''IProjectContainerPage''''' interface.
 
# Save changes in plugin.xml.
 
# Implement the page view class.
 
 
The page class ''org.eclipse.corona.container.project.ui.view.page.'''IProjectContainerPage''''' interface, which contains interfaces described in [[#Common interfaces for pages|previous section]] plus provides a new init method that is used to provide the project container which is the subject of the page.
 
 
For your convenience we provided also an abstract class which provides default implementations of methods - ''org.eclipse.corona.container.project.ui.view.page.'''AbstractProjectContainerPage'''''. Unless you have your inheritance structure, you should probably use it instead of implementing ''IProjectContainerPage'' from scratch.
 
 
=== An example ===
 
Lets create a simple page that simply shows a a name of project container as it content. So firstly you need to define the extension as described earlier. It would look as at the image below.
 
 
[[Image:Corona howto namepage1.png]]
 
 
The corresponding plugin.xml fragment looks like this:
 
 
  <extension
 
        point="org.eclipse.corona.container.project.ui.page">
 
      <projectPage
 
            class="org.eclipse.corona.examples.pcv.page.ProjectNamePage"
 
            id="org.eclipse.corona.examples.pcv.page.projectNamePage"
 
            name="Project Name"/>
 
  </extension>
 
 
Now it is time to implement the view class. To make our live easier I will use abstract class instead of interface. Note that the project context container is already set as a field and is ready to use. The default abstract class implementation saves the project context in a field.
 
 
package org.eclipse.corona.examples.pcv.page;
 
 
import org.eclipse.corona.container.project.ui.view.page.AbstractProjectContainerPage;
 
import org.eclipse.corona.container.project.ui.view.page.IProjectContainerPage;
 
import org.eclipse.swt.SWT;
 
import org.eclipse.swt.widgets.Composite;
 
import org.eclipse.swt.widgets.Label;
 
 
public class ProjectNamePage extends AbstractProjectContainerPage
 
                              implements IProjectContainerPage {
 
 
public void createPartControl(Composite parent) {
 
Label projectName = new Label(parent, SWT.NONE);
 
projectName.setText("Name: " + this.container.getName());
 
}
 
}
 
 
Now simply run Eclipse with your plugin added and the result should be similar to the picture below.
 
 
[[Image:Corona howto namepage2.png]]
 
 
Simple, isn't it? :)
 
 
== Per repository page ==
 
The ''per repository'' pages are a bit more complicated. The problem is in matching when a certain page should be displayed. To do the matching there are two parameters from repository definition taken:
 
* ''content-type''. This property defines what is the contained within a repository. To ensure uniqueness, the value is URI.
 
* ''access-type''. This property defines what is the way to access the repository or the format of the repository. For instance it may say that it represents CVS, or information XML format. Again the form is URI to ensure uniqueness.
 
 
So, for instance if you have a repository, which contains a workbench project and it is kept in CVS, then ''content-type'' will be for ''workbench project'', while ''access-type'' for ''CVS''. An other example, a project home page will have ''content-type'' something like ''home page'', while ''access-type'' would be ''web page''. Bugzilla through WWW - ''bugzilla'' and ''web page'' respectively. I hope it clarifies a bit.
 
 
:NOTE: The provided access and content types are not valid values. Those are just ''human-readable'' form of URIs, just to give you an idea.
 
 
Now, to open a page for a repository, we need to somehow match declared pages with repositories they can handle. The taken approach is that you defined either ''content-type'' or ''access-type'' or even both. Whichever you provide there must fully match with your filter. Lets have some examples to clarify it:
 
* If you have a page that knows how to display HTML pages, you would register your page for any repository that has ''access-type'' set to ''web page''. No matter if it contains a project web page, or Bugzilla bugs - your view always know how to display it. So you register it with filter only on ''access-type'' set to ''web page''.
 
* If you have a special page for Bugzilla, which is able to parse its pages and display some additional information. In this case you would register a page with definition of both ''access-type'' = ''web page'' and ''content-type'' = ''bugzilla''.
 
* If you want to display some information regardless of how they are stored, then you simply add ''content-type'' value. An example of such approach is in team member page, which is focused on displaying members rather than taking care of how to access it. Usually this approach requires usage of ''repository adapters'' which allows you to access repository in format agnostic way.
 
 
Note that if you would deploy above examples, then for Bugzilla you would have two pages displayed. One would be simply web browser, while the second one would be something that somehow parse Bugzilla output. For now we keep this approach, we don't know if we should move to something like ''best match''.
 
 
As you can somehow deduct for the bullets above, there are two default possible ways of creating repository pages:
 
* descriptor based - when your page displays information based only on repository descriptor
 
* adapter based - when your page requires a repository adapter which will read repository content for you.
 
 
For both situations there predefined abstract classes to handle basic scenarios - ''org.eclipse.corona.container.project.ui.view.page.'''AbstractRepositoryPage''''' and ''org.eclipse.corona.container.project.ui.view.page.'''AbstractRepositoryAdapterPage''''' respectively.
 
 
=== Descriptor based pages ===
 
 
==== Example ====
 
 
=== Adapter based pages ===
 
 
==== Example ====
 
 
== See also ==
 
* [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.corona/plugins/org.eclipse.corona.container.project.ui/src/org/eclipse/corona/internal/container/project/ui/view/page/ Source of default pages] and corresponding [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.corona/plugins/org.eclipse.corona.container.project.ui/plugin.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup plugin.xml]
 

Latest revision as of 10:49, 27 February 2008

Back to the top