General XMetaL Discussion

XMetaL Community Forum General XMetaL Discussion Customization object? How can I use a form?

  • queshaw

    Customization object? How can I use a form?

    Participants 2
    Replies 3
    Last Activity 1 year, 7 months ago

    The documentation for xmetal developer 12 says you can associated a form with a “customization object”. But, I see nowhere where it says what a customization object is, or how to create one. Can you elaborate?

    Ultimately, I want to present a dialog box to the user and get data from fields in the form to use from a macro, which I take it is the one form that scripts take. I don't see how binding the form to XML could work for me.


    Derek Read

    Reply to: Customization object? How can I use a form?

    Have a look at the topic “Associate a form with a customization object”.

    That discusses how to add added to the CTM file that tell XMetaL Author which form to associate with which element, whether it is embedded or to be launched as a modal dialog and various other settings.

    You can also launch a form using an API but the most common method (if you need to associate the form with an element) is to make the associations with the CTM file. The topic “Executing a form as a modal dialog in XMetaL” discusses that and provides the simplest example of launching an XFT as a modal form from script.

    The topic “Sample forms” lists the forms provided with the Journalist with brief descriptions (fully understanding what each does is best done by using the Journalist sample and examining it's MCR, CTM and XFT files). Hard to say which one would be nearest to what you want to do.



    Reply to: Customization object? How can I use a form?

    The topic “Associate a form with a customization object” is what I'm referring to. I don't see anywhere a description of how to create a customization object. If a CTM file is a customization object, visual studio tells me I can't add a CTM file to an XMetaL application solution.

    The samples seem to be tied to a DTD, I am not doing anything related to a DTD and don't want to bind a form to an element in the XML document being edited. I am so far not getting how a form is associated with program logic by looking at the samples.

    The documentation for Application.CreateFormDlg shows DoModal() being called on the object returned. Aside from not wanting a modal dialog box, what object is returned? How do I access the value of forms set in the dialog box after it's been dismissed?


    Derek Read

    Reply to: Customization object? How can I use a form?

    Still guessing a bit but here's an example that might help.

    There's an example macro in the Journalist.mcr file called “Insert ULink” that launches a form, lets the user input a Description and URL, and then generates some content in the XML based on that input.

    My sample below reuses that form but doesn't tie it to a document (in the original it isn't tied to any document either really, it's just that the Journalist sample is the only one to use it). Instead of inserting the values into the document like the Journalist sample does this sample merely checks the values and displays them.

    Not sure what you want to do with your values, but in this example they are now strings and you can do whatever you like with them.

    //XMetaL Script Language JScript:
    var formPath = Application.Path + “\Forms\ULink.xft”;
    var dlg = Application.CreateFormDlg(formPath);

    //as long as you don't set the form object to null
    //(in this example that's “dlg”)
    //you can access the controls on it like so:
    if (dlg.DoModal == 1) { //user clicked OK button*
    var desc = dlg.URLDesc.Text;
    var url = dlg.URLLink.Text;
    Application.Alert(“Description: ” + desc + “n” + “URL: ” + url);
    dlg = null;

    *For a form to return 1 when an OK button is pressed you need to set ButtonType for the button to “OK” (as in this form).
    When the user dismisses a dialog using the built-in close button on a form -1 is returned.
    When the user dismisses a form using a button with ButtonType set to “Cancel” then 2 is returned.

    You should null any references to the form eventually (before XMetaL shuts down, but the safest place is in the same script that launched the form so you know for sure the reference is gone). Windows Script Host (JScript and VBScript) does do garbage collection but the timing is not predictable. XFT's are running as part of an external control (a COM DLL) and COM references need to be cleaned up to make sure the software can properly shut down.


  • You must be logged in to reply to this topic.

Lost Your Password?