Blog post about how to switch from a project file to an add-on

[raducoravu]

One of our end users has an already configured Oxygen project which has a framework, transformation scenarios, layout templates and they want to pack it as an add-on.
Pasting below @AlexJitianu 's answer to them:

Hello,

An Oxygen project file is very powerful and versatile and it groups many settings in it, like you've already configured. You can pack as an add-on either a framework or a plugin. The good news is that a plugin can do pretty much what an xpr does. In your case:

1. Distribute a framework [1]. You put the framework directory inside the plugin's directory and then you edit the {{plugin.xml}} file and add something like this ({{@path}} is relative to {{plugin.xml}}):
   {code:xml}

{code}

2. Layout file. The Impose Options [1] plugin can impose a layout file, too. {{README.html}} describes how to name it and where to place it.

3. Templates. The Impose Options [1] plugin can contribute templates, too. {{README.html}} describes how to do that. Please note that templates can also be defined inside the framework. If you put the templates inside the framework [3] then you can just skip this step.

4. Options. In your case, these might be the transformation scenarios used in publishing. The procedure from my previous email describes how to prepare the scenarios. Please note that transformation scenarios can also be defined inside the framework [4], in your case the custom_dita framework folder which is an extension of the default DITA framework. If this is indeed how the transformation scenarios are configured, then you don't actually need to do anything for them. The simple fact that you've done 1. means that you have contributed the scenarios as well.

bq. Is it possible to bundle all these into single add-on and enforce the restrictions and schematron rules through the add-on?
So the answer is yes, but the project file is no longer the glue that binds these pieces together. The plugin is. And the plugin is packed and distributed as an add-on.

bq. I gave it a try but the add-on unzips the content of the add-on to {{\AppData\Roaming\com.oxygenxml\extensions\v22.1\frameworks\http_ip:8091_ngaddons.xml}}
That is the default location where add-ons are deployed.

bq. But I don’t see any configuration changes in Oxygen nor does the project bundled with the plugin automatically load in Oxygen? Wondering how I can make this work.
If you've zipped the contents of your project directory then your settings will not be loaded. Your zip must be an Imposed Options plugin [2] that was changed and enriched with your files as described above.

Have you tried using the Impose Options [2] plugin as a starting point for your add-on? If you have something already then you can send me the add-on archive to take a look at it. If I notice something amiss then I'll tell you how to fix it and I will remove it from my system afterwards.

Anyway, to try and summarize all of these, I recommend you to:

• Put the templates inside the framework [3]
• Put the transformation scenarios inside the framework.
• Put the framework inside the Impose Options plugin
• Put the layout file inside the Impose Options plugin
• The Impose Options plugin directory is what you need to need to zip and and deploy as an add-on.

Your Impose Options plugin directory should look like this:
{code}
oxygen-sample-plugin-impose-options-22.1
lib
oxygen-sample-plugin-impose-options-22.1.jar
plugin.xml
Framework
application.layout
{code}
To make the framework load, {{plugin.xml}} should contain this line:
{code:xml}

{code}
I hope this helps! let me know if you need additional details. If you can send me the resulting archive, then I can analyze it to see is everything is O.K.

[1] https://www.oxygenxml.com/doc/versions/22.1/ug-editor/topics/additional-framework-extension.html

[2] https://www.oxygenxml.com/maven/com/oxygenxml/samples/oxygen-sample-plugin-impose-options/22.1.0.0/oxygen-sample-plugin-impose-options-22.1.0.0-plugin.jar

[3] https://www.oxygenxml.com/doc/versions/22.1/ug-editor/topics/sharing-templates.html

[4] https://www.oxygenxml.com/doc/versions/22.1/ug-editor/topics/document-type-transformation-tab.html

[AlexJitianu]

One more aspect to consider: the transformation scenarios contain references to various resources. My answer to this:

Hello,

Right now you are using the ${pd} or ${pdu} editor variable, right? First of all you need to export the scenarios to an XML file, let's say options.xml, like we've discussed. Afterwards there are two possibilities:

1. We move the scenarios inside the framework:

• Copy all the resources (css, images, etc.) in the framework directory.

• Edit your framework and go to the Transformation tab [1]. Use the Import scenarios action on the button to import the scenarios from options.xml. Edit each scenarios and replace the ${pd} / ${pdu} variables with ${frameworkDir} / ${framework}

2. We move the scenarios inside the plugin

• Copy all the resources (css, images, etc.) in the plugin directory.

• Copy options.xml in the plugin directory

• Edit options.xml and and replace the ${pd} / ${pdu} variables with ${pluginDir(pluginID)} / ${pluginDirURL(pluginID)} . The ID is found inside plugin.xml, and for the Impose Options plugin is: com.oxygenxml.plugin.ImposeOptions

[1] https://www.oxygenxml.com/doc/versions/22.1/ug-editor/topics/document-type-transformation-tab.html