Best way to deploy Global Options?

[Frank Ralf]

Hi,

We've defined some code templates that we want to deploy to other team members. What is the best way to do so?

We already use a custom DITA framework, which is regularly updated. However, code templates are only stored externally when exporting oXygen's Global Options. I've already looked at Customized Default Options and using a project file looks promissing. However, I'm not sure whether these deployment mechanisms will override each user's individual settings with every (automatic) update.

Kind regards,
Frank

[Radu]

Hi Frank,

As long as the user makes no direct modification to the Oxygen Preferences->Code Templates page the customized default options should work. Once the user has made a modification to the preferences page, the default options will not be used anymore.

Another option is to use a plugin (which can be installed via an add-on install site) which imposes a set of options to the application the first time the application starts.

Regards,
Radu

[Frank Ralf]

Thanks for the pointers, Radu.

Frank

[Radu]

Hi Frank,

Also, if you only needed these code templates in the Author editor mode, instead of code templates you could have edited the custom DITA frameworks and create equivalent Author actions, then add them to the content completion window (or to toolbars, menus, so on).

Regards,
Radu

[Frank Ralf]

Thanks for this additional pointer!

Frank

[HomeGoods]

Allow me to disturb.

I'm going to take these pair of actions (from Customized Default Options):

If you want to control exactly which options page will be stored in the default options file, you can choose to attach them to a project file (.xpr file extension)

copy the XML options configuration file to the [Oxygen-install-folder]/preferences.

A couple of questions:

• Some preferences pages (Global, Data Sources, Network Connection Settings) do not have Project Options switch. They can't be distributed as the default values via .xpr?
• Could you elaborate a bit more about [Oxygen-install-folder]/preferences? I have created default-options.xpr file. Am I supposed to create a [Oxygen-install-folder]/preferences directory and copy the default-option.xpr file there?

[alex_jitianu]

Hello,

It's always a good thing clarify any uncertainties in the documentation, so you're not disturbing at all!

- You are correct. If some pages can't be stored at project level then you wont be able to use an *.xpr file. In this case you'll probably be better with exporting the global options. Perhaps we should mention this aspect inside the topic...
- Yes, you have to create a folder named preferences inside the Oxygen installation folder. Afterwards, copy default-option.xpr inside this preferences folder.

Best regards,
Alex

[HomeGoods]

Thank you, Alex. It worked, but in a sort of confusing way.
After placing .xpr in the preferences folder and restarted oXygen, GUI displays as if the customized defaults were project options. (i.e. Project Options radio button is selected on Options - Preferences pages.)
Is this by design?
This behavior makes it hard to see the real project options which come from the currently opened project.

And just curious,

- Yes, you have to create a folder named preferences inside the Oxygen installation folder. Afterwards, copy default-option.xpr inside this preferences folder.

what happens if we put multiple .xml/.xpr files there?

[alex_jitianu]

Hello,

The fact that the Project Options radio button is selected was not an intended behavior. Just an annoying side effect that we didn't notice. I'll add a request to investigate the issue.

If you put multiple *.xpr, *.xml file inside the preferences folder, only one of them will be loaded. Which one, depends on the operating system and the order in which it provides the children of the folder.

Best regards,
Alex

[HomeGoods]

The fact that the Project Options radio button is selected was not an intended behavior. Just an annoying side effect that we didn't notice. I'll add a request to investigate the issue.

Thanks. Please let me know once it's resolved or if more information is needed.
The feature itself, unless this confusion, looks very useful.

If you put multiple *.xpr, *.xml file inside the preferences folder, only one of them will be loaded. Which one, depends on the operating system and the order in which it provides the children of the folder.

Thanks for the clarification. This foreseeable ambiguity was primarily why I first couldn't figure out from the users guide whether "[Oxygen-install-folder]/preferences" is a folder or a file.

[Frank Ralf]

Hi,

Is there a way to use this default options mechanism outside of oXygen's installation folder? Most of our writers don't have write access there so deploying a default project file into a - to be created - /preferences folder won't work.

Is it (in the case of DITA) perhaps possible to deploy this together with a DITA-OT plugin and use oXygen's Integrator script to move the default project file to the correct location?

Kind regards,
Frank

[alex_jitianu]

Hello Frank,

1. The fact that the writers don't have write access to oXygen's installation folder is not necessary a bad thing. They are not intended to put the default options file there. A system administrator should put the file there to make sure the writers are working in the right environment (using the correct default options, in this case).

2. But if the previous approach is not an option, you can also give the path to the default options file as the value of the com.oxygenxml.default.options system property. The value can be an URL so the default options file could reside on a remote server making sure all writers will connect to it.

You can take a look on how to set a system variable for Oxygen. Another way to set this variable would be from an Workspace Access plugin. One could deploy this plugin as an add-on to let the writers install it more easily.

3. Another possibility. from an Workspace Access you can use the Java based API to directly import an options file. This is a little different than providing a default options file. By providing defaults you are allowing the writer to change an option (if he decides he wants it). By importing an options file you will override any change the writers has done to those options.

Best regards,
Alex

[Frank Ralf]

Hi Alex,

Many thanks for this detailed description of the available options. I will have a closer look and report back.

Kind regards,
Frank

[chrizzbee]

good morning

i also look for an option to define the location for the options file. how and where do i specifiy this for the oxygen eclipse plugin? couldn't quite figure it out from the docu and what was posted here ...

many thanks.
chris.

[alex_jitianu]

Hello Cris,

The Customizing Default Options topic from the Eclipse User guide describes the procedure for the Eclipse distribution.

Best regards,
Alex

[chrizzbee]

dear alex

thanks for the pointer to the eclipse-plugin help. have a little trouble here ...

what i did so far: i exported the global options as default.xml and put them in a folder preferences in [eclipse_install_dir]\plugins\com.oxygenxml.author_17.0.0.v2015072912.

this worked nicely. job done.

now i was looking for a way to define the location for default.xml and to have it not within the preferences folder but somewhere else.
to do so, your help says, put the path in the config.ini with the system property com.oxygenxml.default.options and make use of "file:\"

so, whatever i define here, whatever path, either with variable @user.home or @config.dir, does not work – default.xml is not recognized.

what am i missing here?
thanks a lot for guidance.

br
chris.

[Radu]

Hi Chris,

From what I checked right now you can either use an absolute URL or file path or a path relative to the Oxygen plugin folder. So it does not support variables.
We'll try to improve this behavior in a future version.

Regards,
Radu

[chrizzbee]

Hi Radu

i tried to configure the default.xml into the configuration directory with this:

com.oxygenxml.default.options=file\:@config.dir/default.xml

so this does not work. if i use the example from your docu:

com.oxygenxml.default.options=file\:@config.dir/../default.xml

this works. so the default.xml ends up in the eclipse install directory and is loaded correctly.

i tried to use UNC paths as well but wasn't successful, eclipse doesn't like that. can you confirm this?

thanks
chris.

[Radu]

Hi Chris,

About why this works:

Code: Select all

com.oxygenxml.default.options=file\:@config.dir/../default.xml 

I know you took this example from our user's manual, I'm not sure why it was there in the first place, we'll try to update our user's manual contents.
Oxygen does not know what @config.dir is, it considers it to be a folder name. But because you also use "../" (up one level) in the path, the "../" is merged with @config.dir and they consume each other.
So the perfect equivalent of that value is this one:

Code: Select all

com.oxygenxml.default.options=default.xml 

as you can also use relative file paths (and they are considered relative to the Oxygen plugin folder).

Regards,
Radu

[chrizzbee]

not sure, but in my eclipse environment only this seems to work:

Code: Select all

com.oxygenxml.default.options=file\:@config.dir/../default.xml or

com.oxygenxml.default.options=file\:@config.dir/../some_folder/default.xml

what does not work is:

Code: Select all

com.oxygenxml.default.options=default.xml or

com.oxygenxml.default.options=file\:default.xml or

com.oxygenxml.default.options=file\:/../default.xml or

com.oxygenxml.default.options=../default.xml

[Radu]

Hi Chris,

About what does not work:

1)

Code: Select all

com.oxygenxml.default.options=file\:default.xml or

com.oxygenxml.default.options=file\:/../default.xml or

those are not quite relative paths. So those constructs should be avoided.

2)

Code: Select all

com.oxygenxml.default.options=default.xml

From what I tested, Oxygen will try to find the "default.xml" in the main Oxygen plugin folder (the one which contains the lib directory).

3)

Code: Select all

com.oxygenxml.default.options=../default.xml

From what I tested, Oxygen will try to find the "default.xml" in the folder which is the parent of the main Oxygen plugin folder.

Regards,
Radu

[chrizzbee]

hi radu

now it becomes clearer! thanks for these pointers.

regards
chris.

[tjarvas]

Hi,

I am also trying to import a set of code templates. I am using the eclipse plugin version of the Oxygen Author. In my special case, using a default options is not enough, because these code templates should be stored in a different eclipse plugin (where other customer specific resources are stored) and these code templates could be updated by the customer. When this happens, we deploy a new version of this plugin to the update site, so every user could get the new version of the plugin and their code templates should be updated.

I managed to import a set of code-templates by using the PluginWorkspace.importGlobalOptions(File) method. That is good, because I can guarantee that it runs and updates the preferences and if that file only contains the "code-templates" preference, then it only updates it, while it keeps the other settings customized by user. This is an important requirement for us, that's why I cannot use the default options, because the user will save his own settings, so the default options won't be used anymore.

However I have still one issue: If the user defined his own code template, then the importGlobalOptions method overwrites it. Is is possible to update only those code-templates, where their key is matching (or add if doesn't exists), but keep the additional code-tamples defined by the user?

I know, that the user's own preferences are stored in the workbench's .plugins\org.eclipse.core.runtime\.settings\com.oxygenxml.author.prefs. I can find everything in there, but not in the same xml format, but in a serialized format as the value of "Author_Options_Tag" key. One option would be for me, to parse this file somehow and merge the user defined code templates with the global code templates coming from my plugin, but I don't really like this solution.

Is there any Java interface which can help me to solve this issue?

Thanks,
Tamas

[alex_jitianu]

Hello Tamas,

Is is possible to update only those code-templates, where their key is matching (or add if doesn't exists), but keep the additional code-tamples defined by the user?

Unfortunately we don't have API for getting the value of an option. User options might contain sensitive data and that's why we decided not to offer such an API.

know, that the user's own preferences are stored in the workbench's .plugins\org.eclipse.core.runtime\.settings\com.oxygenxml.author.prefs. I can find everything in there, but not in the same xml format, but in a serialized format as the value of "Author_Options_Tag" key.

If you use org.eclipse.ui.plugin.AbstractUIPlugin.getPreferenceStore() you should get the same XML format as the options file you imported:

Code: Select all

String xmlOptionsContent = getPreferenceStore().getString("Author_Options_Tag")

You could then compare the code templates and merge if necessary.





Best regards,
Alex