16.0 Extend Framework

[kirkilj]

The list of new features in 16.0 mentions that an existing framework can be extended. I searched, but couldn't find how this is accomplished. Is it done through the Document Type definition in Preferences or is it a Java-based extension mechanism?

Regards

[Radu]

Hi John,

In the Oxygen Preferences->"Document Type Association" page you have a new button underneath the list of document types called Extend.
Basically you can choose to extend the DITA document type and save the new extension to an external location like OXYGEN_INSTALL_DIR/frameworks/dita_extended/dita_custom.framework.
In your extension you will be able to add and remove functionality from the base, add references either to resources in the base framework folder or to resources in the dita_extended folder.
You can then pack your dita_extended framework folder as an add-on.
The benefit of an extension should be the fact that on each new release of Oxygen which adds additional features to the DITA framework you will benefit of those changes in the extension framework without the need to duplicate again the newest DITA framework and re-add your custom stuff to it.

Regards,
Radu

[kirkilj]

So if we already have an existing fork of the DITA framework for 15.2, I'm assuming that we would perform directory diffs to isolate the existing changes to the base framework for 15.2, and then use the diff as a guide to construct the new framework extension this first time for 16.0. Subsequent releases would then be much simpler.

John

[Radu]

Hi John,

Unfortunately we do not expose a mechanism to compare a framework configuration with an original framework configuration and obtain an extension configuration.
You will probably have to extend the base framework and make again the changes you originally did in the extension.

Regards,
Radu

[kirkilj]

Hi Radu,

I have no problem creating the extended version by doing my own diffs, since it will set the stage for less error prone drudgery in the future. After doing this for the 15.1 to 15.2 upgrade to pick up the DITA framework improvements, I know what I need to do.

Thanks for the extension capability.

John

[kirkilj]

Hi Radu,

I took my first step to create an extended framework, but ran into an issue quickly.

I chose the DITA framework, clicked the extend button, clicked the External button, and accepted the default name in the frameworks folder. See screenshot:



It looks like it's in the right directory to me. I'm running <oXygen/> XML Editor 16.0, build 2014060420 (64-bit).


John

[Radu]

Hi John,

The message says something like:

...a subdirectory of the frameworks directory...

Every external framework (and a framework extension is also an external framework) needs to be defined in its own folder.
So in the OXYGEN_INSTALL_DIR\frameworks folder you should define a new folder called for example dita-freescale in which you should save the extension framework dita_freescale.framework configuration file. Initially the extended framework will use all the referenced from the base DITA framework. For example its references to the main CSS used for editing will use this special editor variable:

${baseFramework}/css_classed/dita.css


but you can edit it at will to change various settings.
Then you can share this extra dita-freescale framework folder with your colleagues, either by having them reference an additional framework directory (Preferences-> Document Type Association / Locations page) or by distributing it as an add-on.

Regards,
Radu

[kirkilj]

OK, I'm done slapping my forehead for not creating the framework directory first.

I can see the references to the new variable "baseFramework" through the UI, but I don't see it it the framework file itself. It looks like a fully serialized framework with references to the "framework" variable instead. If we're used to editing the actual framework file, should we be making references to the "baseFramework" or "framework" variables? Does Oxygen perform this mapping at a later stage?

Should CSS import statements that override DITA CSS use the baseFramework variable now?

Code: Select all

@import "${baseFramework}/css_classed/dita.css"; 

John

[Radu]

Hi John,

Please see some answers

It looks like a fully serialized framework with references to the "framework" variable instead.

The serialized framework contains an identical copy of the base framework. It also contains a list of patches which are your modifications to the base framework. The base framework is stored in it because when the extension is applied to a newer framework configuration (for example the extension is copied in the Oxygen 17 framework which contains an updated version of the "DITA" framework) it will perform a three-way diff, Oxygen will check what has changed between the original extended framework and the new framework and make adjustments accordingly.

If we're used to editing the actual framework file, should we be making references to the "baseFramework" or "framework" variables? Does Oxygen perform this mapping at a later stage?

You should leave the copy of the base framework unchanged edit that particular field containing the extensions list but I would not recommand editing the .framework manually.

Should CSS import statements that override DITA CSS use the baseFramework variable now?

We do not expand editor variables in "@import" statements.
If you want to add a CSS "layer" over the default CSS stylesheets you can add an additional XML catalog to your extension which maps a specific URI known by Oxygen to that layer CSS:

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

Regards,
Radu

[kirkilj]

Thanks for the reference to using the catalog for CSS assets, but couldn't I also just put

Code: Select all

@import "../../dita/css_classed/dita.css"

at the top of the css file in which my overrides are centralized? The disadvantage here is that it assumes that a dita_extended framework directory is a peer to the dita framework directory, sharing the same parent directory. If the extension is an addon, then this definitely is not the case and I see your point about using the catalog to perform the indirection.

I've studied http://www.oxygenxml.com/doc/ug-oxygen/ ... ports.html, but it's not clear to me what my entry would be in my override css import statement and what would be the catalog entry to resolve it to the base dita framework's css.

Would I just make up a fictitious URI name to use as the name of the URI I'd use in the import statement?

Does it have to be a full uri?

How will this resolve on the 2 environments mentioned below to find the base dita framework?

Do you have a default path for Oxygen bundled frameworks that I can use, like you have for xml files of any type (uri name="http://www.oxygenxml.com/extensions/aut ... Custom.css" uri="path/to/custom.css"/)?

On our Windows clients, we use addons for our frameworks, but on Linux virtual machines we use a custom frameworks directory that is controlled by the -Dcom.oxygenxml.editor.frameworks.url parameter in the .vmoptions file.

John

[alex_jitianu]

Hi John,

Radu is currently on leave so I'll try to help you while he's away.

First, I just want to make sure I understood the question. You are extending the built-in DITA framework and you want add changes to the built-in CSS rules. So you want to create a new CSS that imports the original one, like this:

Code: Select all

@import "../../dita/css_classed/dita.css";

// my custom rules that override the rules from dita.css

This relative import should work just fine minus the case when your framework is packed and deployed as an add-on.

I think that what Radu suggested was of the following solutions:
1. Leave the associated CSS untouched in the extended framework. Create a custom_dita.css and add all of your custom rules. Inside the Catalogs tab of the extended framework add a catalog with a content something like this:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.1//EN" "http://www.oasis-open.org/committees/entity/release/1.1/catalog.dtd">

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

    <uri name="http://www.oxygenxml.com/extensions/author/css/userCustom.css" uri="custom_dita.css"/>

</catalog>

What will happen is that the rule from custom_dita.css will be appended to the other rules (they have greater priority).

2. The URI from a CSS import is passed through catalogs. First of all, you should associate in the extended document type a CSS with a content like this (please notice the @import):

Code: Select all

@import "http://my.custom.url/redirect/to/base/dita.css";

// my custom rules that override the rules from dita.css

Using the plugin Java Based API, from an Workspace Access plugin, you can add a resolver :

Code: Select all

  public void applicationStarted(final StandalonePluginWorkspace pluginWorkspaceAccess) {

	  pluginWorkspaceAccess.getXMLUtilAccess().addPriorityURIResolver(new URIResolver() {

		@Override

		public Source resolve(String href, String base) throws TransformerException {

		      System.out.println("Resolve " + href);

		      if ("http://my.custom.url/redirect/to/base/dita.css".equals(href)) {

		        String resolved = EditorVariables.expandEditorVariables("${frameworks}/dita/css_classed/dita.css", null);

		        System.out.println("resolved " + resolved);

		        return new StreamSource(resolved);

		      }

		      return null;

		    }

	});

  }

Best regards,
Alex

[kirkilj]

When you said

I think that what Radu suggested was of the following solutions:

did you mean that there are two separate, independent possibilities numbered 1 and 2

OR

that there is only one solution that requires both steps 1 and 2?

[alex_jitianu]

Hi,

I'm sorry for not making it clear... What I meant is that there are two independent solutions, both using CSS resolving through catalog approaches.

Best regards,
Alex

[Radu]

Hi,

Third independent possible choice:

You create the extension of the DITA framework and then in the Author tab in the CSS tab you add a reference to a custom CSS (which is kept in the new extension framework folder). The reference to the custom CSS is added without any title and with the Alternate checkbox unchecked.
This extra CSS should be merged with the base dita.css reference when the XML is rendered in the visual editor.

Regards,
Radu