Custom framework, xpr files, and code templates

[Lemesany]

Hello,
I've created a custom framework by following the steps in http://blog.oxygenxml.com/2015/08/docum ... aring.html.
I've packaged the framework as a zip file and deployed as an add-on by following https://www.oxygenxml.com/doc/versions/ ... ing-addons.

I was able to add the zip and xml file to an HTTP server and get the add-on to automatically notify me when the xml file was updated. In the framework, I can add a templates folder for custom dita file templates. Where should I place code templates? I have a few custom code templates that required manual import in Preferences > Editor > Templates > Code Templates for each user. Can I add these templates to the custom framework so I can push these updates out to users? Additionally, can I add multiple project files that point to different source files? I'm not sure where in my custom framework to add these two pieces.

My structure that works currently is my custom.framework file lives next to the doctemplates folder.

[Radu]

Hi,

If in your custom framework folder directory you have that doctemplates folder which contains new file templates, if you edit the custom document type association from the Oxygen "Document Type Associations" preferences page, there is a tab called Templates in which you can add a reference to the templates folder from your custom framework folder. In your case the reference should be something like ${frameworkDir}/doctemplates.

Regards,
Radu

[alex_jitianu]

Hi,

Unfortunately, Code Templates can't be set from a framework. If there aren't many of them you could create author actions instead. An author action is just a configuration that is kept inside the framework itself. You can contribute these actions inside the content completion window or you can put it on the toolbar.

If author actions are not an option, then you should know that a plugin can automatically import a set of options (in your case with code templates.) We have such a sample plugin packed as an add-on. You can download it from here. What you should do:
1. unzip it ( you can read README.html to see everything that this plugin can do)
2. export your options inside the plugin's directory (next to the plugin.xml file) inside a file named options.xml.
3. Pack the plugin as an add-on next to the framework. The users will see and install them both.

Code: Select all

Additionally, can I add multiple project files that point to different source files? I'm not sure where in my custom framework to add these two pieces.

Unfortunately even though you can put projects inside a framework we don't have an API to automatically load them. because of that the user will have to navigate to the location where we install the framework and manually open the project. What would be the use case for this? Will the source files also be distributed or they will be remote? Perhaps I can offer an alternative...

Best regards,
Alex

[Lemesany]

Thank you, Alex, for the information!

I'm trying to package the code templates as a plugin instead, using the method you described. I downloaded the .jar file you linked, added options.xml and placed it next to plugin.xml. My next steps aren't working. I tried two ways:

Method 1:
placed the revised .jar file next to my current framework zip as such:
add-on.xml
codetemplates.jar
dita_extension.zip

and the add-on.xml file looks like:

Code: Select all

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

<xt:extensions xmlns:xt="http://www.oxygenxml.com/ns/extension"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://www.oxygenxml.com/ns/extension http://www.oxygenxml.com/ns/extension/extensions.xsd">

  <xt:extension id="dita-now">

        <xt:location href="dita_extension.zip"/>

        <xt:version>1.0.62</xt:version>

        <xt:oxy_version>17.0+</xt:oxy_version>

        <xt:type>framework</xt:type>

        <xt:author>Lemesany</xt:author>

        <xt:name>Custom framework</xt:name>

        <xt:description xmlns="http://www.w3.org/1999/xhtml">Use this framework.</xt:description>

        <xt:license>

<![CDATA[



END USER LICENSE AGREEMENT



]]></xt:license>

    </xt:extension>

    <xt:extension id="codetemplates">

        <xt:location href="codetemplates.jar"/>

        <xt:version>1.0.62</xt:version>

        <xt:oxy_version>17.0+</xt:oxy_version>

        <xt:type>plugin</xt:type>

        <xt:author>Lemesany</xt:author>

        <xt:name>Code templates</xt:name>

        <xt:description xmlns="http://www.w3.org/1999/xhtml">Includes custom code templates</xt:description>

        <xt:license>

            <![CDATA[



END USER LICENSE AGREEMENT



]]></xt:license>

    </xt:extension>

</xt:extensions>

Method 2:
compressed the revised .jar file as a .zip, and placed next to my current framework zip as such:
add-on.xml
codetemplates.zip
dita_extension.zip

In the code example above, instead of .jar, I used .zip for this method.

Both methods give me the error:
"Wrong package structure. Please pack the framework root directory not just its content." and lists "oxygen-sample-plugin-impose-options-18.1.0.1-plugin.jar" at the end. I then tried to not rename the .jar and replaced the add-on.xml file with the full original name, but still got the same error.

The options.xml file was created two different ways for different tests: I added our custom code templates to the Editor > Code Templates preferences, then exported and saved as options.xml in the oxygen-sample-plugin-impose-options-18.1 folder (next to plugin.xml and extension.xml). That didn't work. Second method was following the steps in the readme "Note: To create an options.xml file, use the action Export Global Options.. from the oXygen Options menu. Export this file to the plugin's main directory and edit it as needed." I added the code templates to my preferences, then exported the options.xml to the same directory.

[Lemesany]

Alex, I previously replied about the structure error but have resolved that. Now my problem is still in the options.xml file. Again, I tried to get the code templates to appear in two ways: Adding them to Preferences > Code Templates, then exporting the options.xml as the Readme states; and exporting the code templates from the preferences and renaming it options.xml. I no longer get the warning message about the structure, but the code templates are still not appearing in the preferences or when I search for them in Author.

Thanks for your help!

[alex_jitianu]

Hi,

Please send me the plugin package on support@oxygenxml.com so I can take a look at it. I've tried the same scenario myself and in my case the options were imposed. Another thing that goes through my head is that the plugin imposes the options just once, on the first start-up (if it doesn't find an options file at that point then it wont impose anything at all). What you could do is:
- make sure the plugin is deployed and has the proper options.xml
- Note: You might want to select Options->Export Global Options... to make sure you don't loose any of your options because of the next step
- inside Oxygen select Options->Reset Global Options...
- restart Oxygen
After the restart the plugin should set thee code templates.


Best regards,
Alex

[Lemesany]

Alex, thanks again for your help! I followed the steps you listed in your previous comment and am able to see the code templates. To answer an earlier question about XPR files, we wanted them because of the transformation scenarios in there but I was able to add those into the framework without XPR files, so that's no longer necessary.

The last thing I need for now is to add a custom schema to the framework. I can add this by pointing to an HTTP server and don't get an error, but I don't want to use this workaround. I can't seem to find the right structure locally and get the error about packing the framework root directory not just its contents. I made a resources folder in my structure and placed the *.sch file in there. I also tried copy/pasting from the oxygen dir's framework > dita > resources folder to mimic the structure and its contents. I still get this error. I wonder if the problem is in my framework specification "Validate" tab. If add the schema to the DITA scenario, is the location "${framework}/resources/schema_custom.sch" correct? I still want to use the other schemas to validate and they are listed as "${baseFramework}/resources/..". Is that correct or should the variable change as well?

Thanks again for all your help!! It's been fun working with all this stuff.

[alex_jitianu]

Hi,

I can't seem to find the right structure locally and get the error about packing the framework root directory not just its contents.

The framework root directory in the one that contains the *.framework file. This is the one that needs to be zipped. Anyway, if you can send me the zipped package on support@oxygenxml.com then perhaps I will see what's wrong with it.

If I understand correctly, this custom schema is a Schematron, and you've tried to edit the DITA validation scenario to use it.

If add the schema to the DITA scenario, is the location "${framework}/resources/schema_custom.sch" correct?

This location is correct if the file structure of your framework is something like this:

Code: Select all

{framewordDir}

--*.framework

--resources

----schema_custom.sch

I still want to use the other schemas to validate and they are listed as "${baseFramework}/resources/..".

You should leave this entries as they are. ${baseFramework} will be expanded to the location of the base framework (in your case the built-in DITA framework).

Best regards,
Alex

[Lemesany]

Alex, thanks for all of your help! it's working as expected. My problem was actually due to using a Mac while creating the zip files. Mac threw in some extra hidden folders that I couldn't see until I opened the .zip file in Eclipse and deleted them. The structure is now working and clean since I made the .zip in Eclipse. Thanks for all your help! Exciting stuff

[alex_jitianu]

Hi,

My pleasure! Others might create the archive on a Mac so I will add an issue to make a more robust detection of the framework. Thank you for sharing

Best regards,
Alex

[Lemesany]

Great! Here is what my structure was looking like when I pulled my Mac-made zip into Eclipse in case you're curious:

zip
-- _MACOSX
---- framework_customization
------ ._.DS_Store
-- framework_customization
---- resources
---- templates
---- .DS_Store
---- custom_dita_extension.framework

Deleting the _MACOSX folder and the .DS_Store file in the other folder worked.

[Lemesany]

Another question related to this...

Is it possible to have any transformations I add to the custom framework automatically appear in the "Transform with" dialog? Currently, I have to click the gear icon and select "Show all scenarios". I'd like them to automatically be associated and show in the "Show only the scenarios available for the editor". How do you associate a transformation to the editor?

[adrian]

Hello,

Is it possible to have any transformations I add to the custom framework automatically appear in the "Transform with" dialog?

What type of file are you transforming with ("Transform with")? What extension does the file have?

Currently, I have to click the gear icon and select "Show all scenarios".

That means your scenario is not for the type of file you are transforming.
You should make sure that the transformation you have created is of the correct type.
If you want to transform an XML file, make sure the transformation scenario is of the type "XML transformation with XSLT" (or "XML transformation with XQuery").

I'd like them to automatically be associated and show in the "Show only the scenarios available for the editor".

If you have correctly defined one or more association rules for the framework ("Document Type Association"), you can also check the default box for the scenario from the Transformation section in the "Document type" configuration dialog. All files that match the rules will have that scenario associated by default.

How do you associate a transformation to the editor?

Individual association can be done in the "Configure Transformation Scenario(s)" dialog. Check the "Association" box and press "Save and close".

Regards,
Adrian

[Lemesany]

Hello,

As a followup, your suggestions in the previous post worked.

I have a request to add the "Show extended toolbar" from the DITA Maps Manager to be enabled by default. When I select this option and export my options, there is nothing in the options.xml file makes this option selected automatically. Is this not controlled by a plugin and options.xml file?

Another question: The oxygen-sample-plugin-impose-options that I used for this originally was for 18.x. We are upgrading to 19.1 and I'm finding my 18.x still works for 19.1, but I'm wondering if it's wise to upgrade my impose options to 19.1, as well. If so, and some users are still on 18.x, would the plugin still work? I'm going to be doing some testing on that (I found this link: https://www.oxygenxml.com/maven/com/oxy ... e-options/ ) today but figured I'd ask in case your answers come faster

Thank you in advance!

[Radu]

Hi,

So:

I have a request to add the "Show extended toolbar" from the DITA Maps Manager to be enabled by default. When I select this option and export my options, there is nothing in the options.xml file makes this option selected automatically. Is this not controlled by a plugin and options.xml file?

There should be an option key called "dita.manager.extended.toolbar" with value "true".
Something like:

Code: Select all

<entry>

			<String>dita.manager.extended.toolbar</String>

			<Boolean>true</Boolean>

		</entry>

Indeed when exporting settings from Oxygen, Oxygen will not export it because we considered this is more of an user-related preference that people do not usually want to share with each other. But you can manually add it to the XML options file.

Another question: The oxygen-sample-plugin-impose-options that I used for this originally was for 18.x. We are upgrading to 19.1 and I'm finding my 18.x still works for 19.1, but I'm wondering if it's wise to upgrade my impose options to 19.1, as well. If so, and some users are still on 18.x, would the plugin still work? I'm going to be doing some testing on that (I found this link: https://www.oxygenxml.com/maven/com/oxy ... e-options/ ) today but figured I'd ask in case your answers come faster

Our options are basically keys with associated values. Usually such key,value mappings exported with Oxygen 18.1 should work with 19.1. Probably the other way usually also works (XML keys exported with 19.1 should work with 18.1). But we cannot guarantee this 100%, we seldom change the type of value returned by a key but we may do that from time to time. Usually in each Oxygen version we add new (key, value) mappings but this should be no problem for older versions of Oxygen as they should interpret only they keys that they know of.

Regards,
Radu

[Lemesany]

Adding that option manually did it. Thank you!

[Lemesany]

Hi there,

I have 2 custom frameworks and 1 plugin that get used daily by writers, and I update them about once every couple months. Is there a way I can track who is updating, or at least, how many people have updated?

For example if I have version 2.0.1 out for a couple months, then make a change and create v2.0.2, can I see how many people have installed the 2.0.2 update?

[Radu]

Hi,

We do not have such tracking in Oxygen, maybe you could enable some server side logging and see from what IP addresses the ZIP files referenced by the addon.xml are getting downloaded.

Regards,
Radu