Pro Maps Integration

--> '''Some layout objects to check...'''

--> '''Some script steps to check...'''

-->Perform Find step

-> A couple of tips on field mapping:

--> Trigger: OnLayoutExit (in Browse Mode and Find Mode)

--> Trigger: OnRecordLoad (in Browse and Find Mode)

--> Layout: Property_Detail (1 trigger)

--> Layout: Properties_Map (1 trigger)

-> 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 Classic theme. 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.

-> '''3.2''' 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 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.

-> '''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.

-> Add new fields to your events table from SeedCode ProMaps' "Properties" table:

-->'''Map Search Mode''' script
-->Set Variable $$sc_searchDataPackage

-> A couple tips on field mapping:

-->Fields in Set Variable step calcs ($sc_propertyType, $sc_propertyStatus, -->$$sc_mapDataPackage)

“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

“Properties List” layout: “Show these Properties On Map” button
Script parameter for “Show List on Map” 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)

“ViewPropertyRecord (propertyID)” script
Perform Find step

“Address OnSave” script
Set Variable value (Address, City, State fields)
Set Field gm_GeoLocation

-->“Filters And Headers” script

-->“Check Property Integrity” script

-->“GeoCodeAddress For ProMaps” script

-->“Map Search Mode” script

“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

“Map Search Mode” script
Set Variable $$sc_searchDataPackage

-> '''11.1 General Setup.''' Navigate to the layout "ProMaps Setup" and click on the button "Compile Map Data And Settings" 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.1 General Setup.''' Navigate to the layout "ProMaps Setup - Click on the button "Compile Map Data And Settings" 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.2 Popovers (Map your data).''' Click the "Popover" button in the navigation in the upper right. 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 [[ProMapsPopovers | here]].

->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 (address, tempObjectName, resultFieldName)". The recommended fields to set this trigger on are the "Address", "City", and "State" fields. You can see the best method for passing in the appropriate script parameter on those fields in the "ProMaps" file. 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.

-> Assign 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.

-> '''3.1''' Add new fields to your events 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.

-> '''3.2''' Fields that don't begin with a "gm" are not required but you will probably want them in your solution too. For example, you will probably 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.

->The address fields we use when generating Geo Location Codes are:

-> ''Note: it is important that you don't already have any layouts (or layout folders) with the same name as any of the layouts below. If you do, please rename your layouts or folders before continuing.''

-> Here is how to create that first layout: Create the layout and then visit Layout Setup and uncheck the box beside "Show field frames when record is active". Base the layout on the Classic theme. Also uncheck the box to enable QuickFind. Keep duplicating and renaming layouts making sure to switch "Show records from" to match the associated table shown in the list below.

-> Finally, you may delete the default layouts created when you imported tables in step 3 if you would like. This is note necessary but if you want to keep your layouts to a minimum they are not required.

-> 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. 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 want to use the "Properties" table in ProMaps as your properties table, instead of a table you already have, you can skip to step 3 and start importing the tables.

'''2. Fields.'''

-> '''2.1''' Add new fields to your events table from SeedCode ProMaps' "Properties" table:

->If you are using FileMaker Pro Advanced you can copy the fields from ProMaps and paste them into the Properties table in your solution. If you are using 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.

-> '''2.2''' Fields that don't begin with a "gm" are not required but you will probably want them in your solution too. For example, you will probably 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.

'''Next Steps / Going Further''' 

-> '''11.1 General Setup.''' Navigate to the layout "ProMaps Setup - 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.

-> 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 (address, tempObjectName, resultFieldName)". The recommended fields to set this trigger on are the "Address", "City", and "State" fields. You can see the best method for passing in the appropriate script parameter on those fields in the "ProMaps" file. 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.

%center%  http://www.seedcode.com/rootimages/stikipad/pro12/graph2.png

-> '''11.2 Popovers (Map your data).''' Click the "Popover" button in the navigation in the upper right. 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. interesting to create a [[MultiLineEvents | multi-line event]] display.

--> Events with just a single date should have a start date: if your event has just an end date the calendar will fail. The same goes for times: if there is only one time, make it the start time.

--> Don't use calcs for things like the dates, times, or resources. The calendar wants to edit these values when you drag items around, and it can't edit calcs. Use auto-enter calculations instead if you must.

'''12. Clean Up.'''

-> Rename your Sample Events table occurrence to something that makes more sense for you. And add the script "Upon Opening" to your file's opening script, removing the go to layout stuff if you'd like. If you're using multiple windows or renaming windows in your own upon opening script, you may want to run our Upon Opening routine the first time your users open the calendar in a new window rather than at the beginning. 

'''13. Run a Script.'''

-> That's it. Run the script "Initialize ProMaps" script and you should now be able to use the map.

Enjoy!

!! Next Steps

Now that you've gotten up and running, you'll likely want to return to a few places and do a more thorough job of mapping the calendar to your events. Here are the places we like to revisit:

-> Event Details. You may have left some fields unmapped here. You'll probably also want to double check the arrows / buttons which jump from an event to its related contact or project. Learn more about these here: [[jump to my contact]].

-> Event List. You may have unmapped fields here as well. Also be sure to enter layout mode and double check the summary parts on the [[Event List]].

-> To-Do Details and List. If you're using the To-Do list, you likely skipped mapping some fields on its detail and list layouts as well.

-> Now you may already have layouts you want to use for your properties. If so, take a moment to read about that here: using [[your own Event layouts]].

-> '''11.1 General Setup.''' Navigate to the layout "ProMaps Setup - On Startup..." and "Load Source Settings at Startup --- Describe Your Sources Here ---" and follow the comments throughout the script, changing settings and field mappings as necessary.

-> '''11.2 Map your data.''' Go to the layout "Source No 1" (in the Developer layout folder) and follow the directions on the layout to map the fields there to the fields in your SampleEvents table. Map the "Summary" to a simple field for now like your event's title, just to get you up and running, then return here and try mapping the summary to something more interesting to create a [[MultiLineEvents | multi-line event]] display.

-> '''6.1 Relationships Part 1.''' Staying on the Relationships tab, link "CalendarRows" to "CalendarInterface" to "CalendarColors" as shown below. Double check that the table occurrence names match what we have in the sample file, and make sure the open end of the ≥ operator is pointing toward "CalendarInterface":

-> At this point, if you want to show event colors in list view as we do in the Event List or Event Detail layouts, copy our field "z_sc_ColorCalc" from SampleEvents and add it to your events table. Remove the /* and */ from the beginning and end of the calc and replace our use of the field "status" with the equivalent field in your events table: this is the field we used to color code events in the calendar.

-> '''6.5. Relationships Part 2.''' ''If you intend to remove the Gantt chart you can skip this section.''

-> If you'll be using the Gantt Chart you'll want to connect a few more things in the graph. First, create a relationship from CalendarRows to SampleEvents like this, where "id" is the primary key (the unique ID) in your events table. :

%center width="500%  http://www.seedcode.com/rootimages/stikipad/pro12/graph3.png

-> Then attach SampleEvents to your Contacts, Projects, and possibly your Phases table occurrences, as shown here:

%center% http://www.seedcode.com/rootimages/stikipad/pro12/graph4.png

-> It probably make sense to create new instances of these to attach to SampleEvents, but you don't have to. You'll likely want to rename your table occurrences to "Sample..." for now so that items pasted in later will line up. (Big time saver) If you don't have a Phases table, don't worry: phases are completely optional.

-> 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 SeedCode Calendar (even though only some layouts are visible to users in the layouts menu, all these layouts are required, except for "Demo Expired"). 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 layouts below. If you do, please rename your layouts or folders before continuing. (And yes, FMP's design functions can't tell the difference between a layout and a folder, so a folder named "Calendar" will cause problems also.)''

-> Here is how to create that first layout: Create the layout and then visit Layout Setup and uncheck the box beside "Show field frames when record is active". Base the layout on the Classic theme. Also uncheck the box to enable QuickFind. (If you want to search the calendar using QuickFind you can leave this enabled on the EventList layout, or use %newwin% [[http://www.seedcode.com/cp-app/ste_cat/fmsearchresults | fmSearchResults]] to extend QuickFind. Do this after you've followed these instructions and are up and running.) Keep duplicating and renaming layouts making sure to switch "Show records from" to match the associated table shown in the list below.

-> Again, you don't need to add the sample contact, project, and phase layouts unless you don't have any of your own. But you '''do''' need to create the layouts in the Developer and Additional Skins folders.

-> You may want to create the separator layouts we have as well (these are based on CalendarInterface) but that is just cosmetic. Make sure each layout is based on the table occurrence shown below.

-> Once you're done, go through and make sure these layouts have exactly the same names as the ones in SeedCode Calendar, and that the headers and footers are deleted from each.

-> Finally, delete the default layouts created when you imported tables in step 3.

-> Now you may already have layouts you want to use for your Event List and Event Details. If so, take a moment to read about that here: using [[your own Event layouts]].

-> If you're using the [[To-Do List]] add the To-Do Details and To-Do List layouts as well.

%center% http://www.seedcode.com/rootimages/stikipad/pro12/layoutlist.png

-> Import the scripts from SeedCode Calendar. When importing, just click the check box beside the folder "SeedCode Calendar" and all the scripts within that folder will import. There will be a number of errors reports when you import: this is normal. In "Setup" below we'll remap some of the fields and settings in these scripts to values in your file.

-> However, 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, the calendar has a script called "Upon Opening". If you already have one with that name ours will get imported as "Upon Opening 2". To fix this '''rename yours''' to something like "Upon Opening Main" and then rename ours to "Upon Opening". Our scripts must have the same names as they do in the SeedCode Calendar file for the following step to work.

-> Now copy the layout contents from each layout in SeedCode Calendar and paste them into the layout of the same name in your file. Do every layout, including Calendar Rows and Calendar Color Records. You'll be warned that you'll be increasing the height of each layout; that's OK.

-> When you get to Event Details feel free to edit this layout as you see fit, adding your own fields and buttons. Just be sure to keep the following 3 objects: the "repeat" button, the "show repts..." button below it, and the large "close..." button at the bottom of the screen. You can come back and edit this layout later, for now, just get the Summary, Date, and Time fields lined up with the relevant fields in your events table.

-> Just as you needed to click on fields on Event Details and point them at the proper fields in your table, you'll need to do the same to the Event List layout, and the on the To-Do Details and To-Do list, if you're using those, Again, you can map the basic date, time, and summary fields now so you know the calendar is working. We have a note at the end of these instructions reminding you to come back here and finish cleaning these layouts up.

--> Layout: Calendar Home & Docs (1 trigger)
--> Trigger: OnRecordLoad (in Browse Mode)
--> Script: "Load Home Layout"

--> Layout: Calendar (1 trigger)

--> Script: "Load Calendar Layout"
--> (Do this on "Calendar - no Side Menu" also, along with the "Calendar iPad" and "Calendar iPad - no Side Menu" layouts.)

--> Layout: Event Details (1 trigger)
--> Trigger: OnRecordLoad (in Browse Mode)
--> Script: "On Event Record Load"

--> Layout: To-Do Details (1 trigger)
--> Trigger: OnRecordLoad (in Browse Mode)
--> Script: "On Event Record Load"

--> Layout: Repeat Options (1 trigger)
--> Trigger: OnRecordLoad (in Browse Mode)
--> Script: "Set initial repeat variables"

--> Return to the Calendar Home layout when you're done and enter Browse Mode.

-> Here is where you start making the calendar your own, editing the scripts that control the calendars behavior and default settings. Read through these scripts slowly: you won't need to change every setting in them, but you'll change many and it's good to take your time so you remember what settings are available to you.

-> '''11.1 Configure the calendar.''' Edit the scripts "Load Calendar Settings - On Startup..." and "Load Source Settings at Startup --- Describe Your Sources Here ---" and follow the comments throughout the script, changing settings and field mappings as necessary.

-> That's it. Run the script "Upon Opening" script and you should see your events in the day view.

-> 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 2 and move on to the "Tables" section.

If you are using FileMaker Pro Advanced you can copy the fields from ProMaps and paste them into the Properties table in your solution. If you are using 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".

-> Import three tables into your file from SeedCode Calendar: CalendarInterface, CalendarRows, and CalendarColors. (If you're using data separation, add these tables to your interface file.)

-> If you're using FileMaker Advanced, you can just copy and paste the three tables. If you don't have Advanced, from your file select File / Import Records... / File and then select the SeedCodeCalendar file. Select the first of the three 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'd like to use the calendar's [[To-Do List]] and don't have your own To-Do table already, you can import our ToDoList table into your own file at this time as well. Leave it named "ToDoList" and that will keep things easier in the following steps.

->''You'll see we also have placeholder tables for contacts, projects, and phases. You presumably already have tables in your file representing these entities, and you'll line these up later. If you don't have a contacts or projects table, and wish you did, you may want to pause this integration and take a look at %newwin% [[http://www.seedcode.com/complete | SeedCode Complete]], which already has our calendar linked to a rich contacts and project management system.''

-> Open SeedCode Calendar and recreate the seven value lists from our calendar in your file. Feel free to use your list of statuses and resources, but rename them to the value list names we're using in SeedCode Calendar: you can name them back later. The other values lists need to stay as they are, though you can feel free to change the time formats in "Calendar Times" to suit your tastes. You might want to do that later though, once you have this up and running.

-> Here, and in what follows, you don't need to import anything to do with SampleContacts or SampleProjects as you'll likely already have these things in your file. That is, you likely have a method of selecting contacts and projects and will want to use your existing method on the Event Details layout. (However, even if you do have an existing method, creating Contacts and Projects values lists now will let the Event Detail layout find those value lists when you paste the layout into you file. We also use this Projects value list on the calendar's filters: another good reason to create them now.)

-> Select File / Manage / Database and navigate to the Relationships tab where you can see the "relationship graph" for your file. Click the little green plus button in the lower left to create a new occurrence of your events table (the table that has the records you want to see on the calendar) and name it "SampleEvents" (make sure there are no spaces in the table occurrence name). You can change this name later.

-> If you have a separate table of contacts you can create a new table occurrence of that as well and name it "SampleContacts" (again, with no quotes or spaces in the name). Link this to the SampleEvents table occurrence you just created using the same field matching you use elsewhere: this is likely from the SampleEvent's contact ID to the unique ID of the contact in SampleContacts. Do the same with projects, if you have projects, creating a new instance of Projects named "SampleProjects" and link it to SampleEvent's project ID. You can rename these table occurrences once you're up and running--just remember you'll need to edit one of the calendar's configuration scripts [[Renaming Tables | after you rename]].

-> If you want to use the "Properties" table in ProMaps as your properties table, instead of a table you already have, just import it into your file in step 2 below and skip step 5.

-> '''2.1''' Add two new fields to your events table from SeedCode Calendar's "SampleEvents" table:

--> zscTimestampStartCalcNum
--> zscTimestampEndCalcNum

-> Edit the definitions for these calcs, removing any leading / trailing comment tags if you pasted the fields in using FileMaker Advanced (that is, remove the /* and */ from the beginning and end of the calc). Then replace the DateStart, TimeStart, etc. fields referenced in these calculations with the relevant fields from your events table. Make sure both calcs return the form "number" and that both are indexed.

-> It may be that you don't have an end date field in your solution. You may also lack the time fields mentioned in the next steps (start and end times). The simplest thing is to add these fields to your events table: that makes the integration simpler and lets you take advantage of multi-day events should the scope of your events change. (Note that if you want to enforce that events never have times or never span more than 1 day you can use auto-enter calcs in these newly created fields to force them to be blank.)

-> If you create new fields, make sure the date fields are of the type "date" and the time fields are "time".

-> '''2.2''' Next, add the following Auto-Enter Calculated Value option to the TimeStart field in your events table (you can copy this here or from the definition in SampleEvents):

--> Case ( \\
Self = Time ( 24 ; 0 ; 0 ) ; Time ( 24 ; 0 ; 1 ) ; \\
Self = Time ( 0 ; 0 ; 0 ) ; Time ( 0 ; 0 ; 1 ) ; \\
Self > Time ( 24 ; 0 ; 0 ) ; Self - Time ( 24 ; 0 ; 0 ) + 1 ; \\
Self )

-> Make sure you '''uncheck''' the "Do not replace existing value" checkbox. This Auto-Enter option is needed if you want events to be able to start at midnight.

-> '''2.3''' Now add the same Auto-Enter Calculated Value option to the TimeEnd field in your events table. Again, make sure you '''uncheck''' the "Do not replace existing value" checkbox. This Auto-Enter option is needed if you want events to be able to end at midnight.

-> '''2.4''' If you plan to use the calendar's gantt charts. repeating events, or email notifications add a few more fields from our SampleEvents to yours:

--> z_LinkedWithinProject
--> z_MilestoneSort
--> z_Notified
--> z_Repeating_id

Most folks will paste SeedCode Calendar into their file and use an events table ''they already have'' for the events they want to see in the calendar.

If you don't need to have the calendar "in" your file, you can still link the two files, pointing the calendar at your events table instead of the "SampleEvents" table it comes with. Linking in this way is much faster but means you'll have two files instead of one. (The chief disadvantage of this is that you have to have the same accounts and passwords in each file, unless you set the calendar file to auto-open with its own low access password for everyone.)

If this sounds like it might be for you, follow our instructions for the [[Quick Integration]].

The remainder of these instructions assume you already have a table whose records you want to see in the calendar. If you don't, you can just paste our "SampleEvents" table into your file and skip step 2 below.

You may also have more than one table (or more than one date field in a table) that you want to see in the calendar. Don't worry about that for now: get one table/field up and running and then you can come back and configure [[MultipleSources | additional event sources]].

The most common mistake folks make integrating the calendar (or moving any FMP code from file to file) is performing steps in the order. 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; past 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 calendar integration. =)

!! Step-by-Step Instructions: Pasting SeedCode Calendar into your File.

-> If you want to use the "SampleEvents" table in SeedCode Calendar as your events table, instead of a table you already have, just import it into your file in step 2 below and skip step 5.