Questions about the Extension Bundles

[SSC]

Hello,

I´d like to use ro.sync.ecss.extensions.api.StylesFilter to alter the behavior for the image file path in DITA, because we place our images in a different location.
The location is specified in an PI inside the DITA XML document.

I use the Eclipse Version 13.2 of Oxygen.

I found this tutorial for creating Extensions:
http://www.oxygenxml.com/doc/ug-editor/ ... undle.html

Could someone please explain the last steps of this tutorial?

11. Package the compiled class into a jar file.

How do I get a compiled class of the java file, when there is no main method in it?
How do I package it into a jar file afterwards?
Does the Eclipse version use a different approach?

13. Add the jar file to the Author class path.

Where do I find the correct class path file?

14. Register the Java class by clicking on the Extensions tab. Press the Choose button and select from the displayed dialog the name of the class: SDFExtensionsBundle.

Where do I find the Extensions Tab?
I searched in the Eclipse Preferences, but could not find such an Extensions tab.

Regards,

Simon

[Radu]

Hi Simon,

Before you read my detailed answers about the styles filter:

It might not be necessary to set a styles filter.
You could try to alter the CSS:

OXYGEN_PLUGIN_INSTALL_DIR/frameworks/dita/css_classed/topic.css

which has the following selector:

Code: Select all

*[class~="topic/image"],

*[class~="topic/image"][placement="inline"] {

    display: inline;

    content: attr(href, url);

    width:attr(width, length);

    height:attr(height, length);

}

We have a lot of CSS extension functions:

http://www.oxygenxml.com/doc/ug-oxygen/ ... tions.html

For example you could do something like this:

Code: Select all

content: url("http://www.oxygenxml.com/images", attr(src));

or some more complicated concatenation of the URL where the XML is located with another folder path and then with the attribute @href:

Code: Select all

content: url(oxy_parent-url(oxy_base-uri()), oxy_concat("../path/to/another/dir/", attr(href)));

Please see some answers related to the styles filter below:

How do I get a compiled class of the java file, when there is no main method in it?

I do not quite understand what you mean but I will describe the steps that a developer using our Java API usually does.

1) Download the Author SDK:

http://www.oxygenxml.com/oxygen_sdk.htm ... horing_SDK

2) Create a new Java Eclipse project which has the libraries bundled with the Author SDK in its classpath

3) Create your custom Java class which implements the StylesFilter interface.

The Java class is automatically compiled by the Eclipse platform and it is present in the bin or classes folder.

How do I package it into a jar file afterwards?

You could use ANT for example. You could create and run an ANT build file which uses the <jar> task for this.
Then the ANT build file could also copy the JAR library to the appropriate place (OXYGEN_PLUGIN_INSTALL_DIR/frameworks/dita/yourLibrary.jar).

Or you could simply open in the explorer the directory where Eclipse compiles all Java classes and zip its entire content renaming the resulting zip file with the ".jar" extension, then copy the JAR to the right place.
The JAR should contain inside it a folder structure like:
your/package/name/YourStylesFilterImpl.class

Does the Eclipse version use a different approach?

No.

Where do I find the correct class path file?

The topic you are reading is out of context.
Basically the support Oxygen has for various vocabularies is based on document types:

http://www.oxygenxml.com/doc/ug-editorE ... tings.html

The list of document types in an Oxygen installation can be located in the Eclipse Preferences->Oxygen->Document Type Association preference page.

If you edit the DITA document type from the list, the document type edit dialog contains a tab called Classpath in which you should add a reference to the JAR you have previously copied to the OXYGEN_PLUGIN_INSTALL_DIR/frameworks/dita/yourLibrary.jar.
The reference should use editor variables so that it can be expanded correctly for all users who will use this customized DITA document type.

After you add the jar to the Classpath you should switch to the Extensions tab where you can choose an implementation for CSS Style Filter. If all went well, you should find your own implementation when you click the Choose button.

Then save the dialog and press "Ok" in the preferecences page.

This will rezult in a change of the XML customization file:

OXYGEN_PLUGIN_INSTALL_DIR/frameworks/dita/dita.framework

which now will contain a reference to the new jar + reference to the styles filter implementation.

After this, opening a DITA topic should call your styles filter for each of the elements.

Regards,
Radu

[SSC]

Hello Radu,

I first tried it with the CSS extension functions.
And I used this static definition:

Code: Select all

content:url(concat(oxy_parent-url(oxy_parent-url(oxy_parent-url(oxy_base-uri()))) "../graphics/" attr(name)));

But the fact that some customers use different locations for their graphics and put the path into a PI forced me to use the StylesFilter.

Or is there a CSS extension function available, which is able to read a PI from the DITA XML document?

In the StylesFilter I am using the following code:

Code: Select all

styles.setProperty(Styles.KEY_MIXED_CONTENT,                            new StaticContent[] { new URIContent("file://"+ this.graphic_path, href) });

By the way, do you have some documentation about what properties can be set to the Styles?Must it always be an Array of StaticContent or are there more Objects, which can be used?

Regards,

Simon

[Radu]

Hi Simon,

Or is there a CSS extension function available, which is able to read a PI from the DITA XML document?

The strongest extension function we have is called oxy_xpath:

http://www.oxygenxml.com/doc/ug-oxygen/ ... ction.html

You can use it to run full XPath 2.0 expressions over the entire XML document like:

Code: Select all

personnel{

    content:oxy_xpath("if (contains(//processing-instruction()[1], 'href')) then 'TEST' else 'TEST2'");

}

So it might be possible that using this function and a quite large XPath expression you could achieve the same result as when using the Styles Filter.

The only problem with this function is that it implies a lot of CPU processing on our side and when the document's size is over 500 KBs the processing might slow down the user.
This happens because any change you make in the document (even typing a character) could potentially influence a selector having a certain XPath expression so the entire document needs to be re validated quite often.

About the StylesFilter, your usage seems proper.
Am I do understand that you succeeded with the custom implementation?
Indeed the documentation does not cover all the properties which can be set in the Styles class, they are very many.
The Styles class has a lot of get methods and only a set method. Basically anything that you can get you can also set using the same object type returned on the get.

Regards,
Radu

[SSC]

Hi Radu,

yes I´d succeeded with the custom implementation.
The problem with this approach is that we cannot except the Author to setup the classpath and die StylesFilter, which is deeply hidden in the Preferences. I myself had problems to find the Extensions menu.

Is it possible to change the Classpath and Extensions by programm code, so that we can setup this when the client starts?

Maybe by changing the Eclipse IPreferenceStore you use for the configuration?
Or is there any other approach how we can set default values for the Classpath and Extensions, like the StylesFilter?

Regards,

Simon

[Radu]

Hi Simon,

All changes that you saved to the document type were made to the XML configuration file in this location:

OXYGEN_PLUGIN_INSTALL_DIR/frameworks/dita/dita.framework

So you somehow have to provide this modified framework file to the users who will use the customized Oxygen plugin.

How did you consider providing the Oxygen plugin to your users?
Let them install it from our web site or have your own package which also contains a modified version of our plugin?

Regards,
Radu

[SSC]

Hello Radu,

we will have our own package which contains a modified version of your plugin.

Our Software-Architect dislikes the fact that those things must be defined inside your plugin (i.e. the frameworks folder)

Is there any other approach?
- plugin extension point
- a listener with a certain hook for us in the programming code
- a different properties file where it can be defined

We´d like to avoid to confuse an author, who uses the preferences and think that those settings should be set somewhere else only by an admin.

In our opinion those settings are too technical for an author, who has no knowledge about jars and classpaths and just wants to edit XML documents.

Best regards,

Simon

[Radu]

Hi Simon,

There are no other approaches.

This architecture of frameworks directories used to provide editing support for XML vocabularies is shared between the Oxygen Eclipse and Standalone distributions.

As long as you will bundle our plugin with yours you will need to make these customizations to our plugin's contents (copying the JAR library to the dita framework directory, modifying the dita.framework) before bundling it with yours and providing it to your users.

Regards,
Radu