Java Break - Plumbing Barista with Cust BBj Part 1

Uploaded by BASISIntl on 09.02.2011

Welcome to this Java Break with BASIS.
Today we are going to look at "Plumbing Barista into Your Custom BBj Application."
My name is Nico Spence. I am the Chairman and CEO of BASIS International and I'm going to be joined today by Christine Hawkins,
one of our BASIS engineers, who is going to be showing us some practical ways that we can integrate our handcrafted BBj code into the Barista framework.
Let's have a look at the agenda.
Firstly, I'll remind you what Barista is and then we will look at plumbing Barista. The bulk of today's presentation will be given over to some hands on demonstration
of plumbing Barista into your handcrafted BBj code.
And then we'll take your questions and hopefully provide the satisfactory answers that you are looking for.
So let's begin.
Firstly, the Barista application framework. Let's talk about what that is.
Barista is a data dictionary-based GUI development platform. It's a workbench for developing data-centric applications.
It also provides the application runtime environment for end users when running those Barista generated applications.
The most important aspect about Barista is that it's very quick and easy to generate your application. So it's a rapid application development environment
delivering multi-fold productivity gains over the older methodology of generating applications in the GUI environment.
It takes care of all the tedious event management, keyboard navigation, it presents a very modern look and feel,
it offers the capability across various platforms
and it takes away that often time consuming and tedious task from the programmer and allows you to focus
on those business rules of your business application.
It facilitates application migration by integrating CUI and custom GUI into the Barista framework, and more about that later.
Let's talk about the architecture and interface. It's written in object-oriented BBj. So that gives it the cross platform capabilities that most of our clients need.
You can run in a heterogeneous environment - have a Unix backend server and Windows desktop client and a mix and match.
You could have Mac desktop clients, Linux desktop clients, Windows in the back, whatever you choose.
It's organized as an MDI, multiple document interface. It allows you to be more productive, the user to be more productive, have more tasks running at the same time.
And all of that collapses down into one consumption of a license.
It gives you an optional integrated menu panel. The user can define or decide whether to split that out and not dock it to the side.
It's up to you to determine or the user to determine whether they wish to have it integrated.
It's delivered with a context-sensitive tool bar and menu bar so your navigation can run off of the MDI tool buttons.
The menu bar is context-sensitive insofar as it understands the role-based security concepts that a user would only see those menu items that they have access to.
Let's talk about the components of Barista.
It has, as I mentioned earlier, it's built on a data dictionary.
So it has an extended data dictionary. It extends the BASIS data dictionary or it will extend the third party relational database data dictionary.
So you can import a data dictionary from a relational database management system
such as Oracle, MySQL, and SQL Server. It has a Form Manager that allows you to manage the various forms that you have that make up your application.
It has a Form Designer to allow you to very rapidly generate and design the forms that you need for your application.
It has a Callpoint Editor and this is one of the magic pieces about Barista. It lets you drop down to the BBj code and instantiate BBj
objects, utilize them within your normal business flow within the application. So at the various events that may call for some business logic,
you can insert them as you need.
It has a built in Inquiry System
and it goes beyond just a simple inquiry on a table level, it also has the Expresso Search functionality where you can actually link tables and do drilldowns from,
for example, an order down to customer to the actual stock components that may be on that order.
It has a Menu Design that makes it very easy for you to add new functionality or integrate existing code into the menu system.
And it has a Role-based Security Manager. So you can define roles and then assign roles to the particular users.
And the user may have more than one role.
It has a built in Document Output System. The document output system is great for transitioning legacy report applications and there is a tutorial available
on our web site that will show you how to very simply move your output from the 'print at' type commands to
populating a vector and that vector is passed off to the document output subsystem which allows you to produce output in PDF format to a printer
or to be saved, for example into a Google Doc.
And new to the latest versions of Barista, lookout for it, you will see functionality where you can simply navigate through a standard File Save dialog, to save your files
in the Google Cloud.
Let's talk about the Barista use cases. Barista is perfect for building brand new GUI applications,
for modernizing older GUI applications, or converting character based applications to graphical.
But the key question is can it do 100% of what you need it to do?
And the answer to that is, "One size seldom fits all!" It is generally going to be the situation where maybe the task, the form that you looking for is not bound to a particular
database, to a data dictionary or maybe it needs a very complex interaction from multiple components and multiple data sources.
So what do you do in that case? Do you just throw the baby out with the bath water? Is Barista not appropriate for that function?
Well no, it is probably appropriate for 98 or 99% of your requirements.
And for that other one or two percent, you can drop down to using AppBuilder or custom handcrafted BBj code.
But you need consistency in look and feel and navigation. You want to take advantage of Barista's search capabilities, of Barista's navigation buttons
of the look and feel of the Barista app. So how do you do that? That is the thrust of today's session.
Let's considered the various choices of plumbing Barista into our BBj code.
Firstly, we could have a very simple integration point whereby we can run our outside programming inside the Barista MDI menu.
Secondly, we could retrofit a BBj application
whereby we can plumb Barista into that pre-existing form and give that pre-existing form access to the Barista tool buttons
for navigation and for searching et cetera.
Thirdly, we could extend a pre-existing Barista form by adding controls that may not be readily available within the Barista framework...
a custom tool button for example or a more complex grid to be added to a Barista form.
And lastly, we can build anew.
We can use AppBuilder and FormBuilder, the BASIS development tools in the IDE, with the Barista skeleton code
to provide the pre-plumbing for our custom BBj code.
So let's have a look at some of that in action. Let me hand over to Christine.
We want to begin by reviewing how easy it is to run external forms from within Barista. In this case, we are showing the Examples menu. This is available when you download the
development builds of BBj, Barista, and Addon. I have added to the Examples menu three items that we will use today.
If we take a quick look at the Examples menu...
we can see that launching an external form
is really as easy and this is a form written in BBj, is really as easy as letting Barista know that you want to run an application program...
and provide the path name to the program that we want to run. So the first thing I'd like to show as we discuss today how we can take external forms and
hook Barista functionality into them. The first thing I'd like to show is an external form that has been built in BBj outside of Barista.
This is a simple Customer Form...
attaches to a little customer file underneath
a very simple operation.
If I enter the key for a record it will retrieve that record and display it for me.
I can change using the 'Update' button.
I can delete records and so on.
A simple functional form that I can conveniently launch within the MDI. It's just that it really looks nothing like my other Barista forms.
So how can I run this form in Barista,
preserve the investment that I've made in developing this form
and yet get it to function more like other Barista forms? For example, a form like this that has a toolbar at the bottom
and also makes use of the MDI menu and toolbar?
And that is what we will take a look at.
Before we dive into the more technical aspects of how you can incorporate Barista menus and tool buttons on your forms,
I would like to offer a little background information on how it is that these menus and tool buttons on the MDI and on the individual forms work in Barista.
How does this stuff all work to begin with?
Barista makes use of a BBj group namespace for communication between the MDI and the various forms that may be running in the MDI.
Now how does a group namespace work? You can, by the way, go to the BASIS documentation and read all about namespaces so I won't go into great detail here.
But the thing to understand is that a group namespace allows one or more BBj programs to communicate with each other, to share data with each other.
To let one another known when a particular piece of data that is of interest has changed.
Whenever Barista launches a form
it sets a group namespace variable that corresponds to the name of the form or the task that's being run.
When an MDI menu or tool button is pressed, the namespace variable for the currently running task is updated with an abbreviation of the name of whatever
function or button was pressed.
When Barista/BBj detects that the namespace variable has changed,
it will run the routine that we specified and that routine will look at which function it was that was pressed and route our actions accordingly.
In a similar fashion, when Barista places a toolbar on a form it determines which buttons are appropriate to be enabled or disabled based on the form type and it
registers callbacks for those button press events as well.
And the program that's controlling the form will then intercept that event, take a look at the function that was triggered and route accordingly.
We can see some of that communication taking place just as we move from form to form in Barista.
Let me launch another form so that we can show the difference.
Notice that when I'm focused on the Shipping Methods form, which is a grid style form, there are certain buttons that are no longer applicable.
The 'Record navigation' buttons are no longer applicable but the 'Add new' and Insert new' buttons are.
So as we focus on this form communication takes place between the MDI and the form and Barista knows which buttons to enable or disable.
If I move to the Commission Type form,
again we can see the MDI is communicating with the form that has the focus and enabling and disabling not only buttons but menu options as appropriate.
Looking at this in a slightly different way,
we can get a little more of a detailed look at what goes on in Barista when we select something from the menu or press one of the tool buttons.
This form that I am going to launch is simply a tutorial form. This form is available online, by the way, the BBj program and the 'arc' that are required to run this.
So that if you have the 'examples' installed you can easily run this demo as well.
This looks like a Barista form however, it was developed outside of the Barista development environment
much the same way as this little Customers form was.
It looks like a Barista form because it has its own toolbar and menu and also because it interacts with the Barista MDI.
We did not just paint these on here for looks. They are actually functional buttons.
The purpose of this form is really two fold. It's a tutorial, there's no IO going on.
It just shows us that events are firing as we select a menu item or as we press a tool button and it will show us which events those are. What does Barista call them?
And that, as developers, is what is important for you to know so that if someone presses the 'Save' button
what sort of code, what do you get back from Barista in order to do what you want to do in a program when the 'Save' button is pushed?
So we can take just a quick look at this by just starting to click around on things.
I mentioned the 'Save' button, if I click that here all that this form does is intercept the event
and rather than routing this to some sort of 'record write', which you probably would traditionally do if someone pressed the 'Save' button,
it just let's us know that someone pressed a button Barista calls this 'SAV'.
And what's the source of this event? Did it come from the form or from the MDI? And we can see here that it came from the form.
So this is simply a tutorial that lets you get acquainted with the various tool button and menu selections.
It shows you the internal code that Barista uses to identify them.
And here we see again the source of the event.
So, this is a good little tutorial to run. Not only does it include all of the code that you need for putting a tool bar and
any functionality on one of your own forms, but this one actually lets you then click around to see what happens, which events are firing and what Barista calls them.
Furthermore, if you 'check' the little box here, we can see how another Barista public that we use toggles the status then of, in this case, the 'Find' button.
When I 'checked' this, I don't know if you noticed, but the little 'Find' button here became disabled. If I do the same thing on the 'Save'
you should see that the 'Save' on both the form as well as on the MDI were greyed out.
An note, in the pull down menu it is greyed out as well.
So this is a little tutorial form that you can use to get hold of some sample code and begin to learn how to incorporate Barista menus and tool button functionality
in your own forms.
Let's return now to our Customers form. We have taken the Customer form that we built outside Barista, integrated the code,
much of it copy/pasted from the skeleton code and that gets us a version of the Customer Form that fits much better in with the rest of our Barista forms.
We see now that we have a menu and toolbar on the form.
The one in the MDI is active and responsive as well so I can click 'Next record' from here and my form responds.
I can click on the form as well and it responds.
I can setup for a new record.
I can 'Save' that record.
And again, my own code that I still had in my custom program is preserved here. I get a little updated verification.
So I have a form that now not only looks more like the rest of the Barista forms but truly interacts in the same way as those other forms do as well.
Thanks Christine. So this is what the sample code would look like within the BASIS IDE, the sample code used within that tutorial.
And to learn more about some of that sample code I'd encourage you to go and have a look at the associated article in the recent BASIS Advantage magazine
which talks about "Plumbing Barista into Your Application". Within that article you'll see a link to the download for the arc files and skeleton code
to be found in the "Barista Plumbing Exposed" document.
So let's get on and see what it looks like once we've plug the skeleton code in place.
We've seen how you can integrate Barista menus and toolbars into externally created forms
that is BBj forms that you've developed outside of the Barista framework.
It's also possible to add your own controls to forms that you've created within Barista and manage those controls
so you can provide functionality beyond Barista's default behavior.
This sort of customization can be done on both table-bound forms, that is forms that are largely built and controled by Barista,
or on Barista option entry forms. Those are forms which aren't table-bound.
This allows you a great deal of flexibility to mix and match controls from defined Barista elements with your own controls. We will walk through a simple example so you
can see the basics of creating and managing your own controls whether you're adding one or dozens.
What we have here is again the Examples application that is available when you download Barista.
And I'll launch the Customers form.
This is a table-bound form. The customers table is underneath.
This form is virtually all under Barista's control.
That is to say, all of the elements on here are defined in the underlying Customers table, but there is something we've added on our own
and that is this custom button. This is a tool button.
What we have done is used callpoint code to define this tool button and tell Barista where we want it to be placed on the form.
We've register a callback for this tool button so that when someone pushes it we will be notified
and then we've added some code that will launch the user's email client when that notification happens.
So we can take a look at this in action by just browsing to one of the Examples records. This one has an email address entered.
If I press this button my client's systems email is launched
and the 'To' name here is filled in and we've added an email 'Subject' here just as a filler.
So with just that click of a button I'm ready to start composing an email.
So this is a great example of a customization that I can do.
And if I can do this sort of button I could add buttons to perhaps launch maps, go to web sites...and it doesn't have to be buttons.
I could add my own input controls or other sorts of controls that are available.
So how did we do this? Let's take a look.
Let's bring up the Barista Form Manager and take a look at the callpoint code for our Customer Form.
There is very little callpoint code involved for this example.
But again, the basics of the callpoints we are using and the sorts of code that we're adding would be the same for whatever sort of control you would be working with.
So here in the 'Before Window Show' we've set up a couple of use statements because we will be using the Java URI and Desktop classes to get that email client launched when the
time comes. But more importantly,
we get ahold of the email control itself that is on our form in order to get its position on the form.
Where is the x and y coordinate and so on? Then we get ahold of a control ID from Barista...we want to add a custom control and then we set up a tool button
and we position it out to the right of this email field.
We set some user data for the tool button and this will help us recognize if it was the email button that was pushed later, and then we set the Callback.
So we are setting a Callback for the TOOL_ BUTTON_PUSH event.
When this event occurs it will, in the Barista program that's controlling our form, it will go to a routine called 'custom_event' which will in turn, tell it to come to our
call point in the 'After Custom Event' area.
When we get to the 'After Custom Event' area we will get hold of the event that sent us here and the control will verify again by checking this 'getUserData'...
is the event related to the email control to the one we are interested in? And again, we could have several controls on the form so you'll want to know which control triggered the
event and what was the event.
We only registered a callback for the push button event, so as long as we know that it's the control we are after then we can assume it was the button push event.
So that's what has occurred, we will go ahead and formulate the email address. We will just get the data out of the email field.
Make sure it doesn't have a space in it, just a simple form of validation here. Make sure that the email doesn't contain spaces.
There are other Java classes, certainly other validations you could write for an email address.
We initialize some variables that we need then to use the URI and the desktop classes and we end up launching the email client.
So it's really that same methodology over and over again.
At a point before the form shows you are going to place your custom controls, you'll set Callbacks for them for the events that you're interested in.
And in the 'After Custom Event' routine you'll then intercept those notifications - which control is involved? which event? - and you'll do your processing accordingly.
So again we can see that in action here on the form.
Push our custom button and it launches the email client.
Now that's a very simple example.
Before we finish let me bring up a slightly more complex example. This is from the Addon application and this is, as I mentioned before, an option entry form.
This is not a form that's bound to any particular table underneath.
These fields at the top are defined Barista elements that we've put on this form, but the grid is a control that we added
in the 'Before Show' routine just as we saw in our simple example.
We've defined the number of grid columns, the headings...we do the record reading to populate the grid and we register events that so that when you click in the checkbox
or type in an amount we can intercept those events and act accordingly.
So this gives you an idea of how much you really can do customizing a form that you build starting in Barista.
Thanks Christine. For this last piece let's look at how we can build anew with that skeletal code inside of the IDE inside of the AppBuilder tool.
Let's take a brief look now at some brand new functionality, some new integration between Barista and BBj
that makes it possible as we're working on externally generated forms into which we're plumbing Barista menu and toolbar capability...
makes it possible to launch those from here in the BASIS IDE for testing purposes.
What we have in front of us in the IDE is the Customer form not unlike the one we saw in other sessions.
The difference is this one has been built as a GUI builder project. So rather than writing our own BBj program from scratch, we've let GUI builder
do some of the code generating for us. We've designed the form, we've added code blocks, and here in the Init_codeblock
we can see much of the same code. We are defining that we want Barista menu and tool buttons.
We have the same dsp_form routine that integrates the menu and tool button into the form.
We have the route_func routine that intercepts the events for which we have registered Callbacks and let's us route our processing accordingly.
So we've added codeblocks here in much the same way that we added code to the BBj program we wrote on our own in the previous example.
Now I'd like to be able to run and test this directly from the IDE.
How can we do that?
The first thing is to make a quick modification to your barista.cfg, your Barista config file,
so that the prefix line includes the directory in which your project is stored. So I've added to my cust_form_barista path name here to my barista config.
And then in the IDE, we will go to Tools, Options...BB Project Execution Settings...
and we'll set up the following. In the Config File Location we will again provide the name of our barista.cfg file, the Start File Path will contain the name of this new Barista program,
bax_launch_mdi_task. This is a new Barista program that helps us run our Barista forms or launch them from the IDE rather than the MDI.
And finally the program arguments line will resolve the FILEPATH and the FILENAME to the current file that I have open in the IDE.
So given those project execution settings and my change to the barista.cfg file, I can then open up the GUI builder generated program, cust_form_src.
This is a combination of GUI builder generated code and all of the code blocks that we have specified.
If I now press Shift + F6 or this BB Project Execute button, we will be able to launch the form. It is still going to appear in the MDI,
but when we flip over to the MDI we will see that our form is now running
and I haven't had to launch it from within the MDI. So I haven't had to make any menu mods yet to launch this form from within the Barista MDI.
This gives me a quick shortcut during the early development phases before I flip this form up to a menu to be able to test the menu and tool button functionality
that I am plumbing in to my custom form.
Great! Let's review what we covered. In summary, we've reminded ourselves of what Barista can do for us, what it is. We've spoken about Barista use cases and we've looked at
the examples of how we can plumb Barista into some pre-existing the BBj code. How Barista may not be able to provide us with 100% of our application requirements but
we can handcraft that code in BBj or in AppBuilder and how we can retrofit that with the Barista plumbing.
Some very simple examples where we just run an outside program from within Barista and how we can retrofit pre-existing BBj GUI code with the Barista plumbing.
How we can extend a Barista form with some additional controls and some very complex controls.
And finally, how we can build anew a brand new piece of code that wouldn't necessarily fit the data dictionary paradigm,
but that can be generated using AppBuilder or handwritten BBj code utilizing our skeletal structure for the Barista plumbing.