Frameworks association rules

Post here questions and problems related to oXygen frameworks/document types.
emmam
Posts: 16
Joined: Sat Jul 28, 2012 11:41 am

Frameworks association rules

Post by emmam »

Hi all

I'm using frameworks for several TEI and epidocs projects so every root is TEI !
How to create an assocation that would give me the relevant framework for each project.
The simpliest way would be to use an attribute on the root element, but I'm not confortable at all with that option.
I also thought about using file names prefixes (something like : "prefix*.*") but doesn't seem to be possible at all and maybe would not accomadate any situation.
May be it would be convenient to have an association option with the files associated with a project or a folder...

What would you advice ?

emmanuelle
Radu
Posts: 8736
Joined: Fri Jul 09, 2004 5:18 pm

Re: Frameworks association rules

Post by Radu »

Hi Emmanuelle,

Here's a possibility:

So in the Oxygen Preferences->"Document Type Association" page you would have multiple "TEI P5-like" document types defined, each with its own functionality, all of them matching the same association rule.

Then from the bottom of the Preferences page you change the page to "Project Options" and then you uncheck/disable the TEI frameworks which should not apply to the current project.

Then you load another project and again for it you pass the page to project options and uncheck in it the TEI frameworks which should not match documents in the current project.

So each time you open a project, it would come with its own list of activated frameworks.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
emylonas
Posts: 10
Joined: Sat Feb 16, 2013 3:04 am

Re: Frameworks association rules

Post by emylonas »

Radu suggests using the project specific options to disable the frameworks that aren't relevant. This will work well with a group of steady encoders who have been taught to use projects. As a matter of fact, our initial efforts to provide Author mode frameworks consisted of a project file that the students click on and it is set up with all the necessary settings.

However, we would also like to make the framework available to encoders who contribute infrequently, or who may be working on their own. Explaining and setting up projects may not work for them.

In this case, it seems as if the only option is the attribute on the root element.

Is there any other option? I was thinking perhaps of a namespace prefix? What about information from the Oxygen processing instruction?

We can solve our problem for now either with the root element id or the project. Just wondering if there might be something more generalizable.

thank you.
Radu
Posts: 8736
Joined: Fri Jul 09, 2004 5:18 pm

Re: Frameworks association rules

Post by Radu »

Hi Elli,

If you edit a document type in the Document Type Association preferences page and try to add a new association rule to it besides the usual fields matching a root name, namespace, attributes and so on you also have a custom Java class matcher.

Basically if you create an extension of the API class ro.sync.ecss.extensions.api.DocumentTypeCustomRuleMatcher and you pack it in a Java JAR library which is added to the "Classpath" tab in the document type configuration dialog, you can refer to that custom implementation from the association rule.

Your custom implementation will receive this callback:

Code: Select all

  /**
* Check if the document type to which this custom rule belongs to
* should be used for the given document properties.
*
* @param systemID The system ID of the current file in an URL format with not allowed characters corrected.
* For example: "file:/C:/path/to/file/file.xml"
* @param rootNamespace The namespace of the root.
* @param rootLocalName The root local name.
* @param doctypePublicID The public id of the specified DTD if any.
* @param rootAttributes The root attributes. The attributes are DOM level 2
* and the namespaces are available for each one.
* @return <code>true</code> if the document type to which this rule belongs to
* will be used for the current file.
*/
boolean matches(
String systemID,
String rootNamespace,
String rootLocalName,
String doctypePublicID,
Attributes rootAttributes);
when Oxygen tries to determine if the opened XML document belongs to this particular document type association or not.

One of the parameters is the systemID URL location of the opened XML document. Maybe you can use this information to find out the name of the project folder in which the XML document is located and based on that to take a decision to match or not the document type.
Or using that location of the document you could parse it separately and find a certain processing instruction in it, something like:

Code: Select all

  public boolean matches(String systemID, String rootNamespace, String rootLocalName,
String doctypePublicID, Attributes rootAttributes) {
final boolean[] foundProperPI = new boolean[1];
if(systemID != null) {
XMLReader xmlReader = PluginWorkspaceProvider.getPluginWorkspace().getXMLUtilAccess().newNonValidatingXMLReader();
xmlReader.setContentHandler(new ContentHandler() {
@Override
public void startPrefixMapping(String prefix, String uri) throws SAXException {
}
@Override
public void startElement(String uri, String localName, String qName, Attributes atts)
throws SAXException {
//Break early, do not parse the entire document
//We are only interested in the PIs before the root
throw new SAXException();
}
@Override
public void startDocument() throws SAXException {
}
@Override
public void skippedEntity(String name) throws SAXException {
}
@Override
public void setDocumentLocator(Locator locator) {
}
@Override
public void processingInstruction(String target, String data) throws SAXException {
if("custom".equals(target)) {
foundProperPI[0] = true;
}
}
@Override
public void ignorableWhitespace(char[] ch, int start, int length) throws SAXException {
}
@Override
public void endPrefixMapping(String prefix) throws SAXException {
}
@Override
public void endElement(String uri, String localName, String qName) throws SAXException {
}
@Override
public void endDocument() throws SAXException {
}
@Override
public void characters(char[] ch, int start, int length) throws SAXException {
}
});
try {
xmlReader.parse(systemID);
} catch (Exception e) {
//Ignore.
}
}
return foundProperPI[0];
}

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
dreifsnider
Posts: 66
Joined: Thu Aug 30, 2018 10:06 pm

Re: Frameworks association rules

Post by dreifsnider »

Hi,

Apologies for bringing this thread back, but I'm curious if you have any recommendations for how I can extend the ro.sync.ecss.extensions.api.DocumentTypeCustomRuleMatcher class to match on .ditamaps located under a certain directory.

For example, I'd like to be able to match on a .ditamap that is located under a directory called "my-project". Here is a sample structure of this directory:

Code: Select all

 - my-project
   - documents
      - user-guide
         - en
            - user-guide.ditamap
         - ja
            - user-guide.ditamap
      - specifications
         - en
            - specifications.ditamap
         - ja
            - specifications.ditamap
I'd like to create a custom framework that matches on any ditamap located under the "my-project" directory so I can customize the transformation and validation scenarios, as well as the editor CSS.

Do you have any recommendations for how I can accomplish this? My skills with Java are unfortunately not robust enough to be able to accomplish this on my own.

Thank you!

Daniel
Radu
Posts: 8736
Joined: Fri Jul 09, 2004 5:18 pm

Re: Frameworks association rules

Post by Radu »

Hi Daniel,
On this callback method:

Code: Select all

public boolean matches(String systemID, String rootNamespace, String rootLocalName,  String doctypePublicID, Attributes rootAttributes) 
you receive the "systemID" which is an URL-like path pointing to the DITA Map in the form:

Code: Select all

file:/c:/path/to/my.ditamap
So at a minimum you could implement the DocumentTypeCustomRuleMatcher like this:

Code: Select all

  boolean matches(
      String systemID, 
      String rootNamespace, 
      String rootLocalName, 
      String doctypePublicID, 
      Attributes rootAttributes) {
    return systemID != null && systemID.contains("/my-project/");
  }
But for such a simple use case you do not need a DocumentTypeCustomRuleMatcher Java implementation, in the Oxygen Preferences->"Document Type Associations" page if you edit your framework configuration and look at the "Association rules" tab there is an association rule named "File Name", I think setting it to something like */my-project/* should also work.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
dreifsnider
Posts: 66
Joined: Thu Aug 30, 2018 10:06 pm

Re: Frameworks association rules

Post by dreifsnider »

Thank you very much for your reply Radu!

I haven't tried entering a file path with wildcards into the File Name field in the Association Rules tab, as my initial expectation was that it only accepted and acted on the file name. I will try this and report my findings here.

I will also save your example of implementing the DocumentTypeCustomRuleMatcher for future use cases.

Thanks again!

Daniel
Post Reply