Clip Manager 4 Occurrence Selector
Occurrence Selector's goal in life is to help you select occurrences in the FileMaker Relationship Graph, also called the FRG. The FileMaker FRG is located in the field definitions dialog, it's the 3th tab view item. As soon as your FRG gets more crowded, it becomes increasingly hard to find the occurrences you are looking for. For a developer, time is money, and we saw we were spending to much time finding the needles in the haystack. Using Occurrence Selector, waisting valuable time locating occurrences is a thing of the past.
Occurrence Selector does it's selecting chore by typing the occurrence name. Try it yourself. You can never type fast enough to get to those occurrences with a longer name. But Occurrence Selector can do the fast typing part for you.
Selecting an occurrence
Click on the occurrence in the black HUD list. Clip Manager now focuses the FRG graph and starts typing the occurrence name. This works best if you have a good naming scheme like anchor-buoy. More about the anchor buoy method  here. Don't expect 100% accuracy, because e.g. the occurrence "customers_invoices" looks like the occurrence "customers_invoices_invoicelines", and on the first try, you could be selecting the second occurrence when you want the first one. Fortunately, when you keep on clicking, you will arrive at the occurrence you're looking for.
Finding an occurrence
At the top of the Occurrence Selector HUD window is a search field. Occurrence Selector will filter the list of occurrences, based on the "contain" logic. So just typing a part of the occurrence name is enough.
Directly under the QuickFind field is the base table popup menu. You'll be selecting all occurrences of a base table. This combines with the QuickFind. So don't forget to select "All Base Tables" if you're searching for other occurrences again...:-)
The list of occurrences
Occurrences of tables that are in the current file, are in plain format, external occurrences are in italic. In a more recent release you are able to hold the option key down, and see more information about the occurrence, like the file it belongs to, and the base table.
Still useful in the other tab views
While in the table view of the field definitions dialog, selecting an occurrence wil select the base table of that occurrence.
Whiile in the field view, Occurrence Selector wil select the table from the popup menu on top of the field list, to select the correct base table.
Of course Occurence Selector wil not be able to resolve the items in italic in your occurrence list, because they are external ones.
Enabling and disabling Occurence Selector
When Occurrence Selector gets in your way, you can hide it from the status menu. There is a small icon there in the form of a clipboard. You can also use the option-c shortcut to toggle it.
Occurence Selector will automatically show and hide when the field definitions window is opened and closed, unless you disabled it in the status menu.
Occurrence Selector wil also temporary hide and show when double clicking an occurrence in the FRG. After you come back to the graph, the occurrence will be highlighted in the HUD list. It wil also temporarily hide when you double click the relation itself. When you come back from these 2 dialogs, Occurrence Selector wil not query the graph again, to save time.
How it works
A more recent feature in Occurrence Selector is the bookmarks popup. Bookmarks are locations in your FRG that you can name. The principle is simple. Occurrence Selector keeps track of the horizontal and vertical scrollbars of the FRG "scrollview". Each bookmark is given a name, and represents a horizontal and vertical value of the scroll bars.
Occurrence Selector is able to keep track of bookmarks on a file name level. So you can have different bookmarks for file A and file B. If file A is on a server, it's considered a different file than file A on your desktop. You can see all bookmarks you've made in the "OccSelect" preference pane, so you can maintain everything more easily.
The bookmarks popup is initially rather barren. It contains an entry "Add Bookmark…" and another one "Delete Bookmark".
Adding an occurrence is done by positioning yourself correctly in the FRG, and then selecting "Add Bookmark…". A small dialog let's you input the name of your bookmark. From then on, you can always jump back to that location using that bookmark, because it will be added to the popup menu.
Deleting a bookmark is done this way: first you select the bookmark, then you select "Delete Bookmark", and it will be removed from the popup menu. Kindoff a minimalistic approach, but we just wanted to avoid clutter in the Occurrence Selector Panel.
There's a few other hidden features. Suppose you add to your graph on the bottom. This wil ruin the bookmark positions, because they are relative positions to the length and width of the graph surface. Fear not. Scroll to the right position ( the one the bookmark SHOULD have ) and select the bookmark with the option key held down. The "Add Bookmark" dialog wil come up again, just click OK and the bookmark value is saved again. A little trick: put a dummy occurrence far down in the graph ( not to far, to avoid FileMaker bugs! ). This leaves you ample space to add occurrences, without changing the bookmark values.
One more thing
Designing and testing the bookmarks, we thought it was a good idea to bring you back the last place you were in the FRG, when you left it temporarily. This works even when you did not bookmark your last position in the graph.
Occurence Selector is not correctly selecting my occurrences, why is it having problems?
Occurrence Selector works by "typing very fast". Since the contents of the FRG view is not Cocoa yet, the only way to select an occurrence is to start typing. There are a number of limitations here, that you can find out by trying this typing technique manually.
Occurrence Selector is not showing me the occurrences that are in my Field Definitions dialog, instead it shows occurrences of another file. What's happening?
Occurrence Selector queries FileMaker for the current file using a function that is similar to "Get( FileName )". When you select a script in file X, then switch to file Y, then switch back to the script of file X, file Y remains the current file and there is no easy way for Clip Manager to find out that this particular situation is happening ( Clip Manager should have to know which file the script window belongs to, which it doesn't ). To avoid this from happening, make sure that the file where the script belongs to, is also in the foreground. This has changed in since FileMaker Pro 11. FileMaker Pro 11 uses a new API that let's Clip Manager query a specific file. Make sure to uncheck "use old FQL engine to query occurrenes" in the "Advanced" preference pane of Clip Manager.
I'm having trouble using Occurrence Selector with occurrences that have extended characters, like Japanese.
First of all, check "use old FQL engine to query occurrences" in the "Advanced" preference pane of Clip Manager. Due to a bug in the new FQL engine, it provides Clip Manager with garbage when it queries for the occurrences. This way, you will be already able to list the occurrences. Unfortunately, this is where it stops with languages like Japanese, because it has a different "input method", so the fast typing trick doesn't work. Try it manually, and weep.
Occurrence Selector does not show my newly created occurrences, and does not discover I renamed or deleted my occurrences. Is this a bug?
No, it's something of a "design limitation". As long as you don't commit your changes to the database by clicking the OK button, the database file does not contain all the changes you've made. And we are querying the database file, not the relationship graph. Another design was not possible.
Clip Manager Bridge plug-in
The occurrences selector uses this plug-in to obtain information from the database, so it can populate the HUD dialog.
More information about the Clip Manager Bridge plugin can be found here.