[oXygen-sdk] RSuite Applet Integration: Managing Framework Details

[Oxygen XML Editor Support]

Hi Eliot,

As you know (but maybe it's useful to others on the list) a standalone 
installation of Oxygen comes with a "Document Type Association" 
Preferences page in which you can configure a document type which will 
be used for validating, editing, authoring certain XML documents (which 
match the document type). A document type contains the used DTDs, 
catalogs, CSS files + Author customizations (custom actions, Java 
extensions):

http://www.oxygenxml.com/doc/ug-oxygen/#topics/author-devel-guide-intro.html

For a standalone installation the DITA document type folder is located in:

> OXYGEN_INSTALL_DIR\frameworks\dita

An Author Component Project (used to build an applet) references a 
resource called "frameworks.zip.jar". That resource contains multiple 
zipped frameworks (like the DITA framework) packed from a standalone 
Oxygen installation.
So when the applet starts and loads a certain XML, it will find the 
document type (framework) which matches it and based on the associated 
document type it will provide the editing experience (used DTDs, CSSs 
for visual editing, Author actions).

Now you want to customize the DITA editing experience by replacing some 
actions like "Insert Conref", "Insert Image", "Insert crossref" from the 
DITA framework with your own implementations.

This can be done in two ways:

1) By modifying the DITA framework "dita.framework" from the standalone 
Oxygen installation and packing it in the "frameworks.zip.jar" with the 
Applet (probably your current approach).

2) Leave the DITA framework unmodified and perform the modifications in 
the Java code corresponding to the Author Component customization.
The Author Component Sample Project comes with a sample class 
"AuthorComponentSample" which creates the toolbar for editing XML documents:

AuthorComponentSample.reconfigureActionsToolbar()

The method uses the API:

WSAuthorComponentEditorPage.createExtensionActionsToolbars()

to request the component to create the toolbar exactly as it is defined 
in the DITA framework.

The returned swing JToolbar can be modified to replace some actions with 
your own, I came up with the following sample code:

 > List<JToolBar> tbs = authorPage.createExtensionActionsToolbars();
 > for (int i = 0; i < tbs.size(); i++) {
 >     JToolBar tb = tbs.get(i);
 >     int compsSize = tb.getComponentCount();
 >     for (int j = 0; j < compsSize; j++) {
 >         Component theComp = tb.getComponent(j);
 >         if(theComp instanceof JMenu) {
 >             //A drop down item which has items with actions inside.
 >             JMenu dropDown = (JMenu) theComp;
 >             int menuItems = dropDown.getMenuComponentCount();
 >             for (int k = 0; k < menuItems; k ++) {
 >                 Component item = dropDown.getMenuComponent(k);
 >                 if(item instanceof JMenuItem){
 >                     JMenuItem menuItem = (JMenuItem) item;
 >                     //JMenuItem
 >                     Action action = (Action) 
((AbstractButton)item).getAction();
 >                     String actionID = 
authorPage.getActionsProvider().getActionID(action);
 > 
if("Author/insert.cross.reference".equals(actionID)) {
 >                         //We have to replace it with something else.
 >                         menuItem.setAction(new 
AbstractAction("REPLACEMENT REF") {
 >                             public void actionPerformed(ActionEvent 
actionevent) {
 >                                 // TODO
 >                             }
 >                         });
 >                     }
 >                 }
 >             }
 >         } else if(theComp instanceof AbstractButton){
 >             AbstractButton button = ((AbstractButton)theComp);
 >             Action action = (Action) button.getAction();
 >             String actionID = 
authorPage.getActionsProvider().getActionID(action);
 >             if("Author/insert.conref".equals(actionID)) {
 >                 //We have to replace it with something else.
 >                 button.setAction(new AbstractAction("REPLACEMENT CONREF",
 >                         //Use old icon.
 >                         (Icon) 
action.getValue(AbstractAction.SMALL_ICON)) {
 >                     public void actionPerformed(ActionEvent 
actionevent) {
 >                         // TODO
 >                     }
 >                 });
 >             }
 >         }
 >     }
 >     allActionsToolbar.add(tb);
 > }

About the same thing could be done for the pop-up menu by setting a 
pop-up menu customizer.

So if you make small customizations to a document type, these can be 
made from the component Java code.
If you have quite large customizations to make, they will have to be 
made in the framework itself and then re-pack the framework to work with 
the applet.

Regards,
Radu

Radu Coravu
<oXygen/>  XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com

On 2/19/2013 5:05 PM, Eliot Kimber wrote:
> I'm adapting code originally written by my colleague Lukasz, who implemented
> against 14.0. I don't fully understand the details of how it all works, so
> groping in the dark a little bit.
>
> In our current framework file we provide custom classes for handling the
> various insert actions:
>
> <field name="operationID">
> <String>com.rsicms.rsuite.editors.oxygen.applet.extension.operations.InsertS
> ymbolOperation</String></field>
>
> One each for insert system, insert image, insert reference, and insert cross
> reference. The custom code is using server-side code to provide lists of
> things to select.
>
> These are the only changes to the OOTB framework, so if there was a more
> indirect way to set up this action bindings, that would be ideal.
>
> Please feel free to point me to the relevant docs. In addition to just
> trying to make this work, I'm also trying to work out the best overall
> engineering approach for building custom Oxygen integration plugins. Our
> expectation is that different clients will want different customizations
> depending on their doctypes and business rules, so I want to make sure it's
> as easy to do as possible, which means separating the configuration from the
> code as much as possible, of course.
>
> Cheers,
>
> E.
>