In yesterday’s post, I described a very basic introduction to Data Access Classes, or DAC’s. While a DAC describes the data used by Acumatica, something has to actually generate actions against that data. Acumatica has the lower level data access functionality already built in, but as a developer we want to apply our own business logic. That business logic is contained within a GRAPH. When we build a screen for Acumatica, one of the required elements to configure the screen is what graph, or business logic, to attach. The graph will be today’s topic, but like the introduction of the DAC yesterday, today will be only a very basic introduction to the graph.
The code above is a very basic example of a graph. There are many other features you can build into your graph, but this early post is intended as more of an introduction than to show off how powerful Acumatica is.
Like the MyExampleDAC post yesterday, Line 1 starts the graph with a simple namespace reference to pull in features of Acumatica for us to leverage. Line 3 places this graph in the MyGraph.Example namespace encompassing everything between the braces on lines 4 and 20. When you build your customization project, you will name the project with something like “MyProject” which would be the base namespace for everything in your project. I ask for a little literary license in my namespaces as I’m using them to help remind you what this example does.
Notice that regions have been set at lines 7-10 and 12-18. Like yesterday, these regions are defined to make it easy to collapse the code as it gets more complex. Regions can be nested, so you should plan on defining a region on every field of a DAC, view and method of a Graph, etc. It really is a nice way to keep your code organized.
On line 5, we define the graph, or business logic. we make it a public class that contains everything between the braces of lines 6 and 19. This graph is called MyGraphMaint, and it inherits from PXGraph so that we can use it in Acumatica as they have already written all of the data access code that will access our DAC’s and provided many other features we will want to use. Notice that PXGraph requires a type, or in this case a pair of types. In the first type, we simply enter the name of the graph again. If you don’t understand why, don’t worry. That isn’t important right now. You don’t have to enter the second type, but by entering our DAC as the second type, our graph (thanks to PXGraph) will know the primary data to access and will build some basic navigation into the screen for you automatically.
Like the DAC yesterday, in line 8 we use an attribute to give a “pretty name” to the View we define in line 9. Line 8 simply tells Acumatica that the view called Document should be displayed as “My Graph Example”.
Line 9 defines the way to gather data to be viewed on the screen, so it is appropriately called… a View. The structure of this line is very important, and you can have many of these in a single graph. public makes it highly accessible. PXSelect is a special class created by Acumatica with the ability to dig into the database and retrieve the data we need. It requires a type, or even a complex type of types, to tell what DAC’s to access. That gets entirely too complex to go into for this post, but suffice it to say… it is an area you will spend a LOT of time honing your skills. The word Document is the name I gave the view. It may be the most common name that Acumatica uses for its primary view on graphs, but it can be any name you want provided you do not violate Acumatica naming rules. Like all the other tangents, that’s for another post. To give you the idea, but not get into the details… the type following the PXSelect essentially translates into a SQL statement against the database, and the view (i.e. Document) will contain the results of the data retrieval.
As the region of line 12 hints, line 13 is our first event handler. An event handler is just another method to apply business logic to our data. Well, that’s not entirely true. It is special because, unlike “just another method” an event handler is “hooked” into events that occur as Acumatica process various actions to work with data, views, etc. (You probably guessed it… more on that at another time.) By specifying protected, the event handler cannot be called directly from outside this class (graph). by specifying virtual, it’s easy to override this event handler if you need to apply your own customization. There are special names you can use for event handlers, which I might describe in a post about event handlers, but for now we will just use the generic underscore for all event handlers. When Acumatica advised the community to switch to that syntax, it was a little awkward to me. Over time, I’ve grown very fond of the approach because of the clarity brought by the parameter used. Events.RowSelected causes this handler to be attached to the event of a row of the specified type being selected. Seems kinda obvious, I guess, but note that there are quite a few Events that you can tie into, and you can hook into every DAC and field of the DAC at a variety of points of code execution. The type specified is incredibly important. This is like where you place the nail in the wall to hang a photograph. It very explicitly defines where you want to tap into code execution. For row events, we specify a DAC name. For field events, we specific the DAC.Field. And finally, we specify the argument name, which by convention is always e.
On line15, we retrieve the value of the DAC row being processed and assign it to an object (in this case “row”) of the type of our DAC being handled. While “e” has many elements that we can access, we usually need to access the data itself, so row 15 gives us that data.
As line 16 implies, this is where you can put your business logic. For instance, in a RowSelected event, we often control what fields are enabled for the end user. All of that code, as relevant to the event being accessed, would be placed at line 16.
While this post may not be super exciting, I hope that it gives another perspective to a new developer who may be struggling to understand graphs like I did when I got started. For me, it took a lot of Google searches, digging through the code repository from Acumatica, and just good old fashion practice. Still, I find myself struggling to get all the pieces right, but every struggle brings the reward of growth and, pardon the pun, development.