Prevent Image With Placement Break From Nested Under "Inline Elements"

[dreifsnider]

Hi,

My team is using a custom DTD that constrains some of the default DITA elements. We've also used it to set the default placement attribute value to break for images, since the majority of our images should be break.

Additionally, to assist both our technical writers and non-technical writers who are using a combination of Oxygen XML Author and Oxygen XML Web Author, we'd like to prevent users from inserting an image with placement=break inside of an inline element (for example <p>, <ph>, <li>, etc). Inversely, we'd like only image with placement=inline to be allowed in an inline element.

I've tried to enforce this constraint using the DTD, but it doesn't seem possible without specializing the image element, which we're hoping to avoid. Therefore, I'm wondering if we would be able to implement this using any of Oxygen's features, such as Content Completion and/or Author Actions.

Thanks!

Daniel

[Radu]

Hi Daniel,

One way to look at this problem would be to create a custom Schematron rule as part of a DITA framework configuration:
https://blog.oxygenxml.com/topics/shari ... rules.html
The Schematron validation rule would show an error after someone inserted an image with break placement in a paragraph. The rule could also maybe have a quick fix attached to it so that the end user can press the quick fix and remove the attribute.

Another approach with actions, let's say you want to replace the existing Insert image" action with your own. Our "Insert Image" dialog is quite complex, you would need to re-implement the dialog, sounds like a lot of work. We have some Java APIs which would allow calling some custom code after the image is inserted in order for example to remove that attribute from the image element if the image is placed in inline context.

Regards,
Radu

[dreifsnider]

Hi Radu,

Thank you for your reply!

We've thought about using Schematron and will probably go this route on the XML Editor side, which our technical writers are using.

However, we also have many content authors who use XML Web Author to write content in DITA format. Our main hesitation with Schematron on the Web Author side is that many of our content authors who are using Web Author are not familiar with DITA and Schematron. We were hoping for a more "seamless" solution for these users without requiring them to take any additional actions when they want to insert an image.

We're also considering modifying our DITA-OT HTML plugin to treat break and inline images differently according to what the parent element is. I was hoping to solve this in the source DITA content itself rather than modifying the plugin but this seems like the most viable solution for now.

Thanks again!

Daniel

[Radu]

Hi Daniel,
I assume you have your own server installation of WebAuthor. A DITA framework customization containing a custom Schematron validation rule, once installed on the WebAuthor server will be used automatically for all users working in the web browser with XML content. So the users would not need to do anything, they would start receiving these validation errors when working with the content.
Regards,
Radu

[dreifsnider]

Hi Radu,

Thank you for your reply! Yes, we have our own server installation of Web Author. We are also using custom DITA frameworks as well as Schematron validation rules in Oxygen XML Editor.

The primary issue for us is having Web Author users take additional action to resolve the invalid content simply when inserting an image. These users are most familiar with Word and other non-structured forms of writing and so we're concerned that these users will either become confused when their document becomes invalid simply after inserting an image, or that they won't know how to fix it.

We were hoping to take advantage of Oxygen's schema-aware content completion mechanism to automatically insert the image under the correct parent element without requiring any further action on the user's behalf.

Thanks again!

Daniel

[Radu]

Hello Daniel,

Please see some remarks below:

The primary issue for us is having Web Author users take additional action to resolve the invalid content simply when inserting an image.

This can be done with our Java extensions. So using our Java APIs you can intercept insertion events and decide what to do with them. Do you have a Java developer in the team willing to work on this? If so we can try to outline some steps for you to take.

We were hoping to take advantage of Oxygen's schema-aware content completion mechanism to automatically insert the image under the correct parent element without requiring any further action on the user's behalf.

The <image> element is allowed to be inserted both in paragraphs and between them. So Oxygen's generic insertion mechanisms will not help here.

Regards,
Radu

[dreifsnider]

Hi Radu,

Apologies for my delayed reply.

Unfortunately, we don't have a dedicated Java developer on the team although I have been trying to pick up some Java development skills. Any help would be appreciated on this so please feel free to outline some steps.

I am now investigating converting our DTD based schema into RELAX NG, which Eliot Kimber informed me is able to handle this kind of constraint (constraining an element's parent based on the element's attribute value). I am hopeful that Oxygen's generic insertion mechanism would be able to use the RELAX NG schema to identify the correct place to insert the image based on it's placement value.

Thanks!

Daniel

[Radu]

Hello Daniel,

Unfortunately, we don't have a dedicated Java developer on the team although I have been trying to pick up some Java development skills. Any help would be appreciated on this so please feel free to outline some steps.

There is an API interface which can be extended: https://www.oxygenxml.com/doc/versions/ ... ndler.html
For DITA XML editing there is already an extension for it named "ro.sync.ecss.extensions.dita.DITASchemaAwareEditingHandler" so probably some custom implementation could extend the DITASchemaAwareEditingHandler and override the "DITASchemaAwareEditingHandler.handlePasteFragment(int, AuthorDocumentFragment[], int, AuthorAccess)" method so that in the context of inserting image elements inside paragraphs it could take certain actions like deciding to insert the image after the paragraph.

I am now investigating converting our DTD based schema into RELAX NG, which Eliot Kimber informed me is able to handle this kind of constraint (constraining an element's parent based on the element's attribute value). I am hopeful that Oxygen's generic insertion mechanism would be able to use the RELAX NG schema to identify the correct place to insert the image based on it's placement value.

I think we need to build a sample XML + RNG model first to see if this works, I'm taking inspiration from this chapter:
https://relaxng.org/tutorial-20011203.html#IDAC0ZR

So if I have this XML document

Code: Select all

<?xml-model href="test.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<root>
    <para><image placement="break"/></para>
    <image placement="inline"/>
</root>

and this RNG document:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
  <start>
    <choice>
      <ref name="root"/>
    </choice>
  </start>
  
  <define name="image">
    <element name="image">
      <attribute name="placement"><value>break</value></attribute>
      <ref name="attlist.image"/>
      <text/>
    </element>
  </define>
  <define name="inline.image">
    <element name="image">
      <attribute name="placement"><value>inline</value></attribute>
    </element>
  </define>
  <define name="attlist.image" combine="interleave">
    <empty/>
  </define>
  
  <define name="para">
    <element name="para">
      <zeroOrMore>
        <choice>
          <text/>
          <ref name="inline.image"/>
        </choice>
      </zeroOrMore>
    </element>
  </define>

  <define name="root">
    <element name="root">
      <ref name="attlist.root"/>
      <zeroOrMore>
        <choice>
          <ref name="para"/>
          <ref name="image"/>
        </choice>
      </zeroOrMore>
    </element>
  </define>
  <define name="attlist.root" combine="interleave">
    <empty/>
  </define>
</grammar>

If open and validate the XML document in Oxygen we get two errors, one that the image with placement break is used in the paragraph and one with the placement inline being used outside of the paragraph. So validation seems to work.
Now to test the Author editing mode smart insertion, I copy to the clipboard the "<image placement="break"/>" element from the Text page, then I switch the XML document to the Author visual editing mode, right click inside the paragraph and "Paste special->Paste as XML". And it seems Oxygen pastes the element although after it's pasted, the element is reported as invalid. This means that (as I kind of expected) Oxygen's schema aware insertion strategy does not take attributes present on the element into account, it only checks that the element is valid in that location and not that if its attribute with a specific value is valid on the element which would be inserted. If you want I can register an internal issue for this but I'm skeptical we will find time to fix it in the short term, such cases are very rare, actually for now you are the only one asking for something like this to work at insertion time.

Regards,
Radu