Pages: « 1 2 3 4 5 6 7 8 9 10
 on: April 30, 2018, 07:10:57 PM 
Started by Marvin - Last post by Derek Read
If this was for any DTD or W3C Schema other than DITA then it would make sense to try to figure this out. In that case you have full control over everything that is happening because the scripts you have created (your MCR files) are the only ones you need to worry about having conflicts with.

However, making modifications to the DITA authoring functionality is mostly not supported. CSS changes are supported, as are some configuration changes for CTM settings. However, because the entire DITA authoring system is implemented as an XMetaL customization that is running its own scripts, the only supported method for extending that functionality is by making modifications to a limited number of pre-defined scripting extension points. These are primarily meant to be used to add or change functionality for specialized DITA DTDs, but can also be used to alter some behaviours for the standard DITA DTDs.

They are limited to the following:

None of these will help you. I list them here because it may help to understand what is supported.

Specialization Extender:

  • OnSpecializeCommandBars - for adding or modifying toolbars and menus
  • OnSpecializeContextMenu - for adding or modifying context menu items (right click menu)
  • makeUniqueId - for changing how ID values are constructed (the format) for the DITA auto-id feature, by defaultthe Windows GUID generator is used
  • doProperties - provide a way to stop the context menu item for the DITA "Properties" dialog from being listed in the context of specific element(s)
  • OnGetDisplayNameForDomain - provides control over the items listed for "Domains" in the DITA options dialog

A .js file needs to be placed in the XACs folder for the particular DITA DTD you wish to extend this functionality for. There is a specific naming convention for that filename and there is a specific naming convention for each of the prototype functions (that allow for code extension) that need to be defined inside that file.

A demo file is included here:
C:\Program Files\XMetaL <version>\Author\DITA\XACs\<DITA DTD Version>\ditabase\

To enable this functionality the file must be renamed to match the DTD filename in the same XACs subfolder for the particular DITA DTD you want to extend. So, for example, enable the demo file by renaming it ditabase_ditabase.js
Documentation for the file itself is included in inline comments inside the .js file listed above.

You may want to step through the DITA authoring code in a debug session to see what it does for any of the items you want to extend in order to understand how the existing code works. Without knowing that it is easy to break existing functionality. Two exceptions are possibly makeUniqueId and doProperties, which are quite simple and easily demonstrated by the provided demo code.

If you need to make modifications to a document programmatically, that might be done in a way that does not necessarily conflict with the DITA authoring functionality, but it would be difficult to support this. The APIs you are using in your sample code are ones that mimic behaviours that an author (end user) can do themselves, and so it might be possible to create a macro that does not get in the way of the DITA authoring functionality (which includes automatically setting DITA id attributes). To answer this for certain it would be best to provide a full (in your case not really working) sample to XMetaL Support to see if there is something that can be done. Again, this is unsupported so there are no guarantees, but it might be possible. XML file + MCR that includes whatever code you have so far and as much of a description as possible.

Keep in mind that "supported" also means something you create today will continue to function with all future versions. That is always true (short of introduced bugs that are later fixed) for all XMetaL APIs. However, it isn't true for the DITA functionality because of the potential for conflict, that the functionality might change in the future, and that it isn't documented to have been written to function in any specific way (unlike the XMetaL APIs). So, something created today that changes how the DITA authoring functions might work in a specific version but isn't guaranteed to work in the future (the only ones we plan to continue to support are those extension points listed above).

 on: April 30, 2018, 04:55:26 PM 
Started by Marvin - Last post by Marvin
We have a structure like this:

<parent ID="12345">

We make changes to this structure programmatically, but our DITA scripts have some issues when "track changes" is turned on and only grandchild-level nodes are changed.
For this reason, we'd like to delete and recreate the whole "parent" node - so that "track changes" will show the whole node as updated, and not just the contents (even though actually, only the contents were changed).

I'm quite confident my code does just that now:

var newParentNode = '<' + rng.ContainerName + '></' + rng.ContainerName + '>';




But unless there's a bug in my code, the newly created "newParentNode" receives the same ID as the old one, which again means that only the descendants of the parent node were changed.

Is there a way to force the creation of a new ID for the parent node, or is there some other bug in my code?
Thank you.

 on: April 30, 2018, 04:46:39 PM 
Started by Marvin - Last post by Marvin
Thanks, this was very valuable advice.

XMetaL Developer broke our connector, so that wasn't really an option. Using "debugger;" I can finally step through scripts, even if it's a bit annoying that I have to restart XMetaL Author every time I change something.

I could also solve the problem with <?xm-replace_text?> by simply removing it from the xref mini-template.

Thank you again!

 on: April 24, 2018, 02:20:50 PM 
Started by Marvin - Last post by Derek Read
Sounds like your customization is quite extensive already.

It is possible that checking for an empty value in that event might fail. I'm not aware of that limitation but it is possible.

I can't think of any *new* features in 13 that would help in this specific case. There might be other features you could take advantage of though. There are many other events and there are over 1000 APIs.

Perhaps you might try implementing something in On_Before_Document_Validate. You could walk the document in there (similar to the logic in your On_Document_Open_Complete macro) and look for issues, then display messages to the user. I could imagine a UI that takes the user directly to an <xref> that has issues and shows them your existing xref dialog, but perhaps with a "please fix this" message. The same XFT could probably be duplicated and modified so it contains slightly different prompts.

If you have Visual Studio or the Windows Script Debugger installed you can launch a debugging session by adding the keyword "debugger" into your script. This will allow you to step through your code and use the features that debugger provides.

If you have XMetaL Developer this is quite a bit simpler as you can launch XMetaL Author Enterprise from within Visual Studio in this case in debug mode, put breakpoints in your scripts, and gain all the advantages of Visual Studio's debugging system that way (including in some cases step over, step out, etc). The Programmers Guide and Customization Guide are written assuming you have XMetaL Developer (they ship with that software) but you can download CHM copies from our website if you don't have or don't want to use XMetaL Developer.

 on: April 24, 2018, 08:25:42 AM 
Started by Marvin - Last post by Marvin
Thank you for the detailed reply (btw, we also have a support agreement, but I figured someone else might find this useful, so I decided to just ask her instead).

We're already using the <?xm-replace-text?> PI, like so:

<xref href="#to-be-resolved" id="xref_F767C1E1..."><?xm-replace_text Cross reference?></xref>

I'm not sure how it's implemented, but doubleclicking on that actually opens a dialog that lets you select something.
But we have issues with some users editing the xref contents (label), believing they could change the target, or deleting the label alltogether (thus creating an empty element, which causes problems for us elsewhere).

To make sure they don't change existing xref elements, this works like a charm:

<MACRO name="On_Application_Document_Open_Complete" lang="JScript" hide="true"><![CDATA[
var elemName = "xref";
var rng = ActiveDocument.Range;
while(rng.MoveToElement(elemName)) {
rng.ReadOnlyContainer = true;

As for the "business rule validation," I have found this great example and have adapted the code to our needs, more or less.
Here is the relevant code:

<MACRO name="On_Check_Element_SimpleContent" key="" lang="JScript" hide="true"><![CDATA[
var cd = Application.CheckData;
var elem = cd.Element;
var name = elem.tagName;
if(name == "xref") {
var value = cd.Value;
if(value == null || value == "") {
cd.ValidationMsg = "Empty xrefs are not allowed. If the xref is marked as read-only, please delete it and create a new one.";

But unfortunately value is always "" (empty string).
Can this be related to the <?xm-replace_text?> PI? Maybe the macro doesn't even see the contents?

The code is quite difficult to debug as I basically have to resort to message boxes and the likes. If I could step through it line by line and inspect variables, it would be much easier. I guess there's no way to achieve that?
I also couldn't even extract the properties from the variables at runtime (JSON.stringify(elem) etc.).

And like I said, we're currently using XMetaL Author 9, but we're working on upgrading to version 13. Are there any new features that would make handling this easier?

Thank you.

 on: April 23, 2018, 02:40:38 PM 
Started by Jaadelman - Last post by Derek Read
I see. Please submit a support case to XMetaL Support including any files needed and as much detail as necessary to make it easy to reproduce.

 on: April 23, 2018, 02:37:23 PM 
Started by Jaadelman - Last post by Jaadelman
The version of XMetal we are using is 11 and with Internet Explorer 11.

 on: April 23, 2018, 02:22:40 PM 
Started by Marvin - Last post by Derek Read
The event On_Update_ElementList (and associated APIs) allow you to change or restrict what is displayed in the Element List, so I don't think that's what you want.

You want to add additional validation requirements that cannot be defined in the DTD. We tend to refer to these as "business rules" (though I don't know if that term is actually used anywhere officially). However, it sounds like you also want to guide the user so they are unlikely to see a validation error. Both of these are doable.

The simplest method to guide a user to enter text is to use the <?xm_replace-text?> PI. The difference between this an a normal PI is the way it is displayed and the fact that the entire PI is selected when click on, allowing the user to type over it.

You can use these PIs inside a document template (the files in the Template subfolder) or inside the "mini template" for a particular element.

The mini template can be used to create a chunk of XML to insert when the user inserts an element from the Element List. This is defined for each element in the CTM file. Whatever is in the mini template is inserted instead of just the element. If there is content that must always be inserted for a particular element you can include that in the mini template for the element as well, including text, child elements and their children and/or text, and/or attributes and their values.

Another method might be to pop up a dialog when the user inserts the <XRef> element and then have that dialog guide the user into creating something acceptable, perhaps by simply asking them to fill in a text form and checking to see that they entered something or that they entered something that matches a particular format. However, as an <XRef> implies a URL or path of some kind you might also display a "browse to file" dialog and use the path they pick, or maybe ask the user to copy the address from web browser to the clipboard and then read that into the dialog, something else?

XMetaL Author supports its own form format: XFT. You create these in the XMetaL Forms Layout tool included with XMetaL Developer. Then you hook up the form to either display as a popup or embed it inline in the document (for a particular element) by setting the appropriate settings in the CTM file associated with the DTD.

You can also pop up a dialog inside the On_Click or On_Double_Click events (fired when the user clicks in the document) using the CreateFormDlg() method.

The Journalist customization has a number of form examples (as does the DITA author functionality, though these are typically written in much more complex fashion so that a single XFT morphs how it looks in order to allow it to be reused for multiple elements and situations). The following Journalist elements either trigger the display of an XFT form or show an embedded XFT form when the element is inserted:

Yet another approach (one that you might want to include even if one of those above is also implemented) would be to use the event On_Check_Element_SimpleContent. This runs whenever the document is validated (ie: if the user requests it via F9 or during save or open). In here you can check the PCDATA content for an element and create a corresponding custom error message if your requirements are not met. This means the user needs to insert an <XRef> put in the wrong content (or in your case no content) then they are told about it when they validate or save (just like any other validation issues). This way, if the user somehow gets past your guide and manages to create something that violates your rule (Plain Text editing is the easiest, or perhaps in another piece of software) this code would still catch the issue.

The On_Check_Attribute_Value is a similar event that that lets you check attribute values according to your own business rules.

The XMetaL Developer Customization Guide has information on all of these things.

Keep in mind that XMetaL Author has a feature called Rules Checking that other products don't have. Most products only validate documents (at various times) showing you what is wrong with them after the issue has been introduced. The rules checking feature in XMetaL Author attempts to stop someone from creating an invalid document in the first place. It does this through various means: by listing only valid elements in the Element List (for the current position in the document), by stopping people from pasting in invalid elements, by stopping you from dragging and dropping content to places where it will be invalid, by stopping you from deleting elements (which is not always possible), by stopping you from setting bad attribute values, etc. This feature works automatically based on the definitions in the DTD or XSD, which also means the only way to get it to function is to make modifications to the DTD or XSD.

 on: April 23, 2018, 10:13:25 AM 
Started by Marvin - Last post by Marvin
We curently use XMetal Author 9 (yes, we're working on upgrading to a newer version) and have some "XRef" elements we don't want to allow to be empty.

From what I've read, DTDs don't support that restriction (only XSD schemas do).
Also, it would be nice if users could get immediate feedback when they move the selection away from the XRef element, and not only when they save the document, which could possibly be much later.

I have tried to use the On_Update_ElementList event for this, but I can't seem to figure out where to go from there:
It seems like you can't even open message boxes, so I struggled to even see what was happening (or if my macro was called at all).

Any help would be highly appreciated.

 on: April 18, 2018, 03:23:14 PM 
Started by lchiriac - Last post by Derek Read
Here are some things to try:

1. Navigate to another website instead to see if the issue is limited to something Google is doing. Your screenshot suggests Google is serving up some code that is giving you issues.
2. Navigate to an HTML page you have stored on disk that you've created yourself. C:\temp\mytest.html or something, then put nothing into that HTML file except very basic HTML and no scripts and see if that renders.
3. Load directly into IE (and specifically not Edge which is an entirely different engine and not embedded when you use Shell.Explorer).

I'm fairly certain you would see the same IE version reported for embedded copies. If you want to try to check that you would probably need to create an HTML page that contains script that displays the value for window.navigator.userAgent, then load the page into the Resource Manager (as #2 above).

It sounds like you are dealing with this with Tom through email. I think we should try to limit the communicate for this to that one pathway.

Pages: « 1 2 3 4 5 6 7 8 9 10
email us