Sharing Frameworks and Projects

[kirkilj]

Frameworks and projects are both described as a means for sharing customizations/configurations with multiple users. Many of our needs would be addressed by a custom framework, but there are many preference options that look like they can only be shared through a project's xpr file.

Do both need to be done? Frameworks can be shared via the add-on manager and checked for updates. Project sharing examples include using the subversion capability, which is of course a different path.

What are the best practices for keeping end-users up to date with any customizations and configuration changes we develop in-house? Can projects be shared via the Add-on manager?

We already use subversion in our development shop. In the Framework scenario, we would use subversion internally and then deploy our releasable version to our intranet server, from which the Add-on manager should be able to pick it up and install it. Does the framework payload need to be in a zip file?

I realize I'm asking several questions in a scatter-shot fashion.

John

[Radu]

Hi John,

You could share both options and custom frameworks with a project. In the Oxygen Preferences->"Document Type Association / Locations" page you can specify additional frameworks directories using editor variables like ${pd} which gets expanded to the current project's location. This preferences page can also be passed completely to project level which would mean that a project would come with both your custom "frameworks" folder and with options which instruct Oxygen to use them in addition to Oxygen's frameworks. So users could update the frameworks using SVN instead of having an update site.

If you choose the path of creating add-ons for your frameworks it works like this:

http://www.oxygenxml.com/demo/AddonsSupport.html

but you would also need to bundle a set of default options to be used with each user's Oxygen:

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

Regards,
Radu

[kirkilj]

Thanks Radu,

I'm going to build a quick test of your suggestion in your first paragraph to make sure I've got it.

As far as frameworks go, let me know if the following would be a reasonable approach for packaging customizations from the framework side of things.

If we want to leave the stock Oxygen frameworks alone so that we can pickup any improvements that Syncrosoft makes to them in future Oxygen releases, could we package ALL of our framework-level customizations into one "CompanyX" framework whose priority would be set to the highest level? Any DITA Map, DITA Topic, SVG, XSLT or other customizations we make could be bundled into this one custom framework. Our custom CSS files would use relative references or absolute references using the ${frameworksDir} variable into the stock DITA, DITA Map, etc. framework folders to import the dita.css and map.css files into our own custom CSS files that would perform the imports at the beginning of each stylesheet and then override any framework properties that we want that diverges from the stock functionality.

I'm assuming this could work for CSS, but is there any framework customization functionality that would not work with this approach?

John

[Radu]

Hi John,

If you took the decision of using the approach of adding your framework to the Additional Frameworks Directories list, then the ${frameworksDir} variable will expand to your additional frameworks directory instead of Oxygen's frameworks directory. But you can still use something like ${oxygenInstallDir}/frameworks/dita to make references to resources in our bundled DITA framework.

But we do not have a specific mechanism to extend a certain framework and just add some individual customizations. We plan to consider this for a future version though.

You either copy the entire contents of our ${oxygenInstallDir}/frameworks/dita and start modifying it as your custom framework, this meaning that you have forked it completely and on each Oxygen release if you want to benefit of new changes you will have to compare what you've got with what we packed.

Or indeed from your custom framework you make as many references as possible to resources located in the ${oxygenInstallDir}/frameworks/dita. But a framework is not just about linked resources, it defines and binds custom actions in its framework configuration file (${oxygenInstallDir}/frameworks/dita/dita.framework) and if we add additional actions you will still not benefit from them unless you compare your dita.framework with ours on each release.

Regards,
Radu

[kirkilj]

Is there any reason we couldn't include project files in the framework folder we package up on the update server? We could instruct our users to open our default project within that folder once the update is complete and they restart Oxygen. From then on, Oxygen will open that project automatically for all future invocations. In this manner, we wouldn't have to bother with subversion login changes on the server for every new user. I suppose that in this scenario, the ${pd} and ${framework} variables would resolve to the same framework asset folder. The xpr file would include a reference to the .framework file in the same directory.

Is this thinking correct?

I have a presentation I've prepared to describe our options to our development group tomorrow. If you like, I could email it to your support email address and you can take a gander. I took stills from your video about Add-on configuration and annotated a few for our internal discussion.

John

[alex_jitianu]

Hi,

Your assumptions are correct. Just to make sure I've followed. The project is in the framework dir and the Additional frameworks directories option page is saved at project level and specifies the location like so: ${pd}/../

A possible issue that comes to mind is the fact that when the users must install a new framework version the project file will get overridden (since it's located in the framework folder). If the user has linked resources in the project file then it might get frustrated. Or maybe this is an intended behavior...

It would be great if you could send us that presentation so we can get a better understanding about requirements and use cases.

Best regards,
Alex

[Radu]

Hi,

Starting with Oxygen 16.0 which was released a couple of days ago you will have the possibility to extend a document type configuration in order to automatically benefit of all changes made to the base configuration in your extension.

Regards,
Radu