For a recent project I’ve worked with a customer who wished to provide their users with an engaging desktop application that would allow management of product formulations. They had a Synergy UI Toolkit version and also elements of the required application in a third-party system. However, neither met the needs of the users. After a review and discussions about their requirements we agreed on a Synergy .NET Windows Presentation Foundation based application using Infragistics tooling for the User Experience.
The basic requirements of the application where to allow the creation and maintenance of formulations. A formulation contains the components required to make a finished product. For this customer the final product is an aerosol.
Let’s take a look
The basic interface is built using the Infragistics control to handle navigation (Ribbon menu control), listing and selection of data (powerful DataGrid), hierarchical representation of the formulation components (TreeView) and management of finished product details (Property Grid);
Of course, using the Infragistics DockManager allows the user to drag and reposition all the available windows to their liking.
There are powerful searching facilities, or QBE (Query By Example) controls. These allow the user to provide snippets of information and the application will query the Synergy DBMS database using Symphony Harmony and the Synergex.SynergyDE.Select class;
The top line of the QBE controls allow the user to enter the data in the columns they wish to search for and so only select the data they require and not have to filter through a list of thousands of formulations.
Because the application is written in Synergy, the existing printing capabilities from the original UI Toolkit application have been retained without change;
The whole application is written in Synergy .NET and utilises the Symphony Framework for controlling the data access and presentation. If you would like more details, or would like to know how you can build modern applications with Synergy .NET please drop me an email.
The Synergex Resource Center Community site has a number of great features including the Answers and Ideas portals. Ideas is the place to post your ideas for improving Synergy and related products. You can vote for ideas and provide comment and feedback to help the whole community be more successful. The Synergex community site had an idea posted recently:
The Synergy DBMS Manager allows you to query and manage data in your Synergy data files using Symphony Data Objects.
Code generating Symphony Data Objects for your files is a simple process. Ensure you have your Synergy Repository configured. You need to define the structure and associated file definition for each file you wish to be able to manage using the utility. There are full instructions at the Symphony Framework page which walk you through the few simple steps to building your data object assembly in Synergy .Net. Not sure how to build Synergy .NET assemblies – then send me your repository and I’ll do it for you!
To query data you simply issue the required select command and define the response data object;
Simple, and you can scroll through the results. The idea posted was to be able to then export the selected data to Microsoft Excel so that further review and analysis can be performed.
A new toolbar button has been added and the GemBox Spread assembly used to easily create the Excel document. Now you can export all the selected rows to an Excel document:
Whenever I work with customers code there is almost always a need to “run” their applications. That means I need data. To ensure that Synergex protects our customers data and that we conform to the various data security requirements of todays world there is usually a need to cleanse the data before I get access to it. This cleansing process is like redacting words or phrases in a document – to prevent the consumer (in this case me) from seeing the real data.
With Synergy today there are basically two ways to do this; write a program to clear or set the data fields within the records in the file to a specific value or configure Synergy xfODBC and use a database management tool. If you don’t want to write code, or license and configure xfODBC you can use the Synergy DBMS Manager.
The Synergy DBMS Manager is a simple utility that can be used to redact data in your Synergy DBMS files. Your can download and install the Synergy DBMS Manager utility by visiting the downloads page. The utility uses Symphony Data Objects to describe the data in your files – these are easy to code generate.
Code generating Symphony Data Objects for your files is a simple process. Ensure you have your Synergy Repository configured. You need to define the structure and associated file definition for each file you wish to be able to manage using the utility. There are full instructions which walk you through the few simple steps to building your data object assembly in Synergy .Net. Not sure how to build Synergy .Net assemblies – then send me your repository and I’ll do it for you!
Synergy DBMS Manager
Once you have the data object library built, you simple run the utility:
You’ll need to locate the “Data object assembly” that you have just built, and following that select the “Table mapping method”. Enter the password and you’ll be in the utility and ready to manage your Synergy DBMS data.
You can perform simple queries to locate and review the data in a file;
Now you can easily redact the data in the file – remember you are affecting the ACTUAL data in the file, so make sure this is a copy of the data file and NOT your LIVE data, there is no rollback functionality!
Simply issue an update command;
Notice the result count () at the bottom of the screen. Because we didn’t specify a where clause then all records in the file were affected by the requested update. Now you can perform a simple query and see the results;
This data is now cleaned. If you need to send data to Synergex Support to assist then to resolve an issue you have, this is a great way to redact and protect that data before sending it.
The post conference workshop developed from the ground up a vinyl record collection catalogue system that allowed the management of your favourite records. The workshop stepped through the various aspects of the system including a desktop WPF maintenance program and remote management of your cloud based catalogue using the Synergy DBMS manager.
Having all your vinyl discs catalogued is great – but when I’m in the record shop browsing through all the latest available titles I often wonder – have I got this one? I’ve got a lot of vinyl’s and many more CD’s so remembering all the one’s I have can be difficult, and there is nothing worse than buying a duplicate.
So our OnVinyl app we built at the conference allows us to scan the barcode of the album in the store and check it against our catalogue – if we have it then the details are displayed and we don’t go and buy it again.
Getting all the album information into our catalogue would have been a long and rather boring job – especially having to trawl the web looking for the artwork to associate with each album we have. We need an easier solution – and so to Google we turn.
We all know how good Google is at searching for basically anything you can think of really, but did you know you can use this powerful searching capability from within your Synergy programs? Google provide a search API that allows you to simply and very easily perform any search you require. This is the facility we added into our OnVinyl Album Maintenance program – enter (or scan if you have a barcode scanner to hand) the barcode on the album and pass this through to the Google search API. Our implementation retrieved the album name, artist, cost and artwork so we are able to populate all the fields in the maintenance form – without any typing!
The Google search API provides a REST API that you can call directly from within your Synergy program. For full details visit https://developers.google.com/custom-search/json-api/v1/using_rest. To use the API you need a Google account. The first step is to create an “API key” which allows you access to various Google API’s and identifies you to those API’s. Visit the Google API Manager console to create an API Key. Once you have an API key then you can set up a custom “search engine” that allow you to customize how your searching is performed. You can limit the results to certain web sites for example. This is all configured using the Google control panel (https://cse.google.com/all). To begin you create a new “search engine” and name it. Once created it will be assigned a unique search engine ID – you’ll need this!
In your Synergy code define some constants;
The API is a REST implementation that has a defined URI;
And then make the required REST call to retrieve the search results;
And that’s the call to your custom search engine complete. The response from Google will be in the form of a JSON string which you need to parse and out and extract the individual elements you require. The code for that is available in the OnVinyl project.
And the results in your application;
Easy really is easy with Synergy and Google searching!
On a side note – I’ve been wondering where Jodah had got to, and then this appeared in my inbox;
I’m sure I recognise those eyes…. Have you seen or got a picture of Jodah’s identifying name tag?
This year’s DevPartner conference was held in Atlanta, Georgia and was a blast. I guess I say “the best ever”” each year, so I won’t this time – but it was. The whole conference ran flawlessly, although throughout the week I did see a few strange things in the corner of my eye – but you know how it is. You think you are seeing things… But maybe not.
We had lots of new faces in the audience seeing what Synergy has to offer which is always great, and they got to see a few new faces presenting at the DevPartner conference for the first time.
Although Phil could be considered a veteran now – his third conference – he was joined on stage by first-timer Tate, a fellow support engineer. They presented a cool session on BOTS – not those things you sit on, the automated robots that answer whatever questions you have. There are loads of bots around and the duo showed us what it’s all about and how to build you own!
Another new face was Jacklin who presented all the ways to get fully up to speed with Synergy today including all the various media feeds and the cool YouTube channel we have that’s being loaded with great training videos – and of course you can always re-watch all the conference sessions.
At the beginning of March I blogged about “Physio My Way” which is an app to monitor a patients compliance to perform their prescribed upper limb exercises. Ashley presented the full Physio My Way story and received great feedback – if you get the time check out the Synergex YouTube channel in the coming days to see the full video! It’s a complete mobile solution written end to end in Synergy.
And so to my post-conference workshop. The goal was to write, from scratch, a complete application called “On Vinyl”. “On Vinyl” is a vinyl collection management and inquiry system. The system is written entirely in Synergy .Net and uses the Symphony Framework.
We started off by code generating the base data objects – the classes that expose the Synergy Repository structures as classes with full get/set properties for the fields. We also code generated classes to provide complete data management using Symphony Harmony.
Next we built a simple maintenance program to allow us to manage our collection of vinyl albums. To save typing we also implemented the ability to perform a Google search passing in the album barcode and returning/displaying all the album information, including the cover artwork. I’ll blog about just how easy it was to implement Google searching soon.
Next we hosted all the server logic on a remote cloud server behind Symphony Bridge and showed how to manage the data remotely using the Synergy DBMS Manager (available on the download page at www.symphonyframework.net).
Next we moved to the client portion of the project – to build and deploy an app on the Android and iOS platforms to enable us to check if we have a particular vinyl in our collection. We built up the technology stack. First layer was the client data layer – code generated data objects built into a portable class library. Next we created the connection library which used commands to search for vinyl details using the barcode:
If we didn’t have the album in our collection we could call our stored procedure to perform the required Google search:
And if we chose to buy the album we could insert it into our collection directly from the device:
Our final portable library was the common UI code – using Xamarin Forms. This provides the ability to write the UI once and deploy to different target devices such as Android and iOS.
Up to this point, although there were a couple of “what was that…” moment’s things all built and ran just fine.
The final piece of the puzzle was to write the device specific code – and our first target was Android. We created the project, added the required resource (images, etc.) and after a couple of minor typo’s the project built. But something was not quite right and we could not get the program to successful deploy and run.
We’d hit the end of the day so aborted the attempt and regrouped to try to find out what had gone wrong. Once we have the solution I’ll post the entire project to GitHub and blog about it!
Now I don’t really believe in code gremlins, ghosts or phantoms, but throughout the week there were some strange goings-on, and to be honest I was having flash-backs to conference time 2009! Surely he was not back to try to mess up my workshop again?
Working with the many customers we have is a great opportunity to advance the software we write. Some time ago I blogged about Symphony Bridge – a server based utility that allows you to expose Synergy data and logic through Symphony Harmony using an SQL-like syntax. In essence you can write queries on the client like “select * from part” and the bridge server will return a collection of part objects that are based on a structure you have created in your repository. You can then bind these to grids or input controls on you windows or mobile applications or display them in web pages. In fact you can use the data in any Synergy .Net or non-Synergy application.
Another aspect of Symphony Harmony/Symphony Bridge is the ability to call a remote procedure using the syntax “exec @MyNameSpace.MyClass.MyMethod”. You can pass in arguments and again a data object or a collection of data objects are returned.
During a recent visit with one of our customers who is currently utilizing symphony Harmony and Symphony Bridge to provide third-party access to their systems to allow enquiries on orders, etc. I was asked about “providing the ability to return a standard object that contains the call status AND the response data”. Simple, no problem: Create an RPS structure that defines your response details – call status, error codes, and error message for example. Code generate the required data object and then customize it by exposing a collection of <DataObjectBase> (the base class of all data objects!) As I said – simple.
But the customer was not overly impressed – and they had an idea! Oh dear me thinks – these are seasoned C# developers and I’m not convinced I’ll be able to implement their ideas in Synergy .Net! But how wrong I was…. and without any changes to the Symphony Framework. The basic requirement is to have a “response” class that they can extend with any serializable “type” – be that a single instance or a collection of “type” – without any restrictions.
The starting point was the same – create the required response structure in the repository and code-generate the “response” class. This is the resulting class definition;
public partial class Server_response_Data extends Symphony.Conductor.Model.DataObjectBase
The code generation process creates all the required properties and the logic to serialize the data into JSON or BSON.
The next step was to create a second class with the same name as the response class but this time it will accept a generic – generics are quite cool and allow you to defer the specification of a type until that type is instantiated. So our generic response class definition looks like this;
public class Server_response_Data<T(new)> extends Server_response_Data
By extending the base code-generated class we get all the required Symphony capabilities. The “T” denotes the generic “type”. The (new) ensures that any type you provide must have a parameter-less constructor which ensures that this class can creates an instance of it. We can expose the property so it’s serializable;
public property Result, T
And in the constructor we can ensure there is an instance (to prevent null object exceptions);
public method Server_response_Data
Result = new T()
And that is about it. You can then write your server methods to create an instance of your response class, populate the generic “response.Result” with the required “type” and set the response properties accordingly. For example;
data response = new Server_response_Data<Part_Data>()
Will create a response class with the “Result” as a type of Part_Data data object. If you need to return a collection of Part_Data objects;
data response = new Server_response_Data<List<Part_Data>>()
It’s really as easy as that. On the client you simply make the remote EXEC call through Symphony Harmony;
result = DataExecute.RunDataExecute(connector,
& "exec @MyNameSpace.MyClass.MyMethod",
& new Server_response_Data<List<Part_Data>>()).Result
You can also await the call on a separate thread.
Big shout-out to Gareth for the idea and his persistence to make me get it working!
I’ll be using these techniques in my DevPartner 2017 post conference workshop as we build a mobile app from start to finish using Symphony Harmony/Symphony Bridge to access remote data and logic.
The Symphony Framework provides the ability to expose Synergy data as “Data Objects”. A “Data Object” or DO for short, is a class that exposes the fields of your repository structure as properties that can be accessed using Get and Set methods. These DO’s also provide access to the “raw” synergy record data through a property called SynergyRecord. The SynergyRecord property is the basic way to put record data into or get record data out of your DO. There are a lot of additional properties associated with DO’s, like its validity based on repository and custom validation rules, but those are for another blog. By exposing the individual field elements as Get/Set properties this allows us to bind to them from code (Synergy or C#/VB.Net) and in the WPF world the UI layer in XAML.
The Symphony Harmony framework allows you to select data from a Synergy DBMS file using standard SQL style syntax. Under the hood it uses the powerful SynergyDE.Select capabilities to access data in a file after parsing the SQL like query string. The data is returned as a collection of DO’s. A simple example could be;
Select * from group
Where “group” is the name of a structure/file relationship in your repository. The Symphony Harmony returns all the located records in the form of DO’s. This means we can bind to the individual properties exposed by the DO.
Harmony can accept more complicated requests, for example;
SELECT Id ,Description ,Quantity ,Cost_price FROM part WHERE cost_price BETWEEN 10 AND 20
Is a valid query that will return only the DO’s that match the where clause.
To show the capabilities of the Symphony Data Object and Symphony Harmony I’ve put together a simple “Synergy DBMS Manager” program that allows you to interrogate and manage data in a Synergy ISAM data file. You can select data using SQL like syntax and display the results to the screen. You can also update, insert and delete records again using SQL like syntax. To show the query above using the Synergy DBMS Manager;
The fields within the query can be typed in longhand or selected from the field list (retrieved dynamically from the DO). When the query is executed, the results grid is dynamically built to include only those fields selected.
As mentioned you can also modify the data in the file using an UPDATE command and you can insert new records using an INSERT command. To complete the capabilities you can also delete records using the DELETE command, but make sure you use a where clause or the whole file will be cleared.
The Synergy DBMS Manager application can be downloaded from SymphonyFramework.Net. You can also access full documentation on the same page or here. You will need a minimum of Synergy 10.3.1 runtime environment to run the Synergy DBMS Manager program. You will also need to create and build a library of Synergy Data Objects that represent your repository structure. This library is totally code-generated and full instructions are included in the documentation.
If you would like to take a look at the Synergy DBMS Manager but don’t have the time to build your library of data objects upload your repository files (zipped please) at: SymphonyFramework.Net and we’ll build it for you!
Why not take a quick look at the documentation to see how easy it is to use the Synergy DBMS Manager?
As I wrote about in my last blog the Symphony Harmony namespace provides the ability to execute select queries and stored procedure style method execution using SQL style syntax. The queries and procedures can be executed in-process or via the Symphony Bridge on a remote server via industry standard HTTP/HTTPS/TCP protocols as well as via a Service Bus Relay protocol. In the 3.2.6 release we have added the ability to fully manage the data in the SDBMS files via SQL this style syntax.
Accessing or selecting data through the Symphony Harmony namespace is simple. First you need to define your “connection” to the database. To do this you create an instance of the DBConnector class. For example;
data connector = new DBConnector(“SymLocal:user/password!SimpleHarmonyTestLibrary.TableMapper.MapTableToFile”)
The connection string defines how you want to access the data: SymLocal indicates that it’s in-process and specifying SymRemote indicates it’s via Symphony Bridge. If you are using Symphony Bridge you must include the “server” you wish to connect to – I’ll include an example shortly. The username and password allow you to provide authentication but that’s for another blog. The “SimpleHarmonyTestLibrary.TableMapper.MapTableToFile” is the named method that Symphony Harmony uses to translate the table name to a physical SDBMS filename, and it’s something you can code generate.
Here is an example of a remote access connection;
data connector = new DBConnector(“SymRemote:user/password@localhost:8081!SimpleHarmonyTestLibrary.TableMapper.MapTableToFile”)
Notice the server name and the port the Symphony Bridge server is listening on. Other than the connection string the usage of Symphony Harmony is identical regardless if it’s local or remote data access. Although here we are talking about local and remote data access – we are referring to where the code to perform the query is being executed, either locally in-process or via Symphony Bridge. We are not referring to the physical location of the SDBMS data files which may be local or remote and accessed via xfServer. Both local (in-process) and remote connections via Symphony Bridge can access data locally or via xfServer.
To select records from a file you use the SQL style SELECT syntax and call the DataSelect.RunDataSelect method. You need to instance the Symphony Data Object that will define the response data structure. For example;
data partItem = new Part_Data()
foreach partItem in DataSelect.RunDataSelect(connector, “SELECT * FROM part”, partItem).Result
Note here that the case of the command is not important however the case of string values within a where clause is. You can limit the fields returned, filter the data and order the results as you require. All of these are valid;
DataSelect.RunDataSelect(connector, “SELECT id, description, quantity FROM part WHERE quantity > 10”, partItem).Result
DataSelect.RunDataSelect(connector, “SELECT description, id FROM part WHERE description like ‘BRAKE’”, partItem).Result
DataSelect.RunDataSelect(connector, “SELECT cost_price, id, description FROM part WHERE cost_price < 1.99 ORDER BY cost_price “, partItem).Result
The order of the fields list is not important. You also don’t have to hard-wire the filter values as you can pass positional arguments. For example;
Data qtyValue ,int ,10
DataSelect.RunDataSelect(connector, “SELECT id, quantity, description FROM part WHERE quantity > :1”, partItem, qtyValue).Result
data descValue ,string ,”BRAKE”
DataSelect.RunDataSelect(connector, “SELECT id, description FROM part WHERE description like :1″, partItem, descValue).Result
Data qtyValue ,int ,10
Data costValue ,decimal ,1.99
DataSelect.RunDataSelect(connector, “SELECT id, description, cost_price FROM part WHERE cost_price < :1 AND quantity > :2 ORDER BY cost_price “, partItem, costValue, qtyValue).Result
All of the above will return a collection of data objects of type Part_Data().
As I mentioned above you can now maintain the data in your SDBMS files through Symphony Harmony. We have added the ability to insert data into an SDBMS file using Symphony Harmony. The DataInsert.RunDataInsert() method accepts an INSERT command and a data object and stores the passed-in data object data to the appropriate file. For example;
data partItem = new Part_Data()
partItem.Id = “ID1”
partItem.Description = “this is the description for part 1”
partItem.Technical_info = “lots of additional information for part 1”
partItem.Quantity = 5
partItem.Cost_price = 12.34
DataInsert.RunDataInsert(connector, “INSERT INTO part”, partItem).Wait()
The data in the partItem data object is extracted, placed into a Synergy record and stored into the SDBMS file. Any errors, like duplicate key, will be thrown on the client.
We have also added the ability to update the data in an SDBMS file using Symphony Harmony. The DataUpdate.RunDataUpdate() method accepts an UPDATE command, which should include a WHERE clause, and a data object, and updates the file with the passed data object data. You can optionally pass a list of fields that restrict the data to be updated. So for example if you application wants to simply update a field for a given record;
data numUpdated ,long
partItem.Cost_price = 999.99
numUpdated = DataUpdate.RunDataUpdate(connector, “UPDATE part SET cost_price where QUANTITY = 13”, partItem).Result
Will update ALL records that have a quantity value of 13 with the updated cost_price value of 999.99. The resulting numUpdated field will contain the number of records that were updated in the file.
The field list is optional, but it’s recommended! If you don’t specify the field list then the whole record is updated, so you must ensure that the data object contains all the required information otherwise you may get exceptions if key values that are defined none-modifiable are changed. You may also inadvertently overwrite changes made by other processes.
And to provide the fully SDBMS data management capabilities we have added the ability to delete data from an SDBMS file using Symphony Harmony. The DataDelete.RunDataDelete() method accepts a DELETE command, which should include a WHERE clause, and a data object and deletes the matching records from the file.
data numDeleted ,long
numDeleted = DataDelete.RunDataDelete(connector, “DELETE FROM part WHERE id = :1”, partItem, “ID1”).Result
Removes the required records from the file. There is no need to first select or lock them. The numDeleted field will contain the number of records that were deleted from the file. The where clause is optional so the following is valid;
numDeleted = DataDelete.RunDataDelete(connector, “DELETE FROM part”, partItem).Result
And will result in clearing the entire file – you have been warned!!
All this capability is now available in version 3.2.6 of the Symphony Framework, Symphony Harmony and Symphony Harmony Unplugged packages on Nuget.
The Symphony Harmony namespace allows access to data and logic through an SQL like syntax. For example you can select records from a file using a query such as “SELECT ID, DESCRIPTION FROM PART WHERE QUANTITY > 12 ORDER BY QUANTITY”. All matching records are returned from the query in the form of Symphony Data Objects. The data can be local or accessed via Synergy xfServer. The Symphony Bridge utility allows you to expose your query-able database via a standard Windows Communication Foundation (WCF) web service. So far so good.
Steve Ives and I recently had the opportunity to spend a week working together in the UK to “bang” heads together. Steve has always been an exponent of providing RESTful services to access logic and data which can be consumed by just about anything. So we set about using CodeGen to build a standard Restful service that will utilize the Symphony Framework to enable dynamic access to data and ultimately logic.
We soon had the basic service up and running. Out first implementation handled the standard GET verb – and returned all the records in the file. No filtering, no selection, just all the records retuned as a JSON collection. This is the standard API;
Now remember that Symphony Harmony allows you to filter the data you are requesting, so we next implemented the ability to provide the “where” clause to the query. So for example;
And using ARC (Advanced Rest Client which is a Google Chrome plug-in) we can test and query the service;
And we get back just the selected customer details – all those customers where CUSTST has value of CA.
As well as being able to filter the data we can also limit the results returned by Harmony to just the fields we need; this has the benefit of reducing the data being brought across the wire. But how can our REST server build the required data objects to just include the fields we select? By doing runtime code generation! Within our code generated data objects we added the ability to dynamically build the response data object to only include those fields requested by the client. The calling syntax, as provided by the API, is;
And again using ARC to test our server we can issue a command like;
This is requesting all records from CUSMAS where the CUSNM2 field contains the word “LAWN” and limiting the response data object to just three fields. The response JSON looks like;
Two perfectly formed data object that are limited by the fields in the selection list. If your Symphony Harmony connection to your data is via xfServer then only those selected fields will have been loaded from the file, again improving performance.
We also added the ability to limit the amount of data retuned by adding a “maxrows” option;
We have already added the ability to the Symphony Harmony namespace to perform inserts, updates and deletes using standard SQL syntax and we’ll be adding these capabilities to the appropriate rest verbs POST, PUT and DELETE. Watch this blog feed for more information.
One cool aspect of a Synergy UI Toolkit program has been list processing. When we introduced the concept of a list load method to populate the list as items were required was a huge step towards decoupling the program logic from the user interface. Because of this separation of concerns it’s actually very easy using the Symphony Framework to load a modern WPF data grid using an existing UI Toolkit list load method.
Our starting point has to be the UI, and that’s being rewritten in XAML. XAML allows data binding between class properties and the column elements of a data grid. We exposes our Synergy data by use of a Symphony Data Object. These data object classes represent your repository based data structures. The fields within your structures are exposed as the properties that the data grid will data-bind to.
Once we have the data grid defined we need to define the hooks between the collection of data we are going to expose to the data grid and the host programs list load method. First we call a generic method that will allow us to signal the required list loading requirements back to the host program. This snippet is going to call a generic method that will then raise the event back to the host:
We are passing the load method name and then various parameters that define the actual data we are going to load and any additional list load method data. Now we can raise the load method request to the host DBL program:
In the host DBL program we need to handle the event so we register an event handler:
The following code snippet dispatches the load request to the existing UI Toolkit load method. There are two formats to the request depending if the list has associated list method data:
So now we need to change the load method. If you have coded your list load method according to the standards laid out in the UI Toolkit manual there should only be a single line of code to change:
The DoingTK test is a flag we have set to indicate if the program is running with the traditional UI Toolkit or our new WPF UI.
We shall be drilling down into the ability to handle list loading during the DevPartner 2016 pre-conference workshop as we all migrate an existing UI Toolkit program to a modern WPF user interface.
It’s the tried and trusted way to get the users attention. At the slighting hint of an issue with their data entry you put up a big dialog box complete with warning icons and meaningful information.
We’ve all done it, and many programs we write today may still do it. Writing code using the Synergy UI Toolkit its common practice to write a change method to perform field level validation. When the user has changed the data and left the field – either by tabbing to the next or clicking the “save my soul” button – the change method executes and validates the entry. It is here were we stop the user in their tracks. How dare they give us invalid data – don’t they know what they should have entered? It’s an ever so regimented approach. The user must acknowledge their mistake by politely pressing the “OK” button before we allow them to continue. Users are usually not OK with this interruption to their daily schedule so there must be a nicer way to say “hey there, this data is not quite as I need it, fancy taking a look before we try to commit it to the database and get firm with you and tell you how bad you are doing at data entry?”
When migrating to a new Windows Presentation Foundation UI we can do things a little different and guide the user through the process of entering the correct data we need to complete a form or window. We will still use the same change method validation logic however as there is no reason to change what we know works.
When using the Symphony Framework you create Symphony Data Objects – these classes represent your repository based data structures. The fields within your structures are exposed as properties that the UI will data-bind to. These data objects are a little bit cleverer that just a collection of properties. Based on the attributes in the repository it knows what fields have change methods associated with them. Because of this the data object can raise an event that we can listen for – an event that says “this field needs validation by means of this named change method”. Here is a snippet of code registering the event handler:
The event handler simply raises the required “change method” event back to the host DBL program;
Back in the DBL program we can now listen for the change method events. Here is the event handler being registered:
Remember, we are now back in the host DBL code so we can now dispatch to the actual change methods registered against the field. This is a code snippet and not the complete event handler code:
We are calling into the original change method and passing through the required structure data and method data. Inside the change method we will have code that validate the entry and then, as this snippet shows, we can perform the error reporting:
If the code is running as a UI Toolkit program the normal message box dialog is used to display the message. However, when running with the new WPF UI the code provides the required error information against the field. No message boxes are displayed. To the user they will see:
The edit control background is coloured to indicate an issue with the data and the tooltip gives full details of the problem. When the user has entered valid data, the field reverts back to the standard renditions:
We shall be exploring the ability to handle field change method processing during the DevPartner 2016 pre-conference workshop as we all migrate an existing UI Toolkit program to a modern WPF user interface.
Menu processing is a fundamental requirement in any UI Toolkit program. Without menu columns and entries your program would not function. You also signal menu events from toolbars, and buttons placed on windows and lists. Once a menu entry of any sort is fired, even if it’s signalled from within the DBL code, there is usually a using statement that dispatches to the required segment of logic. When configuring a new Windows Presentation Foundation UI this technique is still valid.
The Symphony Framework UI Toolkit assists the developer to bridge the connection between the DBL host program and the commands associated with menu bars, toolbar, and buttons – basically any WPF control that can bind to a command, and that includes selecting an item within a data grid!
Before we head into how the Symphony Framework UI Toolkit helps let’s first look at some simple UI Toolkit script and code snippets. Firstly we can create menu entries in scripts:
Here we have a menu column called “mfile” with an entry called “f_new”. The important element is the entry name “f_new” as this is the menu signal name that is used within the DBL code. You can create toolbars in code that will signal a menu event, for example:
Here we have the same menu event name of “f_new” being signalled when the toolbar button is selected. We can also add buttons to tab containers;
Windows and lists can also have buttons added to them both in scrip and in code;
If we need to enable or disable the “f_new” capability within the UI Toolkit application we need to do this for all instances, for example;
The Symphony Framework UI Toolkit removes the verbosity of this structure of programming while retaining the same logical concept. Using the Symphony.UIToolkit.Menu.MenuController class allows you to create a command;
Now we have the command we can bind it to any WPF control that accepts a command binding. So for a menu;
We can utilise the same command on, for example, an Infragistics ribbon control;
Using a regular tool bar;
And of course as a regular button on an input form or data grid view;
In the host DBL code we can now simplify the control of the commands. By enabling the single command it changes the executable status of the all UI controls that it is bound to;
When the command is executed the toolkit menu entry is signalled to the host program. We need to define an event handler;
This is a code snippet and not the complete event handler code:
This code is setting up the required menu entry name and then calling into the host DBL code to process the menu select. In the host program we need to ensure that we dispatch to the menu processing code segment. In this example the original toolkit code was processing an input form. We continue to process the input window using the i_input() routine if the toolkit is still the active environment. If we are running using the new WPF UI then we simple process the menu event;
We shall be covering menu, toolbar and command processing during the DevPartner 2016 pre-conference workshop as we all migrate an existing UI Toolkit program to a modern WPF user interface.
I’m sometimes sceptical when somebody covers a song I know and love as I’m worried that their version may not bring with it the true spirit of the original track. If it’s not done right it just won’t be pleasing to the ear, and music should always invoke passion. When customers ask us to demonstrate how to put a new User Interface over an existing program I’m always conscious that our “cover” needs to retain the proven logic of the original program while offering the user a new and pleasing, easy to use and navigate, user experience.
In recent weeks I’ve been developing the Symphony UI Toolkit, which as the name suggests, helps you to migrate your Traditional Synergy UI Toolkit programs to a modern Windows Presentation Foundation (WPF) based UI. This new member to the Symphony ensemble provides a number of simple techniques for connecting between the WPF UI and the existing “event” driven DBL code.
One recent engagement where I utilise the whole Symphony Framework, including the new Symphony UI Toolkit, was to add a modern UI to an existing UI Toolkit program. The basic solution was to write the new UI in Synergy .NET using XAML for the UI components. Then host this in the existing Toolkit program using the DOTNET API. We started off with:
The program presented a list of items from which the user could select from. Other than the slightly dated look and feel the main problem with the application was that the user was restricted to seeing only the information on a single tab page at a time. The brief for the new UI was simple – make the pages dock-able.
Utilizing a number of core features within the Infragistics UI control set I was able to retain all the logic from the original program and bring a fresh new UI to the user:
Now as the user navigated the main list of items, while the docked panels display the relevant information. The grid provided the required filtering and grouping capabilities and selecting an item changed the fields on the input panels to edit mode so changes and additions could be made.
The Microsoft styled ribbon control replaced the traditional menu columns and button toolbar. Additional options were made available within an Outlook style navigation bar – which can be hidden with a single click.
The original program code was modified in a way that we can swap between running the traditional UI Toolkit UI and the new WPF UI by changing a single setting in the synergy.ini configuration file:
Although targeting the UI Toolkit the steps involved in migrating to a new WPF UI with the Symphony Framework will work just as well with almost any style of DBL program, and you can try it for yourself at DevPartner 2016. Join me in the recording studio for the Monday pre-conference workshop where together we’ll make a great new cover version of an old Toolkit program. The day will start relaxed as you write code to handle menu, toolbar and button commands. Then we’ll up the tempo and you’ll code event handlers to execute list load methods. Then we’ll jazz things up a little handling change methods and field validation. By the end of the day we’ll have a number 1 hit on our laptops.
By Steve Ives, Posted on January 28, 2016 at 9:55 am
We have just released a CodeGen update that includes a fix for a problem that was discovered recently related to the processing of enumerated fields. If your repository includes enumerated fields and you use the field selection loop token <SELECTION_VALUE> (or the Symphony Framework custom token <SYMPHONY_SELECTION_VALUE>) then we recommend that you update to the new version and re-generate your code. As a reminder CodeGen recently moved to GitHub, you can find the new release at https://github.com/Synergex/CodeGen/releases.
During DevPartner 2015 a number of people ran through the Utilizing the Repository tutorial which sets out to demonstrate how the meta-data stored in the repository describing your Synergy database can be utilized when building a modern Windows Presentation Foundation desktop application using Synergy and the Symphony Framework.
Using your repository, CodeGen and the associated Symphony Framework templates you can build, from the ground up, a complete WPF application, and this is exactly what you do during the tutorial.
Using the Model-View-View Model pattern you code-generate the model elements as repository based data objects that extend the base Symphony Framework DataObjectBase – this provides field level properties with validation and data bindings. Then we code generate the view – the UI element the user interacts with. The view comprises of windows containing the individual edit controls which in turn use code generated styles. These styles define the visual attributes and data bindings of each field in the repository.
Great – you would think. But I’ve been asked about a default behaviour of a WPF application a number of times and again at the conference, and that is the fact that edit controls, specifically text boxes, don’t auto-select all content when they receive focus. I also find it frustrating but thus far have been unable to think of a solution. “It’s a deal breaker” according to Gayle – who’d just completed the tutorial. Well considering Gayle is a rather fine chap I guess it’s time for me to look at the problem again. I spoke with Jeff @ Synergex who pointed me to a blog by Oliver Lohmann which addresses just this problem.
The solution is to register a behaviour against the TextBox control and handle the GotFocus event – and in the event handler force the selection of the data in the TextBox control. Simple!
And simple it was – and it usually is when you are looking for that “complex” answer. I’ve not done much with behaviours so far, but I think that is about to change! The Symphony Framework has been updated (did that on the plane home) and I’ll be releasing that to GuGet very shortly. The Symphony Framework “style” template will be updated – it’s now released as part of CodeGen – to reflect the new capabilities and normal “behaviour” will be resumed.