Custom Editor Variable using xpath_eval and doc function

[kirkilj]

I created an external tool that would open a specific web page on an internal server for the maven artifact specified in a pom.xml file at the root of an Oxygen project.

Here's an excerpt of the pom:

Code: Select all

<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<groupId>com.acme.xyz</groupId>
	<artifactId>nswtc-vsg</artifactId>
	<version>2.0.0-SNAPSHOT</version>

The command line in the external tool is:

Code: Select all

cmd /c start https://repo.acme.com/techpubs-mvn-dependencies/com/acme/xyz/${artifactId}

$artifactId is a custom editor variable that I defined as:

Code: Select all

${xpath_eval(doc('${pdu}/pom.xml')/project/artifactId/text())}

I just get a null string returned or sometimes xpath_eval parsing errors. I know that many xpath features are not allowed unless it's executed from an XML context, but I thought that the doc function would establish the context needed.

By the way, Is the text() function needed in this context?

=============================================

I just tried to come up with a minimal example to confirm I can evaluate a variable with a simpler XPath expression. With an external tool as:

Code: Select all

 cmd /c echo "${fred}"

and a custom editor variable ${fred} as:

Code: Select all

${xpath_eval(concat('fr','ed'))}

It works fine, and I get the following:

Code: Select all

Started:  cmd /c echo "fred"
fred
Process ended with exit code: 0

I'm using <oXygen/> XML Editor 22.0, build 2020030607

Best Regards,

John

[Radu]

Hi John,

As the pom.xml document has a namespace, your xpath needs to match elements in that namespace, right now you are matching elements in no namespace.
So maybe you can relax the xpath like this:

Code: Select all

${xpath_eval(doc('${pdu}/pom.xml')/*:project/*:artifactId/text())}

to match any element with a certain name in any namespace.
Also the text() is required for now, if it is not provided Oxygen will serialize as a result the entire XML node which is not quite compatible to what the XSLT does.

Regards,
Radu

[kirkilj]

Thanks Radu.

That did the trick!

[kirkilj]

In general, it looks like I may want to use the doc-available function first to fail gracefully if a file isn't present. Perhaps something like:

Code: Select all

${xpath_eval(
      if (doc-available('${pdu}/pom.xml')) 
      then doc('${pdu}/pom.xml')/*:project/*:artifactId/text()
      else 'INVALID_ARTIFACT_ID' 
   )
}

but Oxygen reports a syntax error at line 6 column 1, which is the final end curly brace. My quotes and delimeters appear to be balanced, so I can't determine what's causing the error.

By the way, it would be handy in the Custom Editor Variable dialog to have an eval button for each editor variable when there's at least one Oxygen function being used in its definition. Perhaps it would show the evaluated value in the current context when the button is pressed or just show the evaluated value next to the expression, like a variable watch in a debugger. Right now I'm using an external tool to echo the value of the variable to the console.

[Radu]

Hi,

I can reproduce the problem but using the value on one line seems to work:

Code: Select all

${xpath_eval(if (doc-available('${pdu}/pom.xml')) then doc('${pdu}/pom.xml')/*:project/*:artifactId/text() else 'INVALID_ARTIFACT_ID' )}

so it's probably a bug in the way in which we parse the multi line value, I will add an internal issue to investigate this.

About providing some kind of editor variables watch window, I feel your pain, usually to debug cases like yours I create an XSLT stylesheet, pass a parameter to it and the value of the parameter is an expression with editor variables I have configured in the transformation scenario dialog.
So I also added an internal issue for this. We do have APIs to resolve editor variables so this could even be done with a plugin which contributes a side view. Besides pasting editor variable expressions in that side view, one thing the plugin could also do would be to listen for keyboard focus and when the keyboard focus is moved to a text component which contains editor variables, it could automatically report the evaluated result in the side view. Hopefully we'll get some interns this summer and maybe we can work on small useful plugins like this one.

Regards,
Radu

[kirkilj]

First, I need to wipe away the puddle of drool on my desk. Those features would be glorious to have.

The driving force in wanting to increase the use of xpath_eval in many different Oxygen customizations is that we're planning on moving from Ant/Java style properties files for build options and metadata to using the Ant [https://ant.apache.org/manual/Tasks/xmlproperty.html]XMLProperty[/url] Task so that we can use Oxygen's xpath_eval function to retrieve any property that other tools may define, query, and update in a DocSet's repo.

We also want to be able to provide a multi-layered inheritance of properties at many levels such as company, business group, product family, product, platform, and document, and allow for each property to support either a top-wins or closest-wins inheritance/override strategy independently.

The initial use case is to move our current set of External Tools that we now must duplicate and update in every product's Oxygen project files. Those external tools would be much easier to update and distribute if they were ported to custom toolbars or menus in our framework. One category of such tools is to launch pertinent web pages on various internal servers that pertain to the DocSet, such as the:

• Jenkins page that contains the jobs for the project
• Gerrit or Gitlab server pages for the project's repo
• Artifactory server pages where Jenkins deposits the rendered docs so R&D can pick them up from their build toolchain
• Jira JQL query to view all documentation tickets for the product
• etc.

It should make it easier for the writer to use Oxygen as their base application without having to switch to other tools to keep browser bookmarks for any related web apps they use.

Although most writers follow our recommended conventions for naming and locating related resources, we can't count on the fact that we can take the repo name, branch name, productID, or other metadata and construct the proper URL. So we need the user to be able to override these if necessary. Oxygen's Custom Editor variables would work for Oxygen, but not as easily with other parts of our build pipeline in their Oxygen project files. (I know that a project file is itself and XML file, but I don't think it would be best to make it the primary source of such metadata.) The required set of Editor variables could however access the XML properties using xpath_eval. Any Oxygen customization with xpath_eval support would be able to leverage the same properties. Other XML tools could use the same files for their purposes. We could run transforms and all sorts of other operations and queries on them if necessary. We may eventually create a simple Author mode for such files to make it easier on the writers... unless someone else has already created an addon for Oxygen to support XMLProperties.

I just used XMLStarlet for the first time to get at XML content from Bash scripts, and having properties in XML files would give our scripts access to the same XMLProperty set.

Do you see any flaw in this approach or other opportunities?

[Radu]

Hi John,

Thanks for describing your use case. For now I do not have any suggestion, if you stumble over ideas about improvement ideas in Oxygen to better support your use case, please tell us.
Btw, the initial reported problem will be fixed in Oxygen 22.1 which we plan to release in a couple of weeks if all goes well.

Regards,
Radu

[alex_jitianu]

Hi John,

In Oxygen version 22.1, that was released yesterday, the 2 characters that form ending sequence for an editor variable - )} - can have any number of white spaces characters (including newlines) in between.

Best regards,
Alex

[kirkilj]

Hi Alex,

Thanks for updating me. I did notice that the same expression that surfaced this issue for me is now failing after the update. I didn't have time to investigate on Friday, but I'll check tomorrow at the latest.

John Kirkilis
Nokia

[kirkilj]

Actually, what's now broken in 22.1 vs. 22.0 is that this External Tool command errors out:

Code: Select all

cmd /C mvn compile -Dt=${ask('Choose a target:', combobox,( ${xpath_eval(string-join(fn:for-each (doc('${pdu}/build.xml')/project/target/@name, function($target) {concat("'",$target,"'",':',"'",$target,"'") } ) , ';' ) )} ), 'main')}

with

Code: Select all

An error occurred while expanding the 'ask' editor variable, at line 1, column 258. Please check the syntax of the editor variable: 'cmd /C mvn compile -Dt=${ask('Choose a target:', combobox,( ${xpath_eval(string-join(fn:for-each (doc('file:/C:/Users/kirkilis/Documents/gitworks/sbc/build.xml')/project/target/@name, function($target) {concat("'",$target,"'",':',"'",$target,"'") } ) , ';' ) )} ), 'main')}'.

It also fails in 22.1 if I put the entire ${ask} expression in a custom editor variable and refer to it from the External Tool command, as in:

Code: Select all

cmd /C mvn compile -Dt=${get-target}

with the error:

Code: Select all

An error occurred while expanding the 'ask' editor variable, at line 1, column 195. Please check the syntax of the editor variable: '${ask('Choose a target:', combobox,( ${xpath_eval(string-join(fn:for-each (doc('${pdu}/build.xml')/project/target/@name, function($target) {concat("'",$target,"'",':',"'",$target,"'") } ) , ';' ) )} ), 'main')}'.

which is right after ';'

[alex_jitianu]

Hi John,

I'm sorry for the inconvenience... Starting with version 22.1 the sequence ) } from within the XPath is considered to be a suffix for the editor variable. This generates a snow ball effect of bad variables parsing. We'll fix it for the next in a maintenance build.

As a workaround, you can tweak a bit the xpath expression to avoid that bad sequence (please note the )[1] }):

Code: Select all

${xpath_eval(string-join(fn:for-each (doc('${pdu}/build.xml')/project/target/@name, function($target) {(concat("'",$target,"'",':',"'",$target,"'"),'')[1] } ) , ';' ) )} 

Best regards,
Alex

[alex_jitianu]

Hi John,

Although you probably went with the workaround and solved this issue on your side, for closure, I want to mention that in the newly release Oxygen 23 we addressed the root cause and the sequence ") }" no longer breaks the editor variables parsing.

Best regards,
Alex

[kirkilj]

Thanks for the circling back and letting us know. It's one of the small things Syncrosoft does that shows a level of follow-through and closure that is rare in the industry.

We'll leave the work-around in until everyone is on v23.