[00:00] In this lesson, we'll learn about extension functions for ignition components. What they are, examples of how to use them, and why they can be so useful. An extension function is a specific type of scripting function on a component that is left up to you, the user, to implement. They allow for some more advanced customization of a component via scripting, and as such require a bit better understanding of Python. Extension functions are available on a number of vision components, though not on all of them, the components that do use them, each use them for different purposes. So as an initial example for discussion, let's consider the power table component. So we'll scroll down a bit to the table section, and we'll drag a power table component onto our editor window, and we see that it's empty of data. So just to make this a bit more relevant, let's populate it with some sample data. So in the property editor at the lower left, we will scroll down to the bottom and let's click on test data, to create some sample data.

[01:11] That's more like it. So let's get to the extension functions by right-clicking on our power table and going to scripting and double clicking if needed on the extension functions folder, under the extension functions tree here on the left, we see a large list of functions, each such function gives you the proper place to put some scripting for a very specific purpose. Let's for example take a look at the on pop-up trigger method near the bottom. Notice that its starting default state is grayed out. So we'll click enabled up at the top. Let's take notice several things here, for each of these functions, there's already a fair amount of sample code provided. The first line is the prescribed interface, with its inputs predefined, note that the first input will always be self, a reference to the component itself, instead of an event firing, the component itself decides when it needs to be called.

[02:06] And also notice that we can't even edit these inputs, which is probably a good thing. In this next section, inside triple quotes, this is just documentation, using what's called a Python doc string, and that's just a standard way of adding documentation to a function. Note that it can't be edited either. You can read what all these functions are about, by reading these doc strings. Here, we can see that the on pop-up trigger is called when the user right-clicks on a table cell. So the general idea with all these extension functions, is that you the user, are responsible for implementing the body of the function, whose interface and description are already defined. Let's see how to put one of these examples scripts to use. So let's select these last lines and we'll click control slash to uncomment them. And here we see that we have a defined function, within this function to create a pop-up message box and that pop-up message box will print the cells value and will use the function, as part of the creation of a pop-up menu item, when a cell is right-clicked, let's try it out.

[03:16] Let's click OK to save our changes. We'll go to the preview mode up at the top. And then we'll right-click on the cell, to get the hello menu item and clicking on that, we get a pop-up with a sales value, whatever it may be. So now that we've seen the basics and how to use one, what are the advantages of an extension function? An extension function can save you a big amount of work to achieve the same functionality. Imagine you were trying to piece together a cell handler to do something like we just did from scratch, perhaps by using a mouse handler or something, there would be a massive amount of work needed for example, to translate the mouse coordinates to the coordinates of any one cell. And also you'd have to handle such things such as sorting or rearranging the columns, anything that user might've done.

[04:05] There'd be a whole bunch of low level work needed for something as seemingly simple as a pop-up trigger, making it way too hard. So for an extension function, and we'll go back to design mode and the scripting window, an extension functions such as this one, lets the component do all that work for you. And then it calls your implementation at the correct time. You put the implementation in it, but the component decides when to call it, just to give you a little bit more flavor of this or other components that use extension functions for totally different purposes. Let's try out another extension function for this same component. How about configure cell? So first we'll enable the code at the top. Then we'll select and control slash to uncomment the example code and this one we'll just alternate the row colors. So we will apply our changes, and we see that now we've got alternating white and gray rows.

[05:04] Don't like that, let's change the white to red and we'll apply our changes once more, and now we see red rose. As we said, other components have extension functions available too, for example, let's hit OK, and let's delete this power table, now that we're done with it. Yes, we can delete that. And let's drag over an easy chart component. So we will drag it over here and then do right-click scripting and we'll click on the configure chart function. And we will see that this allows you to provide extra configuration onto the chart itself. So let's get rid of this one by doing OK and deleting this one. Or maybe we can take a look at the alarm status component. So for that one, maybe we'll search for it and we'll pull one over, and have a look at it. Even though here in the property editor, there's a number of properties, that lets you define, which alarms in your system you wanna display.

[06:11] At some point properties never give you the ultimate level of flexibility that scripting can give you. So for the available extension functions, right-click scripting, for example the filter alarm function, will let you have some fine grain control over which alarms are shown. This function will get called for each alarm that the alarm status table pulls out of the gateway and whether or not your script returns true or false, according to whatever criteria you wish to set up, will determine whether or not that alarm is displayed inside the table. So as we've seen, there's really a wide array of purposes that extension functions serve. Just a couple of last things to remember or be aware of, you can't change or even edit the function interface, that's fixed.

[07:02] Same thing goes for the doc string fixed, make sure to use the nesting style of the existing code, which should be Tabs not doing this can lead to some little gotchas I've found. And whenever you wanna teach yourself whatever any extension function does, just review it's doc string. These functions are all self-documenting, which is really nice. So to summarize in this lesson we've seen, how extension functions provide us with fine-grain scripting customization for a number of components, how they provide us with a documented interface, and a starter code framework we can customize and how they're used for multiple purposes by the same or different components.