16.0 Extend Framework
Post here questions and problems related to editing and publishing DITA content.
16.0 Extend Framework
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
Regards
Re: 16.0 Extend Framework
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
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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: 16.0 Extend Framework
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
John
Re: 16.0 Extend Framework
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
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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: 16.0 Extend Framework
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
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
Re: 16.0 Extend Framework
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
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
Re: 16.0 Extend Framework
Hi John,
The message says something like:
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
The message says something like:
Every external framework (and a framework extension is also an external framework) needs to be defined in its own folder....a subdirectory of the frameworks directory...
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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: 16.0 Extend Framework
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?
John
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";
Re: 16.0 Extend Framework
Hi John,
Please see some answers
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
Please see some answers
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.It looks like a fully serialized framework with references to the "framework" variable instead.
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.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?
We do not expand editor variables in "@import" statements.Should CSS import statements that override DITA CSS use the baseFramework variable now?
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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: 16.0 Extend Framework
Thanks for the reference to using the catalog for CSS assets, but couldn't I also just put
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
Code: Select all
@import "../../dita/css_classed/dita.css"
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
-
- Posts: 1009
- Joined: Wed Nov 16, 2005 11:11 am
Re: 16.0 Extend Framework
Post by 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:
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:
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):
Using the plugin Java Based API, from an Workspace Access plugin, you can add a resolver :
Best regards,
Alex
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
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>
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
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;
}
});
}
Alex
Re: 16.0 Extend Framework
When you said
OR
that there is only one solution that requires both steps 1 and 2?
did you mean that there are two separate, independent possibilities numbered 1 and 2I think that what Radu suggested was of the following solutions:
OR
that there is only one solution that requires both steps 1 and 2?
-
- Posts: 1009
- Joined: Wed Nov 16, 2005 11:11 am
Re: 16.0 Extend Framework
Post by 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
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
Re: 16.0 Extend Framework
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
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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Return to “DITA (Editing and Publishing DITA Content)”
Jump to
- Oxygen XML Editor/Author/Developer
- ↳ Feature Request
- ↳ Common Problems
- ↳ DITA (Editing and Publishing DITA Content)
- ↳ SDK-API, Frameworks - Document Types
- ↳ DocBook
- ↳ TEI
- ↳ XHTML
- ↳ Other Issues
- Oxygen XML Web Author
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Content Fusion
- ↳ Feature Request
- ↳ Common Problems
- Oxygen JSON Editor
- ↳ Feature Request
- ↳ Common Problems
- Oxygen PDF Chemistry
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Feedback
- ↳ Feature Request
- ↳ Common Problems
- Oxygen XML WebHelp
- ↳ Feature Request
- ↳ Common Problems
- XML
- ↳ General XML Questions
- ↳ XSLT and FOP
- ↳ XML Schemas
- ↳ XQuery
- NVDL
- ↳ General NVDL Issues
- ↳ oNVDL Related Issues
- XML Services Market
- ↳ Offer a Service