How to implement a right-click tunnel

Sage X3 is chock-full of right-click options, they are basically everywhere. So here is how we can implement our own.
We are going to create a right-click tunnel to the Products function (GESITM) in the grid lines of the Delivery function (GESSDH). Such a tunnel already exists on the field [M:SDH1]ITMDES:

However, there are some problems with that. First of all, it is two clicks too many - we have to double-click the Description field first, and then right-click. Secondly, if we are on the other end of the line, we have to go back all the way to the left side. And lastly, if the delivery is posted, we cannot even enter the Description field. So if we find ourselves tunneling to the Products function often enough, we might want to implement this functionality generally on the line, and not on a specific field.

We will do this by going to the Screens function (GESAMK), navigating to the Delivery details screen (SDH1) and defining a Button action on the bottom of grid variable NBLIG:

In my case, the first free Button action is Button 17, so I use that one. I assign to it the action GOBJETC2, which opens a new object (GOBJETC0 and GOBJETC1 are equivalent actions, but in my case they are already used). My action has three parameters in the right panel:
OBJCLEC2 - the code of the object that will be opened. We assign the product code field ITMREF.
OBJETC2 - the abbreviation of the object to be opened. In our case, "ITM" for Products.
OBJZONC2 - not used.
In the left panel, we also assign a default title of "Products".

This is enough for the functionality to work, but we can put one more finishing touch. When we right-click, we don't want the tunnel label to be the default "Products", but "Product XXX", where XXX is the product to be opened. To achieve this, we must define one more action on the NBLIG variable:

The action is of type Init Button, and we assign SPE to it. SPE means that the action handler will be located in the specific processing file for this screen - namely, SPESDH. After we validate the screen, we can go to the General tab and open the SPESDH file. We want to type in the following handler for the Init Button action:

Subprog IB_NBLIG
Raz GBOUT17
If [M:SDH1]ITMREF(nolign-1)<>""
    GBOUT17="Product"-[M:SDH1]ITMREF(nolign-1)
Endif
End

GBOUT17 is the global variable that holds the title of our Button 17. First we clear it, and then, if we have a product code on the current line, we assign to GBOUT17 the string "Product XXX", where XXX is the product code - exactly what we wanted. We save and compile, and we can close the SPESDH file.

The Delivery function is transaction managed, so the last thing we have to do is validate the Delivery transactions (function GESSLD). After we do that, we can use our new functionality in GESSDH:

This is a general technique that can be used in any X3 grid to open all kinds of objects and documents.