Legal publishing uses a lot of attributes, and CCH publications are some of the richest legal reporting available. When we converted to SGML nine years ago, one of the first things our users requested was a way to modify attributes globally outside the Arbortext Editor Modify Attributes dialog. Often they have been required to open XML files in Notepad, or Edit as XML Source to change attributes in large files, which led to error and was very time-consuming. The project got on the schedule in 2007, and we started the initial analysis, starting with what language to write the tool in, and how to create the interface.
Because this tool requires a good deal of querying the DTD, we decided to write it in ACL. The interface requirements included making it impossible for a user to create invalid XML. For example, the tool needed to remove #FIXED attributes from the attribute list, and, if the user wanted to delete attribute values, the tool needed to remove #REQUIRED attributes from the list. While the Arbortext Object Model (AOM) exposes only a namelist of required attrs, these attribute types are exposed by the tag_attr_required() and tag_attr_fixed() ACL functions. Dozens of such calls that query the DTD or a given Object ID (oid) are easily accessible in ACL.
Because this tool requires a complex dialog box with 24 dialog controls, and because we wanted to give the users a beautiful dialog box, we needed a way to create the dialog that would allow us to drag and drop dialog elements, resizing and changing appearance in real time. We used ACL Designer, a powerful but unsupported interface design tool that, with a conversion program that ships with Arbortext Editor, can be used to create XUI dialog boxes with a wide variety of controls. The ACL dlgitem functions allow granular management of dialog item controls.
As Spider-Man knows, "With great power comes great responsibility." The Global Attribute Find-Replace tool can save a huge amount of time, but it can also destroy a lot of content very quickly. The danger of using the tool incorrectly is mitigated by two layers between the core find-replace function and the user: a business-logic layer, which allows granular control over what the user can and can't do; and a dialog layer, which allows XML-aware control over user input. Because of this tiered approach, it was easy to develop another tool on top of the core function.
This presentation will show you
- an end-to-end example of Requirements Gathering, Technical Design, and Application Development for a complex XML tool
- powerful XML and dialog functions in ACL
- a "tiered" approach to application development
- tips on controlling dialog behavior
- XUI tips
- ideas for interface design and implementation
This project involved a great deal of requirements gathering, meetings, testing, signoffs, and ongoing user input, to come to fruition. The process worked, and we now have a valuable addition to Editor functionality that saves a great deal of time and error.
About the Presenter
Todd Hicks, Wolters Kluwer North America Global Platform Organization, has been working in legal publishing for 20 years, and with Arbortext for ten years. In high school he ran the old printing press, and knew then that he wanted to be involved in publishing. An English major in college, he became a proofreader for CCH, Incorporated, and quickly moved to technical writing, and then to programming, especially for publishing and user interfaces. When CCH converted to SGML, he wrote Wordbasic/Onmimark scripts; when CCH started using Arbortext Adept Editor, he learned ACL, Java, and Javascript, built dozens of tools, and designed the infrastructure for the editor and its interface with Information Manager, our CMS at the time. He now leads a team of Editor programmers to build tools and infrastructure for Arbortext Editor and its interface with Documentum at Wolters Kluwer. He has presented three times at Arbortext conferences.
Watch the Video
Recorded: October 2010
More Resources
- Arbortext Community Voices Podcast: Interview with: Todd Hicks, Wolters Kluwer
Tweet Roundup
In case you missed attending the session live, the event had a live Twitter stream.
Read the tweets
| @SingleSourcing: #arbortext #ptcuser T.Hicks "An ACL Tool to Find and Replace XML Attribute Values" |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Todd has built dozens of Arbortext-based tools to improve the lives of his users at Wolters Kluwer. |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Wolters Kluwer - leader in global services and publishing - using Arbortext and Documentum |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: my dream is to have the very best Arbortext implementation in the universe |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: we build tools for our users, we want to increase efficiency and decrease errors |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: We want to make it easy for users to do the right thing and very hard to do the wrong thing |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: the most important thing in my life is when our Editors come up and say, "it doesn't do this, we need it to.." |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: We needed a tool that would globally find and replace attribute values |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: our Editors didn't want to have to learn regular expression syntax but had need for very specific find/replace |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: we have an ongoing conversation with our users and what they want to do |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: tools like this are a good idea for any kind of organization that uses XML |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: people's eyes glaze over when you say XML, so anything that makes it easier to do what they want to do is good |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I new I had to have code that interacted with the open file and had a complex GUI initiating dynamic behavior |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: we wanted a tool that worked with any DTD or schema and had no business logic in it at all. And it does! |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I took advantage of ACL Designer, a GUI designer for Arbortext |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: ACL Designer was built on Galaxy, complete with springs and struts. Pretty steep learning curve, but visual |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: UI: Act 1 is on left, Act 2 in middle, Act 3 on right, finale at the bottom.. (in western UI design) |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I like to put something at top that shows the effect of their actions, at the bottom the action buttons |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: took me 2 months to build it, but we had the requirements nailed down and a design that the users accepted |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: XUI editor now comes OOTB with Arbortext and it will show you the dialog dynamically |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: We say "AE" for "Arbortext Editor". I can just type "AE" to launch the editor on my desktop |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: "Editor" is a job title in my company |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: we have arbortext customized for WK, buttons that we designed ourselves to launch tools we built into AE |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: To prevent people from accidentally wrecking content, we passworded the global find and replace tool |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: changing the value of the 'pub' attribute on all 'xref' elements -- just use our global find/replace tool |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Action can be limited to specific elements, attributes, and values, in an easy UI for our Editing team to use |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: They were concerned about accidents, so we built in several layers of "undo" |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Now we're getting into some ACL code. Here's how to build a custom dialog box in Arbortext Editor |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Step by step tutorial on building custom tools in Arbortext. It's easy to do, anyone can do it. Very powerful |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Epic is the former name of Arbortext Editor. Before that, it was called "Adept" (Expert!) |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: in your code, you need an object that is the dialog itself, you can identify, use, and interact with it |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Here's how to read the ACL functions and understand how to use them... |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: the next thing you want to do is to have a function for adding callbacks for your controls. |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: a mistake I made early on was adding the "()" but it just needs the function name. |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: dialog item callback is something ACL hands you. When you specify it, it knows what event happened to call it |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: list of elements.. get a callback for each control. |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Sample Callback function code |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: there was a lot of fear for this, so we added "scary" warning boxes |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: ACL (Arbortext Command Language) is great for talking to XML |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: ACL lets you do things in the open file and interact with it, ask the DTD questions, and talk to the markup |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: here's some sample code. You can find out all kinds of stuff by just asking the DTD |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I'm filtering out the Documentum namespace attributes, barring changes to those by the users |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: This is a tree walker. (sample code) |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Here's another little trick: create little functions to do what they do to simplify and encapsulate actions |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: XML ACL sample code to modify markup in the live document in Arbortext Editor |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I wanted to give you the tools you'll need to do it yourself. You can get a dialog like this! |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: It's a pretty clever little pile of code, dialog boxes that keep you awake when you do things in them |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: you want it to do more than say "uh huh" like people reacting to you |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: This saves people a lot of time -- 200 changes by hand? or hiring someone to write a script? do it on the fly! |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: Learn ACL, make good code and good interfaces, and you will have... Smooth Sailing! |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: If you have an application, and it has an API, then use it! You'll be in line with the company developing it |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I went to Ann Arbor for ACL training as well as using the documentation |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I went to Ann Arbor for ACL training as well as using the documentation |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I went to Ann Arbor for ACL training as well as using the documentation |
| @SingleSourcing: #arbortext #ptcuser T.Hicks: I went to Ann Arbor for ACL training as well as using the documentation |
You might also be interested in...
MathFlow, MathType, and MathML in Technical Publishing
Autumn Cuellar & Robert Miner, Design Science
ACL Preliminaries
Brandon Ibach
Basic authoring automation in Arbortext
Lynn Hales
How DITA Transformed Content at Nikon Precision [Arbortext User Meeting]
Debra West-Maciaszek, Nikon Precision
Key concepts
arbortext editor, community, ui customization
Filed under
About the Arbortext User Group
Single-Sourcing Solutions coordinates logistics and donates both financial and administrative support to help Arbortext Users connect through meetings and social media channels. The Arbortext User Group has a blog and a youtube channel.
Trackbacks/Pingbacks