You can open the extension point schema editor in two ways: as a by-product of creating a new extension point or by opening an existing extension point schema. By convention, new schemas have the same name as the extension point id with a .exsd file extension. They are placed in schema directory in your plug-in directory tree.
When a new extension point is created in the PDE, the initial schema file will also be created and the schema editor will be opened for editing. You can define the schema right away, or close it and do it later. Making a complete extension point schema allows PDE to offer automated assistance to the users of your extension point.
The PDE schema editor is based on the same concepts as the plug-in manifest editor. It has two form pages and one source page. Since XML schema is verbose and can be hard to read in its source form, you should use the form pages for most of the editing. The source page is useful for reading the resulting source code.
We previously created the "Sample Parsers" extension point and the initial schema. We can now open the schema by going into the schema folder of our project and double-clicking on the parsers.exsd file. This will open the schema editor.
We want to do the following:
Every extension point schema starts with a declaration of the the "extension" element. We will add a new XML element called "parser."
So far, the schema editor should look like this:
We will now add an additional attribute that takes values from a discrete list of choices. This means we need to create an enumeration restriction of the base string type. In addition, we will set a default value for the attribute.
The restriction dialog should look like this:
When the dialog is closed, change the "use" attribute to "default" and "value" attribute to "always." This establishes the default value. Note that the status line shows an error message as you are typing the value, since it restricts valid values to the three enumeration choices. Once you finish typing, the error message should go away because "always" is a valid value.
Now that we have defined all of the elements and attributes, we need to define grammar. Our goal is to define that the "extension" element can have any number of "parser" elements as children.
After defining the grammar, the DTD approximation below the grammar section shows what the grammar for the selected element would look like in DTD. This information is provided to help developers who are still more comfortable with DTDs than XML schemas.
Now that we have defined valid elements, attributes and grammar, we need to provide some information about the extension point. There are two types of schema documentation snippets:
The first snippet type is provided in the Definition page of the schema manifest. As you select elements and attributes, you can add short text about them in the "Description" section. The expected format is raw HTML (as with Javadoc) and the text will be copied as-is into the final reference document.
We now have to provide a short text description of the extension point itself. In order to do that, we switch to the Documentation page:
The following is an example of the extension point usage: <p> <pre> <extension point="com.example.xyz.parsers"> <parser id="com.example.xyz.parser1" name="Sample Parser 1" class="com.example.xyz.SampleParser1"> </parser> </extension> </pre> </p>
Press Apply.
Note: Special consideration has to be taken when providing examples. Normally, PDE would treat the provided text as raw HTML and would not respect new line and white space greater than one character (i.e. ignorable white space). This is to be expected when regular text is concerned, but is extremely annoying when providing examples, where tabbing and vertical alignment is significant if the example is to look good. PDE has a compromise for this situation: if it detects the HTML tag <pre>, it will take the content as-is (preserving all characters without modification) until closing tag </pre> is seen. This is why we can provide an example like the above and be confident that it will look good in the final reference document.
You may have already noticed that as you type documentation, more and more elements in the editor Outline view acquire a "pen" image overlay. This little indicator tells you that the element in question has some text associated with it - a quick way to check if the documentation is missing somewhere in the document.
Once we have finished with the documentation, we can take a look at the reference documentation. You can do it in two ways. All the time during your work, you can preview the reference document by selecting Preview Reference Document item from the pop-up menu. Alternatively, you can set up PDE preferences (Preferences>Plug-in Development>Compilers, under Schema tab) to automatically create reference documentation on each schema file change. Regardless of the method to create it, the resulting document for this example would look like this.