How to extend built-in frameworks

manojdcoder
Posts: 63
Joined: Thu Oct 29, 2020 12:01 am

How to extend built-in frameworks

Post by manojdcoder » Thu Dec 17, 2020 1:14 am

I would like to customize the built-in framework, for example

1. Extending DITA & DocBook Link Resolvers [1]
2. Configure certain options in framework (for instance enabling / disabling outline pane or certain tools)

I understand that I could download the original framework form Oxygen repo, make changes on specific files, create a jar for my custom link resolver, reference the classes in framework file etc., But over the time it would be difficult to merge my changes into latest from Oxygen manually. Is there a proactive way, something like adding the framework as dependency and override the defaults rather than modifying original files?

[1] topic22151.html#p60246

cristi_talau
Posts: 341
Joined: Thu Sep 04, 2014 4:22 pm

Re: How to extend built-in frameworks

Post by cristi_talau » Thu Dec 17, 2020 9:28 pm

Hello,

In version 23.0 we added support for a "Framework Extension Script" [1]. This way you can "programmatically" modify the builtin framework. I added at the end of the post the script that we used to generate the framework for Lightweight DITA.

For changes you make in code, you can extend the default ExtensionsBundle subclass of that framework and override some of the methods. Then, package it in a JAR file and add the JAR to the classpath using the script mentioned above.

For the outline configuration, it is also looked up in the classpath. To override the one in the base framework, just add the outline configuration file in a folder and add that folder to the classpath of your framework.

Best,
Cristian

[1] https://www.oxygenxml.com/doc/versions/ ... cript.html

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
  Script file that generates "dita-lw.framework"
-->
<script xmlns="http://www.oxygenxml.com/ns/framework/extend"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.oxygenxml.com/ns/framework/extend http://www.oxygenxml.com/ns/framework/extend/frameworkExtensionScript.xsd"
  base="DITA">
  <name>Lightweight DITA - Topic</name>
  <description>Darwin Information Typing Architecture</description>
  <priority>Normal</priority>
  
  <associationRules inherit="none">
    <addRule publicID="-//OASIS//DTD LIGHTWEIGHT DITA Topic//EN"/>
    <addRule rootElementLocalName="topic" publicID="*-//OASIS//DTD XDITA Topic//EN*"/>
    <addRule rootElementLocalName="topic" publicID="*-//OASIS//DTD LW DITA Topic//EN*"/>
  </associationRules>
  
  <classpath inherit="all">
    <addEntry path="${framework}/lw/resources/" position="before"/>
    <removeEntry path="${framework}/refactoring/"/>
  </classpath>
  
  <documentTemplates inherit="none">
    <addEntry path="${frameworkDir}/DITA-OT3.x/plugins/org.oasis-open.xdita*/oxygen_templates/LW (Lightweight) DITA/topic-lw"/>
    <addEntry path="${frameworkDir}/templates/sample-project"/>
  </documentTemplates>
  
  <validationScenarios>
    <addScenarios href="lw/resources/dita-lw-validation.scenarios"/>
    <removeScenario name="DITA"/>
    <defaultScenarios>
      <name>LW-DITA</name>
    </defaultScenarios>
  </validationScenarios>
  
  <author>
	<authorActions>
	  <removeAction id="paragraph"/> 
	  <removeAction id="listitem"/>
	  <removeAction id="orderedList"/>
	  <removeAction id="section"/>
	  <removeAction id="insert.table.column.after"/>
	  
	  <removeAction id="insert.code.block"/>
	  <removeAction id="insert.code.phrase"/>
	  <removeAction id="surround.uicontrol"/>
	  <removeAction id="surround.filepath"/>
	  <removeAction id="insert.menucascade"/>
	  <removeAction id="insert.equation"/>
	  
	  <removeAction id="insert.table"/>
	  <removeAction id="insert.simpletable"/>
	  <removeAction id="insert.table.wizard"/>
	  <removeAction id="table.join"/>
	  <removeAction id="table.split"/>
	  <removeAction id="convert.cals.table.to.simple.table"/>
	  <removeAction id="convert.simple.table.to.cals.table"/>
	  <removeAction id="show.table.properties"/>
	  
	  <removeAction id="insert.related.link.2.topic"/>
	  <removeAction id="insert.related.link.2.file"/>
	  <removeAction id="insert.related.link.2.web.page"/>
	  <removeAction id="insert.concept"/>
	  <removeAction id="insert.task"/>
	  <removeAction id="insert.topic"/>
	  <removeAction id="insert.reference"/>
	</authorActions>
  
    <css>
      <removeCss path="${framework}/css/edit/alternate-syntax-highlight.css"/>
      <removeCss path="${framework}/css/edit/alternate-table-show-colspec.css"/>
      <removeCss path="${framework}/css/edit/alternate-hide-draft-comments.css"/>
      <removeCss path="${framework}/css/hints/hints.css"/>
      <removeCss path="${framework}/css/actions/actions.css"/>
      
      <addCss path="${framework}/lw/css/lw.css" position="after"/>
      
      <addCss path="${framework}/lw/css/labels.css" title="+ Labels" alternate="true"/>
      <addCss path="${framework}/lw/css/print.css" title="+ Print ready" alternate="true"/>
    </css>

    <toolbars>
      <toolbar>
        <addAction id="subscript" anchor="underline" position="after"/>
        <addAction id="superscript" anchor="underline" position="after"/>
        <addAction id="section" anchor="insert.media" position="after"/>
        
        <addAction id="insert.table2" anchor="insert.table.row.below" position="before"/>
        
        <removeGroup name="${i18n(section)}"/>
      </toolbar>
    </toolbars>
    
    <contextualMenu>
      <addAction id="insert.table" anchor="insert.table.row.below" position="before"/>
      <submenu name="${i18n(paste.special)}">
        <removeAction id="paste.content.key.reference"/>
      </submenu>
      
      <submenu name="${i18n(table)}">
        <addAction id="insert.table" anchor="insert.table.rows.custom" position="before"/>
      </submenu>
      
      <submenu name="${i18n(reuse)}">
        <removeAction id="push.element"/>
        <removeAction id="create_reusable_component"/>
        <removeAction id="insert_reusable_component"/>
      </submenu>
  
      <submenu name="${i18n(table)}">
        <addAction id="insert.table2" anchor="insert.table.rows.custom" position="before"/>
      </submenu>
      
      <submenu name="${i18n(insert)}">
        <addAction id="insert.table2" anchor="insert.image" position="before"/>
      </submenu>
    </contextualMenu>
    
    <menu name="Lightweight DITA">
      <removeAction id="push.element"/>
      <removeAction id="create_reusable_component"/>
      <removeAction id="insert_reusable_component"/>
      
      <submenu name="${i18n(paste.special)}">
        <removeAction id="paste.content.key.reference"/>
      </submenu>
      
      <submenu name="${i18n(table)}">
        <addAction id="insert.table2" anchor="insert.table.row.above" position="before"/>
        <separator anchor="insert.table.row.above" position="before"/>
      </submenu>
    </menu>
    
    <contentCompletion>
      <authorActions>
        <addAction id="insert.table2" inCCWindow="true" alias="${i18n(table.wizard)}"/>
      </authorActions>
    </contentCompletion>
  </author>
</script>

manojdcoder
Posts: 63
Joined: Thu Oct 29, 2020 12:01 am

Re: How to extend built-in frameworks

Post by manojdcoder » Fri Dec 18, 2020 5:39 am

For the outline configuration, it is also looked up in the classpath. To override the one in the base framework, just add the outline configuration file in a folder and add that folder to the classpath of your framework.
Do you have an example? I'm using the web-author-component-integration[1] project.

[1] https://github.com/oxygenxml/web-author ... ntegration

cristi_talau
Posts: 341
Joined: Thu Sep 04, 2014 4:22 pm

Re: How to extend built-in frameworks

Post by cristi_talau » Fri Dec 18, 2020 12:13 pm

We have here documentation about configuring the outline: https://www.oxygenxml.com/doc/versions/ ... -pane.html .

Post Reply