Converting from Clarify Desktop to Dovetail Agent (part 3)
Welcome to part 3 of the series on converting an application from the Clarify Desktop environment to work in Dovetail Agent/Admin. The Employee Manager Utility (EMU) is being migrated into Dovetail Admin, and will provide the tools needed to manage workgroups and the employees that are assigned to them.
In the installment of the series, the functionality for the Add… button of the form is going to be implemented. This is going to be a different method that what is normally used in Dovetail Admin due to the fact that workgroups are actually just elements in the WORKGROUP user defined list. EMU adds a lot of information and configuration capability for a workgroup, but there needs to be a record in table_workgroup to hold the details.
The Add… button has a small hint that it will have different behavior in the text of the button itself. The ellipsis is an indication that there is more to come, and in this case a dialog will open that shows the existing workgroups from the user-defined list, and allow for a workgroup to be added or selected for management in EMU.
Using a dialog has a few advantages over a pop-up window that are worth discussing before diving into the code. The biggest gain is that there will not be a new window that pops open, but a dialog window is just displayed on the page instead. All of the details from the parent workgroup pages can be accessed, and the browser doesn’t have any extra overhead to maintain.
The dialog consists of a div element, and it has a title are, a list box for the workgroups, a name text field, and a pair of button. The functionality is separated from presentation for this dialog using a technique commonly name “unobtrusive JavaScript”, and this is a great example of where that makes a big difference. By not mixing presentation with structure, it is easier to change the layout throughout the application simply by changing the style sheet. The required html (shown below) is pretty simple, and all of the necessary CSS and JavaScript is added elsewhere in the document. The code for the dialog is added at the bottom of the workgroup.asp page, just below the </form> tag.
The CSS was added in the head section of the page for the dialog. The CSS shown below sets up all the dialog styles for each of the elements. When complete, all of the CSS for the page will be moved into its own file, which can then be cached by the browser.
#overlay, #underlay_ie_hack { width:694; height:424; }
#workgroupDialog { display:none;height:320px;width:370; }
#workgroupList { text-align:left;margin:1.2em;width:290;height:104;border:1pt #aaa solid;overflow:auto; }
#workgroupAdd { text-align:left;margin:1.2em; }
#newWorkgroup { width:200px;margin:.4em 0 1em 0; }
The functionality for the dialog is all done in JavaScript, and makes use of the jQuery JavaScript Library. jQuery is a fast and concise JavaScript Library that simplifies HTML document traversing, event handling, animating, and Ajax interactions for rapid web development. In both Dovetail Admin and Dovetail Agent, the jQuery library is included on every page (via inc_utility.asp), so adding code for the dialog can be done without having to add the library itself.
The last section of the JavaScript code does most of the work at this point. The $(document).ready(function() { line is a jQuery statement that checks the document and waits until it’s ready to be manipulated, then executes any code within the ready event. In the case of this dialog, event handlers are added for the Add… button to open the dialog, and for the Cancel button to close the dialog. This makes the dialog available, and now it can be tested to make sure it works so far. Here is the result:
The buttons are different sizes, but additional CSS can take care of that. In anticipation of the next step, the highlight class is also shown here. These two lines are added to the style section:
.btn { width:80px;height:22px;font:bold 12px Arial; }
.highlight { background-color: #ffff80; }
The next step is to fill in the list of available workgroups when the dialog is opened. The data for this list comes from the WORKGROUPS user-defined list. The catch is that any records in table_workgroup need to be excluded from the list shown in the dialog. Those records are the ones that show up in the grid at the top of the page – which haven’t been displayed yet because there are no records yet. The list needs to be filled with the correct list each time the Add dialog is opened, and jQuery again provides a very handy (and simple) method to make this happen.
Since the empty box at the top of the dialog is a <div> element, it can contain other html elements. jQuery provides a load function, which fetches data from the server and places the returned HTML into the <div> element. This technique uses AJAX and allows data to be loaded from the server without a browser page refresh. Here is the function needed to get the data and load it into the <div> element:
The call to this function is added inside the showWorkgroupDialog function. In the code shown above, there are just two statements inside the function. The first line clears out any previous text that had been added to the input text field, and the second statement does the AJAX call to the server. The jQuery load function takes “workgroupList.asp” as the URL to follow, and a callback function to be performed after the data returns and is loaded into the <div> element.
The callback function just adds event handling for each of the workgroups that have been added to the available workgroup <div> element. jQuery makes this JavaScript pretty simple to understand. Each workgroup in the list can be clicked on, and doing so will highlight it and copy the workgroup name to the input text field.
The big piece of this process is the page that gets the data, and builds the html to return. The core of this page (show below) get the list of workgroups from the server cache, get the current workgroups from the database, and build list elements for each available workgroup and sends the html back as response text. The entire file can be viewed here.
Dissecting the code above, the list of workgroups is retrieved from FCApp and table_workgroup is queried for any existing records. Looping through the array and excluding the records from the table results in a string of <li> elements that are returned to the client code.
After adding the showWorkgroups function and adding the call inside the showWorkgroupDialog function, the dialog now looks like this:
Now the functionality for clicking the dialog’s Add button can be implemented. This is simply going to make another AJAX call to the server using jQuery, and the page that is run on the server will add the new record to table_workgroup. After the page returns successfully, the new workgroup can be displayed in the grid at the top of the page. Here is the event handling code for clicking the dialog’s Add button, which is also added inside of the showWorkgroupDialog function:
$("#addWorkgroup").click(addRecord);
The addrecord function does the work when the button is clicked. It validates that an available workgroup has been selected or typed in to the text box, and then makes the AJAX call to addWorkgroup.asp to add the record to table_workgroup.
If successful, the List link is clicked on the parent page, and the grid is shown that has all of the workgroups, including the one that was just added. If there was an error in the AJAX process, then a message would be displayed.
The addWorkgroup.asp page does the work in this case, and just has one job to do. The name of the new workgroup is passed in via query string, and table_workgroup is queried to make sure it doesn’t already exist. If everything is okay, then a success message is returned, otherwise an error message is sent back to the caller.
After successfully adding a workgroup, the grid shows the workgroup at the top of the page.
That wraps up this part of the series. The major topics covered here included adding a dialog to the page, adding JavaScript for the html element functionality, adding some CSS to make things appear as designed, and finally introducing how AJAX is used to make the application processing more seamless in how it interacts with the server.
For the next post in the series, adding the html elements for management of the workgroup itself can get started. The Replace button functionality will also be covered so the changes made to a workgroup can be persisted to the database.
