Integration
Integration Options.
Most folks will paste ProMaps into their file and use a properties table they already have for the properties they want to see in the map.
The remainder of these instructions assume you already have a table whose records you want to see in the map. If you don't, you can just paste our "Properties" table into your file and skip step 2 below.
Need Help?
Our products are designed so you can integrate them into your own FileMaker solutions yourself following the instructions in our online documentation, and our team is happy to provide any guidance you need at no additional charge. So please don't hesitate to reach out if you get stuck--we can likely get your integration unstuck with a quick phone call or email.
Alternatively, our trained and certified developers can do your integration for you from start to finish. Just pick up our minimum five-hour implementation package ($1,100) and send us your file (more complex integrations may require more time).
We can also help you build custom features in any FileMaker solution that involves one or more of our products, including customized deployments of SeedCode Complete. For these types of projects that involve custom-built features, please get in touch to discuss the details so we can give you an estimate of the cost and timeline.
Keys to Success
FileMaker is very sensitive to the order in which new code is pasted into a file--create layouts before you paste in a script looking for that layout and all will be well; paste the script in before the layout expected in that script has been created and you'll have some busted code that is particularly hard to unravel.
So, even if you're an experienced developer, follow the steps here carefully and in order--at least for your first ProMaps integration. =)
Step-by-Step Instructions: Pasting SeedCode ProMaps into your File.
1. Backup your file.
Really.
And this is important: review a couple of things you may want to change in your file before you get started.
If you want to use the "Properties" table in ProMaps as your properties table, instead of a table you already have, you can skip step 3 below.
2. Tables.
Import these three tables into your file from the ProMaps file: MapSettings, MapMarkerIcons and Areas. If you don't already have a properties table you can import ours as well: if you do, you'll want to import our Media table along with it.
If you're using FileMaker Advanced, you can just copy and paste the tables. If you don't have Advanced, from your file select File / Import Records... / File and then select the ProMaps file. Select the first of the tables to import and for the target, select "New Table". FileMaker will create the new table and calcs for you but you'll have to come back and uncomment some of the calcs that couldn't find the items needed: come back after you've imported all three tables this way and remove the leading /* and trailing */ from your calcs.
If you don't have Advanced, and that sounds like too much, we'd be happy to complete this step for you, just send us your file.
If you don't plan on using images in the map popovers or want to use existing images you don't need to import the "Media" table.
Pro Tip: Open up the import.log file FileMaker created. It's in the same directors as the file you just added these tables to. Keep this open and keep an eye on the "Error" column during this integration. When you paste fields or scripts into your file you'll want to see zeros in that column. When you don't see zeros it means there is something you need to check. Some errors are natural, such as when you paste the gm_... fields into your table, but for example you shouldn't see error at this point or after pasting layout objects. =)
3. Fields.
3.1 You will want an address, city, state, postal code in your solution. So it is preferred that you create all of the fields that are in the ProMaps "Properties" table in your solution. This will create the most seamless experience once initially integrated. Once things are working properly then fields can be renamed or deleted. At the very least "Status", "Type", and the address fields will make things work out of the box so make sure to add those.
If you have address fields already you'll want to rename yours to the names we use when generating Geo Codes: you can change your field names back after the integration is complete. The address fields we use when generating Geo Location Codes are:
_id (the primary key / unique ID for your table)
Address
City
State
PostalCode
Please make sure to rename your existing fields to match or add these to your table if you aren't using the ProMaps properties table.
3.2 Having renamed your fields, you can add ProMaps' required fields to your properties table from SeedCode ProMaps' "Properties" table.
The required fields are all prefixed with "gm" but you may want to just add all of the fields in the ProMaps "Properties" table for the most seamless integration. Once the fields are added you can rename them to whatever you would like.
If you are using FileMaker Pro Advanced you can copy the fields from ProMaps and paste them into the Properties table in your solution. None of the fields require modification at this point; you'll come back later to edit the field "gm_MarkerName".
If you aren't using Advanced and just have FileMaker Pro you will need to create these fields in your solution. You can copy and paste the field names themselves and the calculation contents if it is a calculation field.
Make sure to set the field types appropriately. Most "gm" fields are calculation fields so set them appropriately in your file. Pay attention to the returned data type as some are "text" and some are "number".
Pro Tip: If you're using FileMaker Advanced and just pasted these in, you may have gotten a 102 error on the field gm_MarkerName. That's natural but is the only error you should have gotten so far. If you got others it's likely the names of your fields in 3.1 above don't match those in ProMaps.
3.3 If you're using our media table, you're all set. But...
I'm using my own media table outside of my properties table.
If you're using your own, ProMaps has a routine to export thumbnails of your container fields for use in the map. It will export any media that has a thumbnail image so you can use that to control which images get exported.
In order for all that to work you'll need to add the gm_Thumbnail field to your media table AND rename your id, foreign key (the field that links your photo to the property, if any) and container field to match those in media. Again, you can rename these fields back when you're done.
Once those are corrected, add the z_...fields from ProMaps' media table to your media file.
I'm using a media field in my properties table.
Rename your media/photo field to "MediaContainer" and rename your primary key to "_id"--you can rename them both back once the map is up and running. Now copy and paste all the fields "z..." from ProMaps' media able into your table along with "gm_Thumbnail".
4. Value Lists.
Open ProMaps and recreate the 11 value lists from our file in your file. Feel free to use your list of statuses and types, but rename them to the value list names we're using in ProMaps: you can name them back later. The other values lists need to stay as they are.
This is one of the few things FileMaker Advanced does not make easier: you'll need to recreate these by hand, so take your time.
5. Table Occurrences.
Select File / Manage / Database and navigate to the Relationships tab where you can see the "relationship graph" for your file. If your properties table is not called "Properties" you will need to rename your TO for the rest of the integration--you can rename it back later. Locate your existing properties table occurrence (the table that has the records you want to see on the map) and name it "Properties" (make sure there are no spaces in the table occurrence name). You can change this name later. If you are using the ProMaps properties table it should already be named "Properties" and you won't need to change anything.
If you plan on using images in your map Popovers you will need to make sure your media table (the table that contains your property images) is named "Media". If your images are stored in the "Properties" table that will work too but our example layouts are set up to work with a dedicated media table as are our instructions. We recommend storing your media in a separate table for the sake of speed and a better data model.
6. Relationships
Staying on the Relationships tab, link "MapSettings" to "MapMarkerIcons" and to "Areas" as shown below. Double check that the table occurrence names match what we have in the ProMaps file, and make sure they are both cartesian joins ("X").
At this point, if you want to use property images make sure and create a relationship between the "Properties" table and the "Media" table. The preferred method is to relate the "ID" field in the properties table to the "PropertyID" field in the media table.
7. Layouts Part 1.
Create a few blank layouts in your file. (We'll paste in content for these layouts in a subsequent step.) You'll create one layout in your file for each layout in ProMaps (even though only some layouts are visible to users in the layouts menu, all these layouts are required. This is most easily done by creating the first layout listed below, deleting the header and footer part, and duplicating it to create the others.
Note: it is important that you don't already have any layouts (or layout folders) with the same name as any of the ProMaps layouts. If you do, please rename your layouts or folders before continuing.
Here is how to create that first layout: Create the layout "Home" and then visit Layout Setup and uncheck the box beside "Show field frames when record is active". Base the layout on the theme "Classic Refined: Cool". Also uncheck the box to enable QuickFind. Keep duplicating and renaming layouts making sure to switch "Show records from" to match the associated table in ProMaps.
You may want to create the layout folders and match the integration we have in the ProMaps file. This is not necessary but will keep things organized nicely in your file.
Once you're done, go through and make sure these layouts have exactly the same names as the ones in ProMaps, and that the headers and footers are deleted from each.
Finally, you may delete the default layouts created when you imported tables in step 2 if you would like. This is note necessary but if you want to keep your layouts to a minimum they are not required.
8. Scripts.
Import the scripts from ProMaps. When importing, just click the check box beside the folder "ProMaps" and all the scripts within that folder will import.
If any scripts are reported as being "renamed" because of a conflict, quickly scan the imported scripts for names ending "2" and correct them. For example, ProMaps has a script called "Load Map Settings". If you already have one with that name ours will get imported as "Load Map Settings 2". To fix this rename yours to something like "Load Map Settings Main" and then rename ours to "Load Map Settings". Our scripts must have the same names as they do in the ProMaps file for the following step to work.
Look in the import log after importing these scripts and you should see that they all came in with zero errors. If you do see errors, then either the field names or table names you entered above don't match those in ProMaps. Delete the imported scripts, correct the field or table names, and add the scripts again until you get zero errors.
You may want to backup your work again at this point.
9. Layouts Part 2.
Now copy the layout contents from each layout in ProMaps and paste them into the layout of the same name in your file. Do every layout. You'll be warned that you'll be increasing the height of each layout; that's OK.
While the layout heights in FileMaker 12 take care of themselves automatically, the layout widths do not. You'll need to manually move the right edge of the layout out to the same place it is on the layouts in our file (for most layouts this is flush with the rightmost object edge).
When you get to Property_Detail feel free to edit this layout as you see fit, adding your own fields and buttons. Just be sure to keep the "gm_Location" field (it should be off the visible area of the layout) and the address fields. The address fields have script triggers set on them to look up the geo location code when modified.
10. Layout Script Triggers.
Since layout level script triggers don't come over when you copy and paste layout elements, you'll have to recreate these. Fortunately there are only a few.
Layout: Property Details (1 trigger)
Trigger: OnLayoutExit (in Browse Mode Mode)
Script: "Property On Layout Exit"
This script trigger refreshes the map data so any changes or new records added will show up on the map for that user. You may want to modify this script trigger so it only runs on record commit, or maybe not at all if you want your users to get in the habit of clicking the "Refresh Map" button instead.
Layout: Properties Map (1 trigger)
Trigger: OnRecordLoad (in Browse Mode)
Script: "Map On Record Load"
This script trigger should be on any layout you add the map to.
Layout: ProMaps Setup (1 trigger)
Trigger: OnRecordLoad (in Browse Mode)
Script: "Go To Settings Panel (panelNumber)"
Parameter: $$sc_mapSettingsPanel
This script activates the selected layout object/panel.
Now you may already have layouts you want to use for your properties. If so, you will probably want to set up that layout to automatically lookup geo codes when an address is entered:
To lookup geo codes in your layout It works best to set the geo code lookup to trigger based on the OnObjectSave script trigger. You can set any field to trigger the geo code lookup by assigning the OnObjectSave trigger to run the script called "GeoCodeAddress For ProMaps". The recommended fields to set this trigger on are the "Address", "City", and "State" fields. The "gm_GeoLocation" field does need to be on the layout for the lookup to work but you can put that field off the layout boundary so it isn't visible.
11. Setup.
Here is where you start making the map your own, editing settings for what displays on the map and popovers.
11.1 Google API Key. Google now requires that you enter an API key tied to an account with billing enabled in order to use the Google Maps API features. Please follow the instructions here to setup your account and retrieve the API key, then enter that key into the appropriate field on the ProMaps Setup layout. You'll want to set the Google API Key value before clicking the "Apply Settings to Map" button, or your properties won't be properly geocoded.
11.2 General Setup. Navigate to the layout "ProMaps Setup" and make sure there are zero records (delete the one you created if there is one. Click on the button "Apply Settings to Map" to load all of the default settings. Here you can edit the default image (remove the default image if you aren't going to use images). You can also edit or add new map marker icons. We have provided a few different colors to get you started.
11.3 Popovers (Map your data). Click the "Format the Popover" link in the sub-menu to the left. This is where you will map which fields will show up in map popovers. If you have used the same field names as we do in ProMaps things should already be mapped correctly but you may want to make some modifications depending on what you want to display. You can read up on editing the popover here here.
11.4 If you are using your own Properties table, look at each of the elements listed below and fix any broken field references therein. Be sure to also uncomment any calculations as necessary. If you are unsure which fields should be used, refer to a stock copy of the ProMaps file.
Some layout objects to check...
Properties Detail layout
Remap off-screen gm_Geolocation field
Remap all local on-screen fields
Properties List layout: gm_MarkerImage field as button
Script parameter for "Show Property on Map (propertyID)" script
Popover Setup layout
Remap all local off-screen "Utility Fields"
Remap all local on-screen fields
ProMaps Properties Utility layout
gm_Geolocation field (off-screen)
Some script steps to check...
ViewPropertyRecord (propertyID) script
Check the Perform Find step
Address OnSave script
Set Variable value (Address, City, State fields)
Set Field gm_GeoLocation
Filters And Headers script
Fields in Set Variable step calcs ($sc_propertyType, $sc_propertyStatus, $$sc_mapDataPackage)
Check Property Integrity script
3 Perform Find steps
Replace Field Contents
GeoCodeAddress For ProMaps script
Perform Script parameters
A couple of tips on field mapping the popover setup...
The fields are managed based on their object names. Please don't add new fields to the layout, make sure to edit existing fields to keep their appropriate object name.
Make sure that the utility fields to the right of the visible area on the Popover layout are mapped. Check that the _id field is mapped to your property ID field.
Try to avoid using complex calculations or summary fields as this will slow down the map.
12. Add the "Upon Opening"/"Initialize ProMaps" script to your file's opening script.
Whenever your file is opened, ProMaps needs to do some initialization. If you have your own script that runs when you open the file, you can just add a perform script step. Otherwise, you'll want to add it as the "OnFirstWindowOpen" script trigger in your File Options
If you want to go straight to ProMaps, you will choose the "Upon Opening" script. If you want to just initialize ProMaps, and NOT navigate to ProMaps, you will choose the "Initialize ProMaps" script.
Note: If you have a large number of properties and you don't want them all to load when first initializing ProMaps, but would rather always send a found set to ProMaps, you can comment out the "Build Property List" and "Export HTML" Perform Script steps on lines 24 and 27 of the "Initialize ProMaps" script. Keep in mind that the map will then show no properties until you send a found set to it.
13. Run a Script.
That's it. Run the script "Compile Map Data And Settings" to compile all of your settings and generate any missing geo location codes. You should now be able to use the map.
Next Steps / Going Further
The map in ProMaps is context independent. This means you can Paste the map and filter fields onto any layout and it will work without modification. So feel free to add the map anywhere you need it regardless of the table.
Enjoy!
