Embedding The Calendar
Integration Options.
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 copy/paste or import our "SampleEvents" table into your file and skip steps 2 and 5 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 additional event sources.
Keys to Success
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; 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 calendar integration. =)
Step-by-Step Instructions: Pasting SeedCode Calendar 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.
2. Custom Functions.
This step requires FileMaker Advanced. If you don't have FileMaker Advanced, please get in touch and we'd be happy to get a copy of your files and perform this step for you.
Open Dayback.fmp12 and navigate to "File -> Manage -> Custom Functions". Select all of the custom functions (there are three) by shift-clicking and copy them (edit -> copy). Then go back to your file and open up the custom function dialog "File -> Manage -> Custom Functions" and paste all of the custom functions you have just copied.
3. Tables.
If you don't already have a table in your file for events, you can copy/paste or import the "SampleEvents" table from DayBack into your file..
Import two tables into your file from SeedCode Calendar: CalendarInterface, 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 two 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 two 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 the two 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'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 SeedCode Complete, which already has our calendar linked to a rich contacts and project management system.
4. Relationship Graph
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 after you rename.
4.1 Contacts and Projects
Note, if your events are linked to contacts, you can create a relationship between SampleEvents and SampleContacts using the same match fields you use for this kind of relationship in your file.
If you're using the projects or our gantt charts you'll want to do the same thing to our SampleProjects table occurrence and our SamplePhases (if you're using Phases, if you're not just leave it alone). Point these at the relevant tables in your file and make sure that they are connected to SampleEvents by the unique ids in each table.
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 SeedCode Complete, which already has our calendar linked to a rich contacts and project management system.
If you deleted the sample Contact, Project, or Phase table occurrences from your graph as we do in our video, be sure to visit the script "Load Source Settings at Startup --- Describe Your Sources Here ---". There you'll see two variables declared with the name of these tables. Replace those table names with "" (blank) or the calendar will ask where they are when you run the calendar's upon opening script.
5. Adding New Fields
You'll copy and paste some fields from our SampleEvents table into your events table: fields the calendar needs in order to run. Some of these are SeedCode's calc fields, and some are just date and time fields calendars expect. If you don't have time fields for your events, or a DateEnd field, for example, you may want to copy and paste those in at the same time. You don't need to use these fields, but the calendar expects them and having them there now 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.)
Open up DayBack.fmp12 and select File / Manage / Database, selecting the "Fields" tab of the "Manage Database" window and select the "SampleEvents" table. You'll copy a few fields from here and add them to your file. If you have FileMaker Advanced this is as simple as copying all the fields you don't have and those prefaced with "DBk_" (for "DayBack"). I generally copy these, though you might already have fields to use for status and resource...
Status
Resource
DBk_ColorCalc
DBk_EventSummaryCalc
DBk_LinkedWithinProject
DBk_MilestoneSort
DBk_Notified
DBk_Repeating_id
DBk_TimestampEndCalcNum
DBk_TimestampStartCalcNum
DBk_Unused
DBk_WebViewerEventData
DBk_WebViewerSource
...and pasting them into your file. If you don't have FileMaker Advanced, please get in touch and we'd be happy to get a copy of your files and perform this step for you.
5.1 Field Definitions
You'll now edit the definition for some of the fields you pasted in, selecting your fields for the DateStart, TimeStart etc. fields used in the calculation's let statements.
Here are some notes on each of the fields you'll need to edit. Some of these fields you can come back to later after you see the calendar working with your own data. Remember, for each field you'll edit you need to remove the leading and trailing "comment" tags (the /* and */) from the calc.
Resource: If you copied our resource field you're good to go. If you're using your own you may want to copy the auto-enter calc from our field as it adds "none" to the resource field if no resource is specified. This means that when you go the resources tab you can see all the events you haven't yet assigned a resource, and then drag then to open resources to schedule them.
DBk_ColorCalc: (you can come back to this one later). This field isn't used *in* the calendar but is here in case you want to show the same calendar colors in your FileMaker Layouts. Read more about editing this field later in "Event Colors".
DBk_EventSummaryCalc: This field is used to calculate which information about your event shows on the calendar in Day, Week, and Month views. For most users this is a combination of the event title and some other fields about the event. Begin by just replacing "Summary" with the field you'd like to see in the calendar, you can use our DBk_Unused field for the rest of the items for now and then come back to fine tune this once you have the calendar working. So a quick edit of this field might leave the editable part looking like this:
s = Summary ; // the title of your event
desc = DBk_Unused ; // your event's description or notes field
cont = DBk_Unused ; // your contact's name (optional)
ph = DBk_Unused ; // your contact's phone number (optional)
em = DBk_Unused ; // your contact's email (optional)
desc = DBk_Unused ; // your event's description or notes field
cont = DBk_Unused ; // your contact's name (optional)
ph = DBk_Unused ; // your contact's phone number (optional)
em = DBk_Unused ; // your contact's email (optional)
Having done a simple mapping like this, you can come back here later and flesh this out to include all the information you'd like to see in the calendar.
DBk_TimestampEndCalcNum and DBk_TimestampStartCalcNum: Edit this calc to use your own date and time fields. You may not have an end date field in your solution; You may also lack the time fields mentioned in this calc. 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.)
DBk_WebViewerSource: This is the field we use to populate the event details popover when you click on an item in the calendar. If you don't have some of these fields, like "contactID" use can use "DBk_Unused" for now. The date and time fields are required, so are the summary and the "id" which should be the primary key of your table. Be sure this field (and none of these newly created fields) is "commented out"--that is, it shouldn't begin with /* and end with */. If it does, delete those characters.
5.2 Auto-Enter Calcs for Times
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 )
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.
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.
5.3 Fields for Contacts and Projects
If your events are linked to contacts and/or projects, there are two new fields you'll need to add to these tables: DBK_WebViewerSource and DBK_WebViewerData. You can copy these from the SampleContacts table that comes with DayBack. Only the first of these needs to be edited, and in it you'll specify which of your fields is the primary key in the table and which field you want to be shown as the name of the contact when you select them from a list. So edit this section of the calc...
id = id ;
name = NameFull ;
...to look something like this:
id = MyContactID ;
name = MyNameLastFirst ;
5.4 Pause and Save Your Work.
Really. It's a good habit to get into. =)
6. Value Lists.
Open SeedCode Calendar and recreate the four value lists from our calendar in your file. Feel free to use your own list of statuses, resources, and projects, but rename them to the value list names we're using in DayBack: you can name them back later. The other value list is for selecting a language. We detect the appropriate language automatically so this is only necessary if you would like to manually select a new language. Although we recommend copying it over even if you don't plan to use it just so you don't get a field that is missing its value list.
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 DayBack (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 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 Minimalist theme if you're using FM14, or the Classic theme for FM13. 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. 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 Calendar Developer folder.
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 DayBack, and that the headers and footers are deleted from each that don't need them.
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 Action - View Event. 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.
IMPORTANT: If anyone will be using FileMaker 17+ to access the calendar, you need to import the scripts using FileMaker 17+. Using an older version of FileMaker to import the scripts will result in a non-functional calendar when opened in FileMaker 17+.
Import the scripts from DayBack. If you are using FileMaker Pro Advanced, you can just copy and paste all of the scripts instead of importing. 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 DayBack file for the following step to work.
9. Layouts Part 2.
Now copy the layout contents from each layout in DayBack and paste them into the layout of the same name in your file. You'll be warned that you'll be increasing the height of each layout; that's OK.
While the layout heights in FileMaker 13 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 Action - View Event feel free to edit this layout as you see fit, adding your own fields and buttons. You may choose not to use this layout at all as it's not required. You can come back and edit this layout later, for now, if you do intend to use this layout just make sure the fields properly match 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.
10. Layout Script Triggers.
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.
Layout: Calendar (2 triggers)
Trigger: OnRecordLoad (in Browse Mode)
Script: "Load Calendar Layout"
Trigger: OnViewChange (in Browse Mode)
Script: "Load Calendar Layout"
Layout: Action - View Event (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.
11. Setup.
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.
11.2 Map your data. -> Navigate to the Source No 1 layout in DayBack.fmp12 and follow the instructions on the layout to map the fields there to the relevant fields in your events table.
A few tips on field mapping:
All fields on the Source No layout need to be mapped, and there are six tabs with fields on them. For any fields that don't have a corresponding field in your events table, map DBk_Unused in their place.
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.
Contacts & Projects
If you are using a contacts or projects table you will want to map those too. Navigate to the "Related Source No 1" layout and map your contact fields. Then you can navigate to "Related Source No 2" and map your project fields if necessary.
Once you've mapped these fields you can run the script "Upon Opening" in DayBack.fmp12 and if you haven't made any mistakes you should see your events in the calendar! If you're seeing errors you might skim through the steps above again to see if you missed anything, or checkout our troubleshooting tips. And you can always get in touch if those troubleshooting steps don't work for you: we're here to help.
12. Clean Up.
Import the "CalendarInterface" table record from DayBack into the "CalendarInterface" table in your file. This contains all of the necessary files to run the calendar.
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 "Upon Opening" script if you haven't already and you should see your events on the calendar.
Enjoy!
Next Steps
Now that you've got the calendar showing your own records (congratulations!) 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...
• Color Coding. Click on the filters tab of the calendar and edit the statuses listed there to match the values in the field you mapped to "status" on your Source No 1 layout. This is the field we'll use for color coding. Click on the gear icon beside a status to change it's name or color. Click on the "+" icon to add new ones. Read more about colors here.
• Showing Additional Fields Remember the summary calc (DBk_EventSummaryCalc) you edited when setting up your calendar? You'll want to go back to that field and add in any additional event fields you'd like to see in the calendar. You'll likely want to do the same with the field DBk_WebViewerSource. Tips for configuring both these fields can be found here: adding fields to the calendar.
• Resources. Take a look at the field you mapped to Resource and edit the Resources value list in the calendar so it matches the contents of that field: we used "location" as the resource in our video and changed the "Resources" value list in the calendar to point to an existing value list in the Meetings file. You may want to do something similar. More on resources.
• Filtering the Calendar If you need to set up more filters or point the existing ones at your own fields, then check out our notes on filters.
• General Settings. You'll also want to read through the script "Load Calendar Settings - On Startup --- Edit Configuration Here ---" making changes as necessary: this lets you change a number of the calendar's default settings and is a good read as it lets you know what's already set up for you to change.
• Renaming Sample Events. If you'd like to change the name of "sample events" in the relationships tab, you can do that now, just read about this script you'll need to edit afterwards: renaming tables.
• Linking Contacts & Projects to Events You may have just mapped the DBk_Unused field to the contact and project IDs you encountered during integration. If your events are linked to contacts or projects now is the time to teach the calendar about those relationships.
• Additional Tables (Sources). And don't forget you can show records from additional tables, not just the one your named Sample Events. We call each of these events tables "sources" and any table that has dates in it can be a source. Learn more by reading about multiple sources.
• Event List. If you've linked the calendar with your own file, and don't have your own list view for your events table, you may want to use the "Event List" layout in the calendar file. If so, sure to enter layout mode and repoint the fields and the sorts on the layout's summary parts. More here: Using the Event List Layout.
• The "Action - View Event" Layout One of DayBack's example custom actions takes you to a sample event record in a FileMaker layout called "Action - View Event". If you want to make use of this layout you'll need to repoint it to the fields in your own events table much as you did with the event list.
• To-Do Details and List. If you're using the To-Do list table that came with DayBack there is probably nothing to do here but may want to visit these two To-Do layouts and add or remove fields that don't apply to you.
• Deleting Unused Tables. Finally, if you've linked DayBack file to your file (instead of embedding it) you may want to delete the tables you're not using (like our original SampleEvents table, sample contacts, etc.)
• Displaying the DBk_ColorCalc in linked integrations. If you've linked DayBack, utilizing the DBk_ColorCalc field to display an event's status color on FileMaker layouts outside the calendar requires a few additional steps:
1. Add a "CalendarColors" table occurrence to your data file (wherever your Events table is located) based on the CalendarColors table in your DayBack file.
2. Add a new layout named "Calendar Status Colors" in your data file based on this CalendarColors table occurrence.
3. Copy the script "Load Calendar Color Coding" from DayBack and paste it in your data file.
4. At the bottom of the "Load Calendar Settings - On Startup" script, add another Perform Script step which calls the new "Load Calendar Color Coding" script from your data file.
• Getting Ready for PSOS. If you've using FileMaker Server, check that your file's start up script bails out when run on FileMaker Server. Each Perform Script on Server (PSOS) script initiated runs the start up script in any required files and that can really slow things down. Feel free to use the same routine used as the first lines of DayBack's "Upon Opening" script:
If [PatternCount ( Get ( ApplicationVersion ) ; "Server" )]
Exit Script []
End If
