Adding Custom Actions to OxygenXML Frameworks

[00:00:01.730] - Liz Fraley

Welcome to the TC Dojo from Single-Sourcing Solutions, the TC Dojo is a tech comm community that is driven by you. You choose the topics and we find the experts. Today it's just me, I'm going to show you some things that I learned about Oxygen. I put an e-book out about--first who's me, I'm actually a Computer Scientist, I have my B.S. in computer science from the University of Maryland College Park. I have two degrees in English. Also, I founded two companies, one of which is a nonprofit, I am invested in our community in our technical communications community, this is our fourth year of the TC Dojo and it's our second webinar system like this, I created the TC Camp, which has spun off as it's own nonprofit now, and that's all about learning and all about us. We invest in our communities, we enable people around us and we're very economical with not just our money, but our customer's money as well. Sure, we could do projects and throw it over the fence, but this is more fun. We teach you what we learned because it's hard enough to figure things out in the first place, right. So last year I put out three books, one of which was the Oxygen Book, and it is free for download, you can get it no charge. It's the same topic we're covering today, and there were eighty downloads the first day. I put it together because I was learning this stuff and no one else had posted on it anywhere really and when I asked everyone in my network who've been using Oxygen, I've been using it for almost 20 years now.

[00:01:40.400] - Liz Fraley

Everybody pointed to the same one or two people and this knowledge just wasn't everywhere. So we put the Ebook together simply because we figured people wanted to know it and with eighty downloads that first day. I think we got that right. The link is there I'll bring the links back again sometime soon toward the end of the session. But in the meantime, I'm going to go through the basics and if you have questions, be sure and type them into the question window as we go. Since it's just me today we're going to answer questions at the end. So put them in there when you think about them and here we go.

[00:02:14.300] - Liz Fraley

So what are custom actions, well, in Oxygen, these are operations that can be triggered upon some kind of context and you can define what that is. Most of it happens, or at least what I'm going to talk about today happens in author mode. When your author is doing something, say you want to update all the IDs in the document because they've cloned the document they were working on, they're just going to change it a little bit. So, you know, you need to change all the IDs in that file, you can make a little script that does that and the author can trigger it on demand as they see fit. Or you can do it as part of some other automated process. So it's very--it's actually a really cool system and when you look at how Oxygen is structured and how they envision how everything works together, once you understand that, it becomes a lot easier to figure out what you want to do. There're already a lot of custom actions that already exist, but you can create your own too and the four that are the most useful, at least from my perspective, that I've seen are the XSLT, the XQuery, the XQuery Update and JavaScript. You can use any of those languages to do something within the document, in the window as you see it in Oxygen, and it will do whatever you've decided you're going to do in that programming language.

[00:03:33.950] - Liz Fraley

All right, for the most part, for custom actions, you want to start by extending your DOCTYPE because everything is tied to the DOCTYPE and the framework, if you are doing heavy customization, that's a good idea to customize your framework and have that isolated separately so that you can control updates to it and your plugins and anything else that you're working on and it's fairly straightforward to extend the DOCTYPE, it doesn't change your--well, it doesn't change how you operate, but the way you do it, it's pretty simple, you go to Options > Preferences, you extend your document type, you can add an action to it, and then, in the end, you'll add that action to the toolbar, the menu, and that's pretty much all you're going to have to do to make it work. It's really very simple once you understand how it works. So let's take a look at the preferences window and I'm going to show you a couple of things that are keys to remember.

[00:04:37.060] - Liz Fraley

First, it's in this left-hand half in the Preferences window, right? So you're going to--and you're going to get to know this really well. If you're building these custom actions, you're going to go into preferences, you're going to click that and you're going to come here and the first thing you do is you extend your doctype, whatever type it is. In my example, I'm using DocBook just because it's simple and it was easy to do, for example purposes, but any of these doctypes are fair game and there's a lot whole bunch of them, right. There's a great big set of doctypes here. You can do it for any of them. You might want to have a little bit of help if you're extending a full framework and implementing it separately, but you can actually figure all of that out and if you contact the folks at Oxygen, they are super fantastic guys and they are really responsive and they want to help you so you can always get in a lot of extra help from them. I know, I have, all right. So next thing up, so now that we know where this is and where you're going to come back to this over and over again, you're going to go to preferences window, you'll look at your doctype, you'll save it you'll check it out, you'll see your toolbar is working, you'll come back in and you're at your things again. So you'll get really familiar with this and use that little edit button in the middle once you've got it existing, you'll edit it over and over and over again so get used to this view. From there, once you have done that and you click that edit button right, options, preferences, document type association, your document type edit button.

[00:06:05.080] - Liz Fraley

Pretty much you're looking at three steps from this window forward, you're going to select the author tab because what we're doing is for the author's benefit, right? We're doing custom actions in the author window you're going to select an action in the left-hand navigation and I'll show you in a minute and then there's two things. One, you're going to create actions and two, you're going to fix or edit actions if they aren't quite doing what you think they were going to do, right. OK, so let's take a look at that document type window, that's what this looks like. This is the document type window and I have the big pieces already highlighted in red, the keys are--so here's the author tab up at the top. We have named and described our doctype we are storing it somewhere over here is how we add actions on the left-hand navigation, and then down here in the bottom you can plus or wrench, plus to add a new one wrench to edit the one that you have and you can only edit one that exists right, so you select the one if you're editing you select the one that you edited before and you edit it and you hit OK and you're ready to roll, start working on the custom action. It's really kind of simple and straightforward way of looking at how oxygen puts the environment together and a lot of times that's the hardest thing to figure out.

[00:07:25.910] - Liz Fraley

All right, so let's scooch on to the next thing, let's talk about the action window once you hit that edit button, that wrench or that plus you get the action window. So let's talk about what's in there right, we're three levels in, but each one is very, very clearly defined you're going to fill out the basics of anything that's new, right? You're going to give it an ID, you're going to give it a description, you're going to maybe make an icon for your toolbar or your menu and you're going to define what that action is. This is the action windows where you say everything about the action, what you're going to do, how you're going to do it, what the results are supposed to be, and the arguments that are coming along with the action, anything that needs to be known, defined or otherwise specified for this and what is supposed to happen all right.

[00:08:14.580] - Liz Fraley

So, again, you fill out the information you define your operation. Now, I got two things, three things here you're going to default to a single test, this is the default, you can select the operation. Is it XSLT, is it change capitalization? Is it something else? What are you going to--what is the operation you're going to have in this action? And then you're going to fill out the arguments again, just like in the other window, you want to add a new action, you hit the plus, if you want to edit things, you click the wrench right back in the day to get back to this action window. All right. So here's what the action window looks like. And again, we've got all kinds of stuff here at the top, right. We've got the basic metadata to describe what it is we're creating. It has an ID that's unique, it has a name, has a description. All of these are things you'll see in the action window by itself you can have a quick access key, right? The quick key combo, you can have icons in short cookies, right menu access key versus a shortcut key you can have many different things--you can have a lot of different ways to get at this action or to narrow the scope of when it happens or to specify with a greater detail when this action should take place and when it shouldn't and what should happen and the different behaviors that should happen in different cases, and that's what these tabs are here in the operations window, down here, you get this choose block where you are going to select what operation this action is based on what is the fundamental thing underneath that it's doing? Is it an XSLT script? Is it an X query update script? Is it a JavaScript file or code or is it one of the other actions that you can choose from? Right, and down below it, we get arguments. These are things that the operation needs to know about if you are doing, for example, an XSLT transformation on the document, when the author clicks this button, you need to have either the JavaScript code available to the action or you have to have the file that your code is in.

[00:10:36.590] - Liz Fraley

Either way, the script needs to know about it or the action needs to know about it in the script then is one of the arguments. OK, you can change priority of the test that's these one through five up here, and I'll come back to that in a little bit and then of course, plus there's our plus again right, we're going to add some things to it that adds operations and we can move on to the next screen once the action is set up. All right, well, that little erase thing does weird things and go to webinar. OK, so let's take a look at what kind of operations are available, and there's a lot of them, actually. They come with a lot already built-in plus it includes those four that I mentioned. They'll give you leave to do more than what's specified right? If you choose, for example, X Query update where you're going to update the contents of the document, right, you're changing the code within the document while it's alive, if you're doing that kind of update, you can do anything you want right, it's an X Query update operation. You specify the X query code, you write the script, so you're not limited to what's included out of the box you can pretty much do anything you need to do, which is really a great way of going about this.

[00:12:00.030] - Liz Fraley

All right, so this window here, this operation window, this is what you get when you select the operation. So let's step backward briefly, that is this part down here at the bottom, invoke the operation. You choose, you click that choose button and you will get the window. Here, you'll get this operation's window that choose button, gives you the operations window. All right, so once you've chosen the operation, you go back to that window and in the lower half of the windows, is that argument's part remember I mentioned that previously, and you can--there's a lot of flexibility with this argument window you can--right here you can see I've got code right inside the script value right, I can do that way or I can do it this way and I can point it at a specific file that has the code in it. Now, I'll say that this second way is kind of my favorite way because you can use Oxygen to edit the access the XSLT query script you can test it all through that and then once you have it working really well, you can point the script argument right at the file that is well tested. It's a lot harder to write code in a window that's just a blank window. But you luckily you don't have to do that.

[00:13:28.280] - Liz Fraley

So I really do like to do it that way. The other thing is you can have it be an absolute path like you see in the lower window you can have it be the code or you can have a path that is relative to the framework. Now, remember, I talked about this in the beginning. You can extend a doctype, but you can also extend and customize a framework and isolate your changes from any other changes that happen in the software or anywhere else and that is really the preferred and best way to go, that you extend your framework so that if you do any custom actions, you can put them in a folder relative to the framework and anything you put there, it's a lot easier to configure and to make sure that everybody has access to it. The only thing is you need to make sure that you distribute that framework to everybody, but when you go down that road, you kind of know that. All right, let's move on from here.

[00:14:21.560] - Liz Fraley

You can narrow the scope of the action. And I talked about this a little bit before, just pointing it out. Now, let's talk about what these tabs are down here and this priority button down here, this increase or decrease, you can narrow the scope of the action and make it only applicable when certain situations are true. That's what this has. When the XPath expression is true, then this is valid test and the way that it works one, two, three, four or five, it creates a structure like this. If test one, you do one, if else, if test two, then do number two, do what's in the two. So what this can all be different right, your test can be different. I want to do one thing when I have a title, but a different thing when I have a short description and a different thing when I have a para in a bullet.

[00:15:16.610] - Liz Fraley

Right, you can absolutely specify what should happen and the case in which it applies. This lets you narrow the scope and change how it all works and with that you get the ability to change the arguments so you can have different scripts to do different things in different situations, and that's really very useful. You can do these--you can add the--you click the plus and add a new tab down here. One, two, three, four, five, six, anytime you want and if you want to change the priority that if else, if else, if else is structure and you want it to move it higher up in the list, that's what the increase and decreases at the bottom increase moves it higher in the priority list decrease moves it down. All right, not seeing any questions, so hopefully you had a chance to work through all of this or at least get an idea what's going on? Oh, I have a question. The test applies to the document or the selection, the current position. It does apply to the current position and or the document, depending on which operation you picked. Xquery update operates on the document. XSLT often will just or can work simply on the element itself right, it depends on how you specify both the XPath and which operation you selected. All right, so let's go back to our custom action menu. This is our document type window.

[00:16:44.140] - Liz Fraley

We saw this already, but once you have your action defined, we're now that was this menu item here, this navgrid right here. What we're picking now is we're picking menu because now that we have a custom action and it's well defined, we want to add it to a menu so we can test it out. We can run it, our authors can run it.

[00:17:05.590] - Liz Fraley

We can access this custom action that we've defined. And this is how you do that you click the author tab again at the top, click the menu in the left-hand navigation and what you get is this list of actions, and it's pretty long, this will go the scrolls down a good bit, this also scrolls down a fair amount and what you get is you'll see your thing that you added in the list of available actions. It'll likely be at the bottom it's actually not necessarily so. You select it like submenus selected in this window, there's two buttons in between these two windows. This is available actions, these are the current ones that are in the menu and this is the menu that you can see. You want to add it to the window, you can click the button right here to add it right, this one adds it to the menu. It puts it in a subordinate position. I think I'm covering that up with my pencil it's a result of those drawings and come back right. That's a subordinate one the button above does adds it and creates a substructure. OK, so and once you're here, you can delete it, you can move the priorities up or down. That's your error keys over here once you add it, it's right there on the toolbar, just like the bold button, just like the italics button and just like the underline button, right, all of these things are here. You can just add it there and access it right on the toolbar. With toolbar you have, you can add your own toolbar, you can add your own substructure to the toolbar, you can--depending on where you select that's where it goes.

[00:18:44.880] - Liz Fraley

All right, so but let's go back now to the action window, because we put it on the toolbar, but we didn't have an icon to click like the B, for Bold right. So you can actually specify all of that earlier on in that custom action definition right, right here you can have two icons, you can put them right here, add them right there, and now they're available for you when you add your custom action to the toolbar or to the menu, right. So let's say we go back, we put our icons in. Now look at what we have. We have author tab toolbar, instead of the menu now we're looking at the toolbar right in the toolbar we go down to the action we want and in this case, I have a run XSLT and you can see that I've already got the icon there because I defined the icon before when I did this, I'm creating a new substructure into I'm putting it right inside the menu as a sub-entity and here it is. You see not just the name of the description of the action, but you see the icon itself as well. This is great because we're actually sort of as humans used to recognizing things like faces, like logos, like everything, like what things are. We're very tuned that way so they'll get used to seeing just like the bold button, they'll see your icon and do the right thing with it over and over. And that's how you add it both to the menu and the toolbar, the actions are the same you look for your action, you add it to where you want it in the customer action, and you can move it around you got it in the wrong place accidentally, which occasionally will happen.

[00:20:32.810] - Liz Fraley

So here's the things to remember, remember when you're ready to test the custom action, remember, we did this under author mode, right? We did this all under the author tab. So that's when this is happening. So when you open up a document to test, remember, you have to be in author mode. There's the three tabs at the bottom of the editing window text, I forget the middle one and then author mode in author mode you have to be there in order to test this you need to make sure your cursor is in the place that is applicable to any test that you set, right, if you set it to a limited element or an element attribute combination, you need to make sure that you have created the situation that will let you test what it is you're trying to test, as I answered the question earlier, sometimes it matters on current position because you're changing the item itself, sometimes it matters the documents can change the document as a whole. It really depends on what you set but you need to make sure that you've remembered to put yourself in that situation so everything works and then you can hit that button, hit that toolbar menu item and off you go right, so for example, here it is in the menu bar, right. We see I've created my own menu. So creative, here's my icon in the description that I attached to it, and in the toolbar I just see the icon right, you make sure you're in author mode down here. You're in author mode in both cases for you to see these as accessible live buttons.

[00:22:10.080] - Liz Fraley

All right, back to this, so that's pretty much all I'm going to cover today. We're pretty close on time anyway type in your questions if you have them. In the meantime, let me tell you what's coming up we have two affinity groups that we  started where you actually sit together with other professionals on a conference call and get to discuss your real-life problems, you hold each other accountable to things. This has worked really well for small groups or groups where you're the one tool's person or the one information architect and you need some other people to bounce ideas off of. The TPC Affinity Groups are all about that it is not a free session like the TC Dojo because you're talking real things. So everybody needs to have at least a little skin in the game. It's not super expensive, but it is just there to keep us all isolated so no one just drops in to figure out what's going on at your company. If you want time that is specific to you, the TPC Affinity Groups are the wrong place to get it. But you can book time with me or anyone, any of the other experts at my company, I regularly do this kind of thing with XSLT or Xquery or even just let's look at your docs and figure out how this should be structured. It is only, it is one on one. It is focused on you and your documents, it is part of that economy that we practice where we know you want to learn, but you don't, you're by yourself and you don't want to have to do it all yourself, or at least you don't have to do it alone. Think of us as your TA or your mentor you can ask any questions you want, you can bring your whole team with you if you want. One session is one session in the next TC Dojo next month, we don't have a title yet, but the topic is Style Guide and Keith Schengili-Roberts will be from Ixiasoft will be here to talk about it. You can sign up now and you'll updated as soon as the description is posted. You can get that at www.tcdojo.org scroll down to the bottom and you'll see the date at least for April and as soon as we have information should be--we're supposed to be this morning, but will be in the next day or two.

[00:24:26.520] - Liz Fraley

All right, thanks for attending. We'll get to questions in just one second. Here's all the things that we do, if you want to be sure you'd be notified when this video is posted, make sure you're on the mailing list also, here's those links again, just in case anybody wanted them. The e-book is free to subscribers, if you don't want to be on the mailing list, you can buy it for three or four dollars at Amazon, which is fine, too but we occasionally post bonus tips and we already had one, but we're getting close on time, so I don't have time to share it with us today, but we, you know as we learn things, we are kind of unparalleled in our dedication to community and we post all kinds of information for free all the time. So join the newsletter, stick around, and then when Keith's session topic is ready, you'll get an automatic notification in your email.

[00:25:20.640] - Liz Fraley

All right, Let's get to the questions. Let's see what we've got, all right, can you add an action to be available in text mode? That is a good question, let's take a look at our action window and there's not enough natural tab for that, but I know George is on the line, so maybe he can post the question for me. I haven't tried that, but I would assume that I know that you can do things in your framework, so, it kind of depends on what you're trying to do. So I'm going to ask you to maybe clarify that question, or I hate to give the depends on what you kind of do answer, but a lot of times it matters, you know, what is it fundamentally, you want to happen, are you trying to have something every time you check in, everything you check out, every time the document is saved, those would be things that are independent kind of author mode or text mode and there's things you can do in the framework automatically but so clarify your question a little bit.

[00:26:28.930] - Liz Fraley

All right, let's see what else is there an easy way to share custom actions across multiple workstations for multiple writers? So that I'll come back to the second part of that question. That is when you customize a framework, because then the custom framework can be deployed to everybody's desktop and as you have things, you add it to the custom framework and then that's the thing that's the controlling piece and that's how you would do that.

[00:26:54.490] - Liz Fraley

Can you export actions for multiple ohh sorry, can you export actions or host them on a server? Good question, I want to say yes, because if your framework is on a server, that's a map drive. Sure, I can see that having no problem at all that's the Windows issue is not an oxygen issue right, or even map--It's a map drive so that shouldn't be an issue and you would do it the same way through the framework, not just the action themselves, unless since you can specify a specific and absolute path. It's fragile, so I wouldn't recommend doing it that way, but if everybody has the map drive to the same map location, then, yeah, you know, you just point that all to there and it'll work but it's pretty fragile because you're depending on everybody doing a lot of manual things themselves. So the framework is a better way to go is it even something to think about or do you recommend being fairly, fairly specific to the workstations? Now getting some answers from George, I think I covered that answer, if not, add another question. George say No, custom actions do not work in text mode. So I understand this I actually am a big text mode user myself because I'm mostly in XSLT programmer like I said, I've been using oxygen since close on 20 years at this point I was a customer in 2000 and so I write code and, not worried about that. I did notice that I would switch if you're just ready to test switch to author mode and do some things. So you may need to have some people trained for that.

[00:28:39.120] - Liz Fraley

All right, here's the next thing a framework can be deployed as an add-on hosted on a server. So there's some more answers from George, you just use the framework alright and say I thank you, you answered the question. that's good, all right, one more thing from George, there are options to work in text mode, for example, the selection, plugin refactoring actions, etc. and that's all we did some refactoring stuff so that actually works pretty well. All right, so next question, if we want a separate toolbar or menu, we need to create a new framework and not extend an existing one. No, you can just extend the framework and you can create a new menu item when you want this button off the top that I picked actually, you can create a new one. One of them will let you, the first time it'll ask you sometimes if you want to create your own menu, especially in the menu of thing. The toolbar, not as often, but you can create a new toolbar. You don't need to extend the framework. It's just a best practice right, because if you have your code isolated somewhere that is not in the install tray, so if you update oxygen, it's not covered by anything that way, it puts it in a place that you control and can distribute to your writers. So the framework is a best practice, but it's not only a requirement, you can just extend doctype and work with that, especially if you're a small team.

[00:30:02.880] - Liz Fraley

All right, let's see any more questions, all right, that's all I see, and we are right on time. I'm happy to have done this. If you want time with me, be sure and find that -- I'll put those links back up you can book time with me. It's on the, from the Oxygen page, you can get to that information actually I think, pretty sure and actually not positive I have to go and check on that. I was too busy writing the books and putting them out so that we all can learn together but yeah, there you go I will make sure that gets up there and if you want time, that's about you.

[00:30:42.610] - Liz Fraley

That's one on one time. If you want to just have some people to collaborate with. We do have Oxygen people as part of our TPC Affinity Group meetings, you get special things with the affinity groups if you're a corporate member, you get forty-five minutes free time, one on one with me every month anyway. But you also get access to all the other conference calls and all the other team members and we're all learning things all at the same time. We just learn them in different order so it can be very helpful to have other people to collaborate with and discuss things with like, you know, the big question right now, actually, with all my folks is, do we do like Salesforce and get rid of our inline linking that's a big concern. Do we use relationship tables? Do we use keys and how do we use keys? A lot of DITA right now, but we have people with all kinds of different tools in that session and a wide array of seniority, most people are going around a really long time, and that's part of what makes it work, all right, folks, thanks for coming and we'll see you hopefully next time when Keith talks about Style Guide. So long.