Many-to-many checkboxes revisited, part 11: Attaching to an ABC browse
by Unknown user
I originally chose the School.app as my test bed for applying my many-to-many checkbox classes to an ABC app. I had a browse that looked like this:
After looking at the data dictionary a bit more closely I discovered a number of things I didn't like, chief among them the lack of an unexposed autonumbered primary key in each table. I changed the primary keys to use new autonumbered fields. I made a few other changes to make the dictionary suit my purposes better, but I won't bother going into them here because this is an article about managing many-to-many links not about writing course registration software.
The second time it's a template
Eventually I'll want a template I can throw at this procedure, but my first step in writing almost any template is to write the source I want generated and verify that it works. Then all the template has to do is reproduce the code I wrote, which makes writing the template much simpler since I'm not also debugging the generated code.
An ABC persister
I previously created a persister class that can write the linking data to a TPS file, and looking at that code I can see that it contains much of the code that I'll need if I want to write to any file managed by the ABC classes. But I don't want to derive my ABC persister from that class because CML_Data_ManyToManyLinksPersisterForTPS contains an actual definition of a TPS file which I won't use and which will only confuse the situation.
In a case like this where I have two classes that will share a lot of code, the logical solution is to remove that common code to a class that can be the parent to both classes.
My first thought is to call this new parent class CML_Data_ManyToManyLinksPersisterForFile since it contains the standard file handling code.
And before I get it working for ABC classes I really should make sure that the refactored CML_Data_ManyToManyLinksPersisterForTPS class still does its job after it is derived from CML_Data_ManyToManyLinksPersisterForFile.
But I have another problem. When I look at CML_Data_ManyToManyLinksPersisterForTPS I see that it's derived from CML_Data_ManyToManyLinksPersister, and that class implements code for three methods:
CML_Data_ManyToManyLinksPersister.CloseDataFile procedure
code
if not self.DataFile &= null
close(self.DataFile)
end
CML_Data_ManyToManyLinksPersister.OpenDataFile procedure!,bool
code
dbg.write('CML_Data_ManyToManyLinksPersister.OpenDataFile')
self.CloseDataFile()
if not self.DataFile &= null
share(self.DataFile)
if errorcode()
create(self.DataFile)
if errorcode()
message('Unable to create data file ' & self.DataFile{prop:name} & ' ' & error())
return false
end
share(self.DataFile)
if errorcode()
message('Unable to open data file ' & self.DataFile{prop:name} & ' ' & error())
return false
end
end
end
dbg.write('returning true')
return true
CML_Data_ManyToManyLinksPersister.Save procedure(long leftRecordID,CML_Data_ManyToManyLinksDataQ linksDataQ)
x long
code
if self.OpenDataFile()
dbg.write('CML_Data_ManyToManyLinksPersister.Save')
loop x = 1 to records(linksDataQ)
get(LinksDataQ,x)
if LinksDataQ.IsLinked and not LinksDataQ.IsPersisted
self.AddLinkRecord(LinksDataQ.LeftRecordID,LinksDataQ.RightRecordID)
LinksDataQ.IsPersisted = true
put(linksDataQ)
elsif not LinksDataQ.IsLinked and LinksDataQ.IsPersisted
self.RemoveLinkRecord(LinksDataQ.LeftRecordID,LinksDataQ.RightRecordID)
LinksDataQ.IsPersisted = false
put(linksDataQ)
end
end
self.CloseDataFile()
end
The third method is no problem, but the first two methods will absolutely not work for ABC (or for that matter Legacy) files as they will do an end-run around the standard open counting. So that code needs to be moved up to the TPS persister class; once I've done that I can use CML_Data_ManyToManyLinksPersister as the base class for CML_Data_ManyToManyLinksPersisterForABC and I will not need CML_Data_ManyToManyLinksPersisterForFile (at least not right now).
The CML_Data_ManyToManyLinksPersister methods now look like this:
CML_Data_ManyToManyLinksPersister.Construct Procedure()
code
CML_Data_ManyToManyLinksPersister.Destruct Procedure()
code
CML_Data_ManyToManyLinksPersister.AddLinkRecord procedure(long leftRecordID,long rightRecordID)!,bool,proc,virtual
code
return false
CML_Data_ManyToManyLinksPersister.CloseDataFile procedure!,bool,proc,virtual
code
return false
CML_Data_ManyToManyLinksPersister.LoadAllLinkingData procedure(long leftRecordID,CML_Data_ManyToManyLinksDataQ linksDataQ)!,bool,proc,virtual
code
return false
CML_Data_ManyToManyLinksPersister.OpenDataFile procedure!,bool,proc,virtual
code
return false
CML_Data_ManyToManyLinksPersister.RemoveLinkRecord procedure(long leftRecordID,long rightRecordID)!,bool,proc,virtual
code
return false
CML_Data_ManyToManyLinksPersister.Save procedure(long leftRecordID,CML_Data_ManyToManyLinksDataQ linksDataQ)!,bool,proc,virtual
x long
code
if self.OpenDataFile()
!dbg.write('CML_Data_ManyToManyLinksPersister.Save')
loop x = 1 to records(linksDataQ)
get(LinksDataQ,x)
!dbg.write('Got LinksDataQ record ' & x)
!dbg.write('LinksDataQ.IsLinked ' & LinksDataQ.IsLinked)
!dbg.write('LinksDataQ.IsPersisted ' & LinksDataQ.IsPersisted)
if LinksDataQ.IsLinked and not LinksDataQ.IsPersisted
self.AddLinkRecord(LinksDataQ.LeftRecordID,LinksDataQ.RightRecordID)
LinksDataQ.IsPersisted = true
put(linksDataQ)
elsif not LinksDataQ.IsLinked and LinksDataQ.IsPersisted
self.RemoveLinkRecord(LinksDataQ.LeftRecordID,LinksDataQ.RightRecordID)
LinksDataQ.IsPersisted = false
put(linksDataQ)
end
end
return self.CloseDataFile()
end
return false
As you can see the only method that is still implemented is Save(), because that's the only code that's truly common in all situations. Everything else can change depending on the kind of data store in use (which isn't necessarily a traditional database).
I moved the open and close code up to CML_Data_ManyToManyLinksPersisterForTPS, but as that's pretty much a throwaway class I won't go into the details here. I did recompile my UITest application and the class does function as expected, so all's well there.
Here's the declaration for CML_Data_ManyToManyLinksPersisterForABC. Note that it references ABFile.inc because the class contains a reference to the ABC FileManager object.
include('CML_IncludeInAllClassHeaderFiles.inc'),once
Include('CML_Data_ManyToManyLinksPersister.inc'),Once
include('ABFile.inc'),once
CML_Data_ManyToManyLinksPersisterForABC Class(CML_Data_ManyToManyLinksPersister),Type,Module('CML_Data_ManyToManyLinksPersisterForABC.CLW'),Link('CML_Data_ManyToManyLinksPersisterForABC.CLW',_CML_Classes_LinkMode_),Dll(_CML_Classes_DllMode_)
Initialized bool,private
LinkFileKey &key,protected
LinkFileLeftIDField any,protected
LinkFileManager &FileManager,protected
LinkFileRightIDField any,protected
ManageFileOpenAndClose bool
Construct Procedure()
Destruct Procedure()
AddLinkRecord procedure(long leftRecordID,long rightRecordID),bool,proc,derived
CloseDataFile procedure,bool,proc,derived
Init procedure(FileManager linkFileManager,*key LinkFileKey,*? LinkFileLeftIDField, *? LinkFileRightIDField)
LoadAllLinkingData procedure(long leftRecordID,CML_Data_ManyToManyLinksDataQ linksDataQ),bool,proc,derived
OpenDataFile procedure,bool,proc,derived
RemoveLinkRecord procedure(long leftRecordID,long rightRecordID),bool,proc,derived
End
And here is the method source:
Member
Map
End
Include('CML_Data_ManyToManyLinksPersisterForABC.inc'),Once
include('CML_System_Diagnostics_Logger.inc'),once
CML_Data_ManyToManyLinksPersisterForABC.Construct Procedure()
code
self.Initialized = false
self.ManageFileOpenAndClose = false
CML_Data_ManyToManyLinksPersisterForABC.Destruct Procedure()
code
CML_Data_ManyToManyLinksPersisterForABC.AddLinkRecord procedure(long leftIDField,long rightIDField)!,derived
code
if not self.Initialized then return false.
clear(self.LinkFileManager.File)
self.LinkFileLeftIDField = LeftIDField
self.LinkFileRightIDField = rightIDField
if self.LinkFileManager.Insert() = Level:Benign then return true.
return false
CML_Data_ManyToManyLinksPersisterForABC.CloseDataFile procedure
code
if not self.Initialized then return false.
if self.ManageFileOpenAndClose
if self.LinkFileManager.Close() = level:benign then return true.
return false
end
return true
CML_Data_ManyToManyLinksPersisterForABC.Init procedure(FileManager linkFileManager,*key LinkFileKey,*? LinkFileLeftIDField, *? LinkFileRightIDField)
code
self.LinkFileKey &= LinkFileKey
self.LinkFileLeftIDField &= LinkFileLeftIDField
self.LinkFileManager &= LinkFileManager
self.LinkFileRightIDField &= LinkFileRightIDField
if not self.LinkFileKey &= null |
and not self.LinkFileLeftIDField &= null |
and not self.LinkFileManager &= null |
and not self.LinkFileRightIDField &= null
self.Initialized = true
end
CML_Data_ManyToManyLinksPersisterForABC.LoadAllLinkingData procedure(long leftIDField,CML_Data_ManyToManyLinksDataQ linksDataQ)
code
if not self.Initialized then return false.
free(linksDataQ)
if self.OpenDataFile()
clear(self.LinkFileManager.File)
self.LinkFileLeftIDField = LeftIDField
set(self.LinkFileKey,self.LinkFileKey)
loop
next(self.LinkFileManager.File)
if errorcode() or self.LinkFileLeftIDField <> LeftIDField then break.
clear(linksDataQ)
linksDataQ.LeftRecordID = self.LinkFileLeftIDField
linksDataQ.RightRecordID = self.LinkFileRightIDField
linksDataQ.IsPersisted = true
linksDataQ.IsLinked = true
add(linksDataQ)
end
return self.CloseDataFile()
end
return false
CML_Data_ManyToManyLinksPersisterForABC.OpenDataFile procedure!,bool
code
if not self.Initialized then return false.
if self.ManageFileOpenAndClose
if self.LinkFileManager.Open() = Level:Benign
self.LinkFileManager.UseFile
return true
end
return false
end
return true
CML_Data_ManyToManyLinksPersisterForABC.RemoveLinkRecord procedure(long leftIDField,long rightIDField)!,derived
code
if not self.Initialized then return false.
clear(self.LinkFileManager.File)
self.LinkFileLeftIDField = LeftIDField
self.LinkFileRightIDField = rightIDField
get(self.LinkFileManager.File,self.LinkFileKey)
if not errorcode()
if self.LinkFileManager.DeleteRecord(0) = Level:Benign then return true.
end
return false
I originally passed in the file reference as well, but then I realized that there is already a reference as a property of the FileManager instance. I also initially wanted a way to do the equivalent of a Clear(prefix:Record) but there doesn't seem to be a way to keep a reference to a Record structure. That's not a problem because Clear(File) works just as well. The only downside is it might be marginally less efficient since it also clears any Blob or Memo fields, which are not included in a Record.
Adding the code to an ABC app
After making the above-noted changes to the dictionary and fixing up the app, I had a browse that looked like this (students on the left, courses they're registered for on the right):
To begin with I needed a couple of global includes (the third one is just so I can add some debug statements if needed):
When I first threw the checkbox code into my test app I put together a couple of routines in place of some embed code. I didn't have a really good reason for doing that (too many legacy apps on my brain lately?), and when Mike Hanson looked at the code he quickly pointed out that the code should be in local class methods.
Here's the procedure-level class that wraps up all of the functionality:
CheckboxList class
ListCheckbox &CML_UI_ListCheckbox
Persister &CML_Data_ManyToManyLinksPersisterForABC
Links &CML_Data_ManyToManyLinks
Construct procedure
Destruct procedure
DisplayCheckboxData procedure
Init procedure
LoadEnrollmentData procedure
SaveEnrollmentData procedure
end
And here are the methods, declared at the end of the procedure:
CheckboxList.Construct procedure
code
self.ListCheckbox &= new CML_UI_ListCheckbox
self.Persister &= new CML_Data_ManyToManyLinksPersisterForABC
self.Links &= new CML_Data_ManyToManyLinks
CheckboxList.Destruct procedure
code
dispose(self.ListCheckbox)
dispose(self.Persister)
dispose(self.Links)
CheckboxList.DisplayCheckboxData procedure
code
self.ListCheckbox.LoadDisplayableCheckboxData()
CheckboxList.Init procedure
code
self.Persister.Init(Access:Enrollment,ENR:kStudentIDCourseInstanceID,|
ENR:StudentID,ENR:CourseInstanceID)
self.Links.SetPersister(self.Persister)
self.ListCheckbox.Initialize(Queue:Browse,Queue:Browse.InClass_Icon,|
Queue:Browse.CLA:CourseInstanceID,?List:Enrollment,,self.Links)
CheckboxList.LoadEnrollmentData procedure
code
log.write('CheckboxList.LoadEnrollmentData')
self.SaveEnrollmentData()
StudentBrowse.UpdateBuffer()
self.links.LeftRecordID = STU:StudentID
self.Links.LoadAllLinkingData()
self.ListCheckbox.LoadDisplayableCheckboxData()
display(?List:Enrollment)
CheckboxList.SaveEnrollmentData procedure
code
self.Links.SaveAllLinkingData()
This is the mostly-working version of the code. There are a few wrinkles which I'll get to after I show the embed code.
Right after the window is opened I call the Init method which gets all of the objects ready for use:
At the end of ThisWindow.Run I added code to save any changes on exiting the procedure:
I needed a call to the LoadEnrollmentData() method whenever the user selected a different student record, but I had problems. I initially put my code in the WindowManager.TakeNewSelection method for the Student list box. And I found that using the arrow keys to select a new record worked fine, but using the mouse keys did not update the record in memory.
I asked Mike about this, and he replied:
The better place is inside the Browse method. You cannot access that embed from the Control's embed list. You have to go to the ABC objects tree in the procedure level embeds, or even better, the source view (a.k.a. embeditor). Search for ".TakeNewSelection " (note the period at the start and space at the end).
You cannot assume that PARENT.TakeNewSelection will load your record. Even though it does load the newly selected record, it calls ThisWindow.Reset, which may change things.
To be safe, call either MyBrowse.UpdateBuffer (which fetches the highlighted record from the queue and updated the corresponding fields in the record), or MyBrowse.UpdateViewRecord (which additionally fetches the record from the database). Avoid low level code like GET(Queue:Browse:1,CHOICE(?Browse:1)).
Also, I often want the user's "click" to fire some code, even if the record hasn't changed. I'll use the TakeAccepted handler for the control event, rather than (or in addition to) the browse class' TakeNewSelection method.
The bottom line is that your approach may vary from situation to situation. If you want to stick with one approach that will work most of the time, then use the browse method's TakeNewSelection method (via the embeditor). You may want your code to go before or after the PARENT call, depending on your situation. Regardless, do a call to UpdateBuffer or UpdateViewRecord, to be sure that the newly selected record is in memory.
I put my code in StudentBrowse.TakeNewSelection, and I had my LoadEnrollmentData method call StudentBrowse.UpdateBuffer, and that solved my update problem. Thanks Mike!
I thought I was all set, but my procedure still had some issues. I discovered that although my linking records were saved to the database, the display was more than a little funky especially when I tried scrolling through the page loaded list of courses.
I fixed the checkbox display problem by re-applying the checkbox data every time the right hand list changes:
In hindsight this makes perfect sense. The right hand list, like the left hand one, is a page loaded browse, so if the user scrolls and brings up a new record or page of records, the internal list of which records are checked must be consulted and the icons applied accordingly.
And I found a really silly coding error that only showed up once I started working with an actual database. Have a look at the LoadDisplayableCheckboxData and see if you can spot it:
CML_UI_ListCheckbox.LoadDisplayableCheckboxData procedure
x long
code
if not self.ManyToManyLinks &= null
loop x = 1 to records(self.ListQ)
get(self.ListQ,x)
if self.ManyToManyLinks.IsLinkedTo(x)
self.ListQIconField = CML_UI_ListCheckbox_TrueValue
dbg.write(x & ' true')
else
self.ListQIconField = CML_UI_ListCheckbox_FalseValue
dbg.write(x & ' false')
end
put(self.ListQ)
end
end
You'd have to be fairly well immersed in the code to notice this, but the problem is the line
if self.ManyToManyLinks.IsLinkedTo(x)
which needs to be
if self.ManyToManyLinks.IsLinkedTo(self.ListQRightRecordID)
With that final fix the sample app worked almost as expected.
This time the problem was with the scroll bar buttons. When you click a scroll bar button the list box doesn't fire a TakeNewSelection event until you release the mouse. Meanwhile any new list box items that scroll up don't have their list boxes drawn:
The first solution I tried was to add one line of code to the end of the CheckboxList.DisplayCheckboxData method:
select(?List:Enrollment,choice(?List:Enrollment))
That partially solved the problem. While the mouse was held down the icons were still blank, but as soon as I released the mouse the icons were drawn. I also tried a Display() on the list but that caused the entire control to flicker.
I fixed the problem by adding a method call to the SetQueueRecord method, which is where you normally insert code to modify the displayed values.
Here's the code for SetCheckboxIcon:
CheckboxList.SetCheckboxIcon procedure
code
if self.links.IsLinkBetween(self.Links.LeftRecordID,self.ListCheckbox.ListQRightRecordID)
self.ListCheckbox.ListQIconField = CML_UI_ListCheckbox_TrueValue
else
self.ListCheckbox.ListQIconField = CML_UI_ListCheckbox_FalseValue
end
As all of the values specified here are already being tracked by the classes I think I can move the code down a level rather than have to write it out every time I use the classes. I'll look into that next time.
A nice side effect
The checkbox list has a benefit I hadn't thought through beforehand. Ordinarily if you have a child list box, any time you change the parent list box selection the child list box reloads completely. But because the list of linking records is managed internally by the class, and then applied to the right hand list box in whatever state it happens to be, you can go to whatever page you want on the right hand list box, then select any record on the left hand list box and the right hand list box will still display the same records. Only the checkboxes will change based on the underlying data.
For instance, I can go the the last page of courses, then scroll through all the students and see who is registered for any of those courses. It feels right - this is how it should work.
I often have this experience when writing classes - although there's more work up front, there are many little paybacks (and sometimes big paybacks) later on in the process.
Next time: A template to make it all easy.
Download the source (the checkbox classes are also available on GitHub but are not yet exported from the library).