By now you’ve all heard the earth-shaking news: the merger between the Proof Group and Geist Interactive. The new company, Proof+Geist (the ‘+’ is silent, by the way), brings together the best of The Proof Group and Geist Interactive. All that you know about those separate entities are now as one. Now led by Ernest Koe as CEO, Steve Ritchie as CFO, and Todd Geist as CTO, this new team of 20+ people is ready to use our technologies, products, knowledge, and skills to provide unparalleled service to our current clients, our future clients, and the Claris FileMaker community. 

This merger seems inevitable.

Todd and Ernest have a long and strong friendship. Todd has been in FileMaker forever, and he describes Ernest as “Someone who has always been there.” They talk often and are two people that push the platform further. As Ernest says of his team: “In the last three years or so, Proof has expanded in consulting and custom application development.

But our background is in using FileMaker as a vertical market solution platform; and that has pushed us to develop a practice around enterprise-class, modular FileMaker development where we have tried to favor performance, and configuration over customization. These are the same underlying philosophies you see in the products, tools and approaches for Todd’s team. ” So bringing together The Proof Group and Geist Interactive, two companies that have a lot more in common than they have differences, is quite a step forward. 

The mission of Proof+Geist is two-fold.

We want to bring a people-centric approach to the design, and development of custom applications and solutions for business, and we want to create the best products and resources for the Claris FileMaker community. Let’s look at each one of these and see Proof+Geist’s philosophy and approach.

People-Centric Approach

It seems obvious, but at Proof+Geist we see people as the greatest resource. Those human beings include those who create custom apps, write content, pay bills, etc. and those folks who have business problems that need to be solved. 

Our company has a supportive environment: we’re one team. We are all here for a common purpose (described above), which is embedded into each one of us. We work together, sharing ideas, questions, struggles, and resolutions to common issues found in all businesses. I’ll tell you, in my few weeks so far of working with a team of people to create this announcement content, I’m finding myself happy that the best ideas and the best words come forth. The team makes things better.

For our clients–current and future–we use empathy to ask the right questions and get to the root of the business problems faster. We put our heads together to find the best solution for the problem, no matter the technology or the technique. 

In future blog posts, we’ll describe our people-centric approach in more detail.

Innovative Resources

The merging of the Proof Group and Geist Interactive expands our product line. The FMPerception Suite, Otto, Proof+Hosting, LedgerLink, Generator and much more come together in the same store for the Claris FileMaker community. More people on the team means more support and more innovation of new products and tools. We’re excited to see what comes from this combined team.

High-Quality Education

Proof+Geist is an unmatched gathering of knowledge and resources for the Claris Community. We have over 100 years of combined experience in FileMaker development. Our roster includes people who:

Have spoken at conferences and user groups.

Lead or have founded community initiatives such as WITFm, and PauseOnError.

Are MVPs in the Claris Community.

Are educators by training.

Have specialized in concepts and techniques that are beneficial to the Claris FileMaker community.

Work closely with Claris International, providing thoughts and feedback to potential new features.

Our combined team will share their knowledge and expertise even more than in the past. We’ll be active in the various FileMaker communities, share our thoughts on The Context Podcast, and write more blog posts about FileMaker concepts and techniques ( we won’t just write about JavaScript anymore).

Onward

It’s an exciting time. Proof+Geist has arrived and is ready to meet the technology challenges of today and tomorrow. The team looks forward to continuing their shared legacy of designing, building, and orchestrating systems for people who want to do great things. For more information, general inquiries, or to partner with Proof+Geist, please visit www.proofgeist.com or reach out via email to info@proofgeist.com.

And here’s a few ways you can learn even more:

Hello there 🙂

We have some exciting news to share with you. Geist Interactive has merged with the Proof Group to form Proof+Geist (the + is silent). This is an acceleration of our decades-long mission of empowering people to do great things, a mission we have always shared with the people at the Proof Group. Together, as one team, we are very excited for what’s ahead.

Please see the attached press release, and visit us at www.proofgeist.com!

In normal years, when I get to travel around and speak to people about FileMaker, I am always gratified by how many of you in our community ask me about One Spark Academy, the non profit learning center that my wife Lori and I started in 2011. Many of you follow the happenings there, and many of you also give every year to our end-of-year campaign. It is so nice to be a part of such an interested and generous community. 2020 has been an extra challenge as you can imagine, and I am here to ask you again if you can help support our mission.

Donate Now

Rising to the Challenge

It’s not news that families all over the country are struggling.  People have lost jobs or wages.  Parents have to work from home, often while their children are home also trying to keep up with school work.  Everyone has learned to Zoom.

One Spark is doing what we can to help. We have changed just about everything we do while continuing to give our students a solid and engaging curriculum, as evidenced by the pictures here. At the same time, we’re holding or reducing costs where we can, so our students don’t find interruptions in their learning needs.

Of course this comes with a financial burden that we can’t ignore. We still have the same number of employees to pay as before. We still have bills to pay. We still need to make ends meet. This is why we are reaching out to you. Your tax-deductible donation can help us help families and kids who need it.  Please consider giving any amount.

Learning in the Time of COVID

When the pandemic hit and lockdowns became a reality, One Spark Academy moved quickly to become a fully virtual program. It was a challenge, but part of the mission of One Spark is to stay focused on the students and adapt to their needs.  So even though nobody knew what an online middle school program should be like in the middle of a pandemic, the teachers, students and families quickly figured out how to bring the unique philosophy and focus from a site-based academy to a Zoom room.

Bread Camp

How do you move a cooking class online? Well, the teachers who normally cooked with our students in the kitchen decided to deliver all the ingredients to the students’ houses, safely left on the door step, and then met their students on Zoom.  Bread Club was a summer take on our cooking class, which continued into Fall, and it was a big hit. Meanwhile, our regular cooking class (“Food Fascination”) teamed up with local restaurants, whose chefs offered our students mini-lessons on signature dishes and a chance to recreate them at home.

The Great Outdoors

Once it became clear that outdoors with social distancing and masks was a safe way to learn, we moved some classes outdoors.  We even built an outdoor classroom in our local community garden, where the “Seeds and Sprouts” class met.  Geology was another class that moved easily outdoors. We rounded that out with Fitness Club at the local park, and Hiking Club on the trails. Having outdoor time together improved our students’ mental health, which made online learning better.

Solid Core

While One Spark spent extra care on helping students with their social and emotional well being, we didn’t drop the core educational opportunities.  We still offered a full slate of core curriculum.  Everything from math, English, world geography and history, to specialized science and computer engineering classes are still being offered.

Generosity Matters

This is a challenging time for everyone. But some of us are still doing okay, and may even have a little extra to give.  If you are one of those folks and are looking for some way to help, please consider helping us to better help our families this year.  Your generosity will make a difference.

Happy Holidays,

Todd

It’s been a few weeks since the Claris FileMaker add-ons were put into the product. A lot has happened since then. People have explored them using the sample data and even their own. The community is now filled with questions about these new packages of functionality. People are discovering what can be done with them. They’re also discovering little things of which to be aware. So this post is a compilation of what folks have learned about the FileMaker add-ons. I present them in no order. Just find the heading that’s of interest to you and read details about that particular nuance.

Scripts

There are a few more scripts that I’ve not mentioned previously. Here’s a description a few more of them.

The Schema Script

There’s a script inside the “Event Handlers” folder that checks your file’s schema for layouts and fields on one specific layout (the one you choose in the configurator). As with other scripts, you don’t need to do much with this. Additionally you really don’t have to even modify it. I wouldn’t give this script a second thought. But if you do need to know, here are some short details:

  • Do not change the name of the script.
  • The script is called by the web viewer’s JavaScript code as you open the configurator. For each dropdown on that screen, this script provides the choices: first the layouts in your file, and then the fields on the individual layout you choose.
  • It gathers a lot of info about your file: layouts, scripts, value lists.
  • It requires a ‘best-practice’ file name. See that section below.
  • The script reads from the config for the instance of the add-on with which you’re working, and it uses values in the config as the starting point for the configurator. If you’ve already chosen a field for the primary key, for example, that field name is extracted from the config (in the ConfigStore field) and displayed in the configurator.
  • Once you’ve selected a layout, this script runs again to pull the fields on that layout. So each time you change the layout in the dropdown, the field list is regenerated (per type of field).
  • It uses FileMaker 19’s Execute FileMaker Data API script step, specifically using the metadata query.
  • All the fields on the layout are separated into field type arrays.

That’s really all you need to know about this. There’s no instance I can conjure that requires you to manipulate this script in some way.

Get WebViewer Object Name Script

This utility script simply gets the name of the web viewer object in which a script is working. It receives the AddonUUID from the parent script and adds the prefix to it, sending it back to the parent script.

There’s nothing to concern yourself here. It just does its thing and moves on.

Save Config Script

As with the other two scripts, this one is pretty untouchable. Its sole purpose is to receive the configuration from the JS when you press “Save” on that screen and store it in the ConfigStore field.

I mean if you really wanted to, you could override the Config choices made in the configurator. Since JSON is coming from the configurator, you could update a key before it gets stored in the field. Heck you might even be able to ignore the configurator all together and instead use this script to update what’s stored in the field.

Little Quirks

Pause / Resume Script Step

The pause/resume scripts inside the add-ons scripts can cause a problem for certain users. Claris has identified the problem here, and suggests the work-around. Hopefully this will be fixed in a future update of the product and the add-ons for newly-installed add-ons. But you can fix it now.

The problem is that the Pause /Resume script step was set with 0.5 as the pause interval. That doesn’t work for some users, as they’re running FileMaker Pro on a machine with a system language that doesn’t match the region. You can easily fix this by changing the 0.5 to 1/2. And that is what you’ll have to do if you’re currently using an add-on.

The scripts that contain this step are few. Using FMPerception, I am able to find them:

They are, in case you can’t see the image, ShowConfig (line 25) and SaveConfig (lines 54 and 69).

Layout Zooming

There was one question in the community about how the web viewer reacts to layout zooming. The poster typically zoomed layouts to 150%. The web viewer on that layout followed the zoom, which sort of unsharpened the add-on.

Unfortunately that’s how it is. There’s no way to counteract the layout zoom with a web viewer zoom. I’m not sure that’s even possible. It’s likely the layout zoom overrides the web viewer zoom.

So consider that as you design layouts.

Customization

Many folks have asked about customizing a FileMaker add-on further than what is offered in the configurator. Since the add-on is built to be a complete package, the JavaScript code that runs it is packaged up into the HTML field inside the add-on’s table. It’s pretty impossible to get in there and modify something like the color or the width of a particular item.

When we built the add-ons, we worked with Claris to decide what to expose in the configurator. The goal was not to overwhelm a developer with every possible choice; building a configurator with nearly as many choices as the current inspector is tough, and just gives too many choices. So we made decisions on what would be customizable. Generally basic color/theme choices are available, as well as a lot of options in the specific add-on itself.

If any developer wishes more customization, she’s free to build an add-on that suits her needs. We can help with that, for sure, building an add-on that is defined exactly how it works for an app.

We’d love to see some sort of actual add-on inspector incorporated into the current layout mode that gives more choices. I don’t know how that would work, but it is an interesting dream.

Naming Things

Layout Names

After the add-ons were released, I started seeing a few bugs reported about a particular layout not showing up in the configurator’s inspector. After some poking around, I found that layout names with quotation marks in them would cause the the entire layout drop-down to fail. The Schema script (described above) collects the layouts in the file as an array. We know that each string element in an array is quoted, so if a layout name has a quotation mark in it, the array cannot be generated properly. Single quotes might work (not tested), but generally, I’d say, stick to naming layouts without quotation marks in the name.

File Names

Like layout names, File Names are important. Developers have found that the configurator fails to render when the file contains a dot in it: File.Name.fmp12, for example. I think it’s agreed that dots are bad for names; they’re used to designate a file path, not a file name.

Script Names

Be careful with the script names as well. Don’t change the names of scripts where that warning is written at the top. These scripts are called from the JavaScript. The JS has each script name hardcoded into it, and the JS Function looks for the script by name (not by script ID) when it goes to call the script.

Licensing

All of the add-on were built using free MIT-licensed JavaScript libraries. You can use them for commercial apps, for many apps, and for many customers.

Onward

There’s probably more that we’ll discover about add-ons in the coming months, and in the coming months, the entire structure of the add-ons might change. We’ll keep you updated on the latest bugs, discoveries, and changes to the FileMaker add-ons.

In Part 2 of All that we Know on Add-ons (part 1 is here), we talked about how to create add-ons that include a simple child relationship. The sole purpose of that add-on was to add a child table and have it automatically relate to the context of the layout in which we drop the UI elements. This simple relationship might prove useful in many cases: add a notes or addresses table easily. But for complex relationships, we need to create filemaker add-ons with join relationships.

To keep our heads straight, pictures and a real-world scenario (or at least a common join-table use case) will help us understand this. We’ll use a Schedule table that shows all the classes in which each student is enrolled.

Considerations

Here’s a small list of considerations about FileMaker add-ons with join relationships

  1. Just like in our discussion about add-ons with relationships (part 2), we’re creating this add-on from the related table context. That means, in this case, we’ll be creating it from the join table perspective. The base table of the add-on layout is “Schedule”.
  2. Each table has their proper keys. The Schedule (or join table) contains a generic foreign key field (as described in part 2), and it contains the foreign key for the far right table (the Classes table). And of course, the tables contain primary key fields. The default fields feature of FileMaker 19 will create the primary key fields for you.
  3. A package is one or more tables (among other FileMaker things). As you install the add-on, the tables inside the package get added to the schema once. Even if you place the add-on many times in your file, each instance will use the exact same table.
  4. An add-on must also include the far right table. In this case, the add-on contains the Classes table. There’s no need to create the relationship between Schedule and Classes. It’ll be automatically created on install.
  5. Adding an add-on to a layout automatically creates the relationships between that layout’s table occurrence and the add-on’s tables, provided you’ve set up the package correctly.
  6. Remember: there’s a difference between ‘installing’ the add-on and dragging it to your layout. The difference is very apparent in these kinds of add-ons.

Our first step is to set up the portal showing the schedule records. Again, since we’re on the context of the schedule, use the “Show Records from Current Table” option of the portal set up.

As we can do with all other portals, we can put any fields from the context or relationship inside the portal. Notice in the image, I have “Classes::ClassName” field in the portal. That’s fine. Yes, it’s an unrelated field since we didn’t create the relationship, but you can still place the field on the layout.

Group this object.

Next, we need to tell the add-on package which fields is the primary key and which fields are the foreign key fields. Place those fields on the same layout and name them as follows:

Schedule::ForeignKey: R1|LeftTable This is the field that will be part of the relationship to the context upon which the add-on is dropped.

Schedule::ForeignKey_Classes: R1|JoinTable: The foreign key meant for the relationship to the Right table (in this case, the Classes table).

Classes::PrimaryKey: R1|RightTable. This is the primary key of the Classes table (yes, it’s okay if you put the unrelated field on the table).

NOTE: The name is important in its structure. Each field name needs three pieces:

  • A relationship name: this can be anything as long as it’s the same for all three fields.
  • A “|” (pipe character)
  • and one of three names: “LeftTable”, “RightTable”, “JoinTable”

Now group just the fields together and name the group

__FMAddonDynamicRelation_

and complete the name with the relationship name you used in the field names. My example would be:

__FMAddonDynamicRelation_R1

At the end of the set-up, this is what you have on the add-on creation layout.

At this point, I have a perfectly-set up layout. I can now create an add-on using the same process I’ve described before. Simple. Those two grouped items will be part of the package. Finally, on the install . . . let’s see what happens.

Installing

As we do with other add-ons, we can install this join-relationship add-on. Additionally, the install process adds to the file the package tables, fields, scripts, and layouts. In this case, the Classes and Schedule tables are installed.

Further, when you drag the add-on onto a layout, you only get the grouped objects. The group of fields is NOT part of what you drag on. Instead they’re indicators to FileMaker of the relationships to create.

Here’s what the Manage Database looks like when you install the add-on.

And here’s what it looks like when I drag the add-on onto a Student layout.

After all this is done, we have a join-table relationship installed into the app. The process takes a few moments to set up correctly, but once done, the process adds a lot of good functionality to these add-ons.

We’re continuing our discussion of the new FileMaker 19 add-ons. Claris has released a great video on these add-ons, but, in this series of posts, we’re taking a deep dive into how the add-ons work. In this post we look at how to use multiple instances of the FileMaker add-ons.

The Point of the Add-ons

One of the biggest reasons to use an add-on is that it can be used many times throughout your file. Just like a portal or a button bar, the calendar add-on or the photo gallery add-on is flexible enough to use all over.

As a FileMaker developer you don’t have to know how this works; just know that it works. Your use of an add-on multiple times in the file will not disrupt any of the other add-ons. Here’s a silly example.

Two Timers To Track Times

These two timers are separate instances of the same Timer add-on.

They work with two sets of the timer’s required fields. They have their own configurations (one has a blue button/gray background, and the other has a red button/white background).

Each add-on runs independently of each other; indeed, you can kind of see it here (in the button text), the first timer is running and the second timer has stopped.

Each Timer is Unique

The magic behind this idea is that each timer is given a unique Addon UUID when you drag/drop the add-on to a layout. You can see this unique ID in a few places:

  1. The add-on’s FileMaker buttons (such as the configurator button or the back/forward arrows) script parameter
  2. The name of the web viewer object in the Inspector
  3. The web viewer’s calculation

Of course all of these match, and have a specific purpose.

Multiple Instances of FileMaker Add-ons: The Deets

Let’s make sure we have something clear in our heads:

  • When we install the add-on, all the scripting, layouts, etc comes in as a complete package. The scripts come in once.
  • When we drag/drop the add-on onto a layout, we’re creating a new and unique instance of it. The UUID gets generated and attached to the places you see above.
  • If you were to copy an add-on, you’re copying the UUID as well, so there will be two add-on groups with the same UUID. Can’t have that.

Now that we have that clear (if not, go back and read it again), all add-ons of the same type use the same scripts, so the UUID is passed to scripts to let the script know which one to work with in some manner. The “Show Config” script gets the UUID attached to the button and grabs the config from the ConfigStore field using that UUID. Because the web viewer is named with the UUID, the script knows which web viewer on a layout to activate and manipulate.

This idea of the UUID is incredibly important. You don’t want to change it, unless you want to go to the trouble of updating it all over.

The Only Other Thing

I believe the only other thing you really need to know about multiple instances and the UUID is the script containing the words “WebViewer Object Name”. This script generates the web viewer’s name at runtime, and is used in almost every add-on script. Just FYI.

Oh yeah: if you really want to know how the UUID is generated, I explain that in the post on creating add-ons. Check that out.

Go Forth and Multiply

So use add-ons all over the place. Use a timer ten times in your custom app. Build a dashboard using charting add-ons. Create a layout with two Kanban boards that show different tasks. You got it! It’s easy and the add-ons are built with this in mind.

We’re continuing our discussion of the new FileMaker 19 add-ons. Claris has released a great video on these add-ons, but, in this series of posts, we’re taking a deep dive into how the add-ons work. In this post we look at the FileMaker add-on configurator

The add-ons are meant to be working with little effort. Even at the moment of install they work using sample data and some default settings. At install, you see exactly how they work.

Make it Your Own

There’s no one here, however, that wants the sample data settings to be part of the add-on in their app. Some of the settings too may not fit every customer solution. Both of these issues are easily solved with the add-on Configurator.

So let’s take a look at how to configure the add-ons. We’ll look at the configurator generally, and then in a follow-up post, we’ll address specific add-on configuration settings.

Configuration, Generally Speaking

The configurator dialog is a window installed as part of the add-on package. The layout contains only a blank web viewer, and this layout is used as a card window. And finally, every instance of an add-on–whether used multiple times on a layout or multiple times in a file–will use this one configuration layout.

As part of the layout object that you drag over, a button with a gear icon is included. This activates the “Show Configurator” script. This button is set to be invisible on iPhone or if a user is logged in with a non-full access account. The script uses the UUID of the add-on (generated on drag/drop), and opens the configurator.

Once the configurator is open, you’re presented with some mini pages that contain drop downs or text fields or checkboxes to enter your configuration for this particular add-on instance (remember, you can have multiple instances of the same add-on throughout your file).

In many add-ons there are the same pages: Required, Settings (or options), and Filter. The required fields are required, and the add-on will not save until those fields are filled in.

Required & Optional

I’ve discussed already the required fields for each add-on, but I need to point out one more thing: Most add-ons require a layout in the first drop-down.

This choice is vital: you have to select a layout on which contains all the fields you wish to use in the add-on. All the required fields as well as the optional fields you want to use in the display. For example, the Kanban add-on requires some fields and gives you optional fields. Each of these fields need to be on the layout you choose.

The layout you choose should be one you’d like to use to show the record when it is clicked on in the add-on. Here’s a couple of tips when picking a layout:

  1. Be sure and put all the fields on the layout: either visible and part of the design or off to the right of the visible area.
  2. You can use fields from a related context, but you might run into some slow-down of gathering data.
  3. Before you actually set up the add-on, create all the required and any optional fields in the data table.

Settings

Many add-ons give the developer some ways to customize the add-on. It could be as simple as button color. Whatever the settings, each add-on has default settings that you can change.

Filter

We’ve discussed before the filter mechanism. It is part of the configurator, so you can read up on that. There’s not a whole lot more to talk about there.

Scripting

The button that opens the configurator runs a script partially named “Show Configurator”. This button contains the AddonUUID as a parameter. Here’s an example:

JSONSetElement ( ""; 

  ["AddonUUID" ; "701F0F8B-BED4-48D0-948D-B7E5F2D1171B" ; JSONString]

)

As we’ve talked before about add-ons generally, this UUID is generated when you drag the add-on to your layout. Further, this UUID in the parameter is the same as the UUID for the web viewer object. The UUID attached to the button allows for you to use multiple instances of the add-on all through your file or on the same layout. Each button will have the UUID of its web viewer package, thus be tuned only for that instance.

The Config

It’s important to know where this FileMaker add-on configurator gets the options. For each instance of an add-on, the configuration–that is, the field choices and settings–is stored as a JSON object inside the add-on’s table in the ConfigStore field with the add-on’s UUID as the key.

{
   "701F0F8B-BED4-48D0-948D-B7E5F2D1171B":{
      "AdditionalInfoField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "AssignedTo":{
         "required":false,
         "type":"select",
         "value":""
      },
      "CardDraggable":{
         "required":false,
         "type":"checkbox",
         "value":true
      },
      "CardStyle":{
         "required":false,
         "type":"select",
         "value":"Tasks::BackgroundColor"
      },
      "DataSourceLayout":{
         "reScanOnChange":true,
         "required":true,
         "type":"select",
         "value":"Tasks"
      },
      "DescriptionField":{
         "required":false,
         "type":"select",
         "value":"Tasks::Description"
      },
      "FilterField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "LabelField":{
         "required":false,
         "type":"select",
         "value":"Tasks::Label"
      },
      "LaneSortOrder":{
         "value":[
            "To Do",
            "In Progress",
            "Done"
         ]
      },
      "PrimaryKeyField":{
         "required":true,
         "type":"select",
         "value":"Tasks::PrimaryKey"
      },
      "QueryField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "SortField":{
         "required":true,
         "type":"select",
         "value":"Tasks::SortOrder"
      },
      "StatusField":{
         "required":true,
         "type":"select",
         "value":"Tasks::Status"
      },
      "StatusSort":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleStatus"
      },
      "Style":{
         "required":false,
         "type":"select",
         "value":"Red"
      },
      "TitleField":{
         "required":true,
         "type":"select",
         "value":"Tasks::Title"
      }
   },
   "DEV_UUID":{
      "AdditionalInfoField":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::AssignedTo"
      },
      "AssignedTo":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::AssignedTo"
      },
      "CardDraggable":{
         "required":false,
         "type":"checkbox",
         "value":true
      },
      "CardStyle":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::Style"
      },
      "DataSourceLayout":{
         "reScanOnChange":true,
         "required":true,
         "type":"select",
         "value":"KanbanSampleData"
      },
      "DescriptionField":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::Description"
      },
      "FilterField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "LabelField":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::Start Date"
      },
      "LaneSortOrder":{
         "value":[
            "To Do",
            "In Progress",
            "Done"
         ]
      },
      "PrimaryKeyField":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleData::PrimaryKey"
      },
      "QueryField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "SortField":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleData::Sort"
      },
      "StatusField":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleData::Status"
      },
      "StatusSort":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleStatus"
      },
      "Style":{
         "required":false,
         "type":"select",
         "value":"Blue"
      },
      "TitleField":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleData::Name"
      }
   }
}

Notice that in the above Config, I have two properties, one for the add-on with the UUID beginning with “701F0F8B” and is tuned to the settings I want: the Tasks table fields, the Red style, and so forth. The other with the key of “DEV_UUID”, which contains the settings for the default (on-install) set up. If I end up with ten instances of this add-on throughout my file, there will be ten objects here, each identified with the add-on’s UUID.

If you really, really, really, ever, ever, ever want to wipe this field out there’s a Developer-only script called “Clear Config” that will clear this field. If you do that, all of your configs for all your add-ons will be wiped out. So maybe don’t do this??

Using the Configurator

And finally, as each instance of the add-on is used throughout your file, the add-on setup, the custom functions, and the “Show Config” script work together to get the config out of that field and pass it to the JavaScript code, where it is used all over, telling the JS such things as what colors to use, what layout to pop up to display the data, what fields to use. There’s a lot in this config, and it’s best to leave it alone. Other scripts use the config as well, so

If you want: If you’re really interested you can, at any time, hijack this config and overwrite it with something temporarily. It’s just JSON, and you can target and change anything in here. What you change will update the web viewer.

The FileMaker Add-on Configurator

So that’s the skinny on the FileMaker add-on configurator. It’s an important part of the set up, but really only needs to be touched once during development. After that you’re free to move the button off the layout to the side and use it only when necessary. Heck you don’t even need the button. You can use the same parameter in the button set up in a parent script to call the Show Config script. As long as you pass in the Addon UUID as a JSON object, you can call the configurator via a Developer-only script.

We’re continuing our discussion of the new FileMaker 19 add-ons. Claris has released a great video on these add-ons, but, in this series of posts, we’re taking a deep dive into how the add-ons work. In this post we look at the required fields for the FileMaker Add-ons.

Add-ons Required Fields

Each add-on has one or more required fields for it to work. The dashboard-type add-ons (Kanban, Calendar, Activity Timeline, Photo Gallery) all require the Primary key field of the source data records. That’s a given. The Heatmap add-on doesn’t require a primary key field since it will return all the events of a clicked-on date.

But each add-on has other requirements, and you can see the FileMaker add-on required fields in the configurator. But the configurator is in one part of the add-on, and adding fields is elsewhere, so what follows is a list of all the required fields for each in-product add-on. You can use this list to create the fields in your data tables (or just copy from the SampleData table that comes with each add-on).

An Example Configurator

Remember, these fields do need to be on the target layout, whether on or off screen (off the layout to the right), in order for the add-on configurator to get the data you need.

For fun, I’ll list the non-required fields as well, just so you can make them all at once. These fields provide additional functionality if you choose to add them to your data table.

Calendar

Required Fields

  • Primary Key
  • Title: that which you’ll see on the calendar.
  • Start Date
  • End Date
  • Start Time
  • End Time

Non-Required fields

  • Tooltip
  • AllDay – a number field (1 or 0(empty)) representing the full-day indication
  • Editable: a number field (1 or 0/empty) to indicate if the event can be clicked on and edited.
  • EventStyle: a text field describing the color style the event should be. The FCCalendarStyles value list provides the pre-determined choices.

Kanban

Required Fields

  • Primary Key
  • Name or Title: that which you’ll see on the board.
  • Sort: a number field determining the sort of the cards in each lane. Note: this field get constantly updated as users drag/drop to rearrange the cars on the board. But you can do an initial set of the sort.

Non-Required fields

  • Description: a field holding a description of the task. This is one paragraph with no returns in the text.
  • Label: the label will appear on the top-right of each card. You may want to put a priority level or a date field here.
  • Additional Info: the value in this field will be included in the card if there’s data in the field. It just provides more information about the task.
  • Assigned to: pick a field that holds the assignee name.
  • Card Style: a text field describing the color style the event should be. The KanbanSampleStyles value list provides the pre-determined choices.

Activity Timeline

Required Fields

  • Primary Key
  • Start Date: A timestamp or date field.

Non-Required fields

  • Title
  • Description: a field holding a description of the task. This is one paragraph with no returns in the text.
  • Assigned: pick a field that holds the assignee name.
  • Background: a text field describing the color style the event should be. The ActivityTimeline Styles value list provides the pre-determined choices.

Required Fields

  • Primary Key
  • Photo: This field points to either a container field or a base64-encoded field (see the sample data table). If the file with the add-on is hosted, you can use the container field. Local files require the base64-encoded field.
  • Scale Width: A number field given the relative width of the image. You can calculate this from the original width of the photo. See the SampleData table for examples.
  • Scale Height: A number field given the relative height of the image. You can calculate this from the original height of the photo. See the SampleData table for examples.

Calendar Heatmap

Required Fields

  • Start Date: A timestamp or date field.

Barcode Creator

Required Fields

  • Barcode Source: The data you want to turn into a barcode.
  • Image: Where to place the barcode image.


Timer

Required Fields

  • Time Logged: A field where the time from the timer will be placed when a user stops the timer.
  • Total Time: A field which holds the total time.
  • Time last Started: This field will be given a UTC timestamp when the timer starts, which is used to determine the state of the timer: on or off as users navigate to other records.

Text Editor

Required Fields

  • Rich Text HTML: This is the field where the rich text will be placed and read from when the editor loads.

Simple Chart

Required Fields

  • Field One: A number field with a value that will be graphed on the chart.

Non-Required fields

These non-required fields are additional data points you can plot on the chart.

  • Field Two
  • Field Three
  • Field Four

As we have said before (and I’ll probably say one hundred more times), the Claris FileMaker Add-ons just work. In just a few minutes, you can get a fully functional heatmap or activity timeline running with your data (all records or a found set) in your custom apps. In just a few minutes, you can solve a high-value problem for your customer. Add-ons bring more power to the problem solver.

However, there’s a lot of us that want to know how the add-ons work. So let me explain, generally, how they work. We built these add-ons with the following ideas in mind:

  • They provide a complete package of scripts, layouts, custom functions, and objects.
  • They needed to be self-booting. No special setup is needed.
  • They needed to work on all parts of the platform.
  • In some cases, they needed to refresh themselves or refresh by an action.
  • They need to work with your data and with your choice of settings.
  • Many instances of the add-on can be used throughout the file, even multiple instances on the same layout.

Let me explain these ideas. The ones we skip for now will be detailed further in separate posts.

Types of Add-ons

There are two types of add-ons included in the FileMaker 19 update: Dashboard and single record add-ons.

The Dashboard add-ons include Kanban, Activity Timeline, Calendar, Heatmap, and Photo Gallery. I call them “Dashboard” add-ons because of two reasons: They can work with a found set of records from any table in your entire app, and they can be placed anywhere in your file. The context isn’t important; all the scripting and custom functions can gather the data and code necessary for the add-on.

The Single-Record add-ons include Rich Text Editor, Timer, and Barcode Generator. These require the context that provides them the relevant fields. For example, the Timer add-on needs to be on the “Task” layout so that the user can use the add-on to time her work.

Keep these two types in mind as you work through the rest of this.

Complete Package

As we’ll say repeatedly, these add-ons provide a complete package of functionality. That includes all the tables, layouts, scripts, JavaScript code and custom functions. Here’s a breakdown of each of those.

Tables

There are two tables that are part of each of the add-ons: a SampleData table, and an Addon table, a table named after the add-on.

Sample Data

This table holds records that are used when the add-on first is installed. After dragging the add-on to a layout, the widget gets data out of this sample table so you can see immediately what it looks like working. Feel free to delete this table any time during the process.

Addon Table

The Add-on table contains a few important fields, vital to the workings of the add-on. You wouldn’t want to delete this table while the add-on is installed. The fields here are:

HTML: a text field holding the inlined/minified code that runs the add-on. There’s no need to get into this field and examine its contents; the code is practically unreadable.

ConfigStore: This text field holds a JSON object. This Config object contains one object for each unique instance of the add-on you use throughout the file. It determines the layout from which to get the data, the settings, the filter fields, etc. There’s a lot there. When we talk about multiple instances of add-ons, we’ll go more into detail.

Additional Fields: The additional fields that have global storage are there for additional settings. OriginalTable, OriginalLayout, are fields that temporarily store what’s needed for add-on navigation, and the Query field is an example field of how to do a query. Use that field by default for the query. Take a look at that blog post to learn more about how to use this field.

Layouts

Within a Layout Folder with the specific add-on’s name are two layouts. One is the “Configurator” layout, and the other is the Sample Data layout.

The Configurator layout contains only a single web viewer. This layout is opened as a card window. You can rename this since it’s referenced directly in any scripting.

The SampleData layout is used initially as the target layout for gathering data for the add-on. Once you target your own layout, you can delete this layout.

Custom Functions

The two custom functions that come with each add-on are there to build the data URL for the add-on (AddonDataURL) and to collect the configuration of the target widget from the ConfigStore field (AddonConfig). You should not have to do anything with these. Don’t delete them. I would just let them be, but here’s some info about each one:

AddonConfig: This custom function requires the AddonUUID and pulls from the ConfigStore field that config which matches this AddonUUID. As you first install the add-on, the default config (the “Dev_UUID” config) is pulled and used. This config is eventually sent to the add-on code where the individual settings are picked up and used to render the add-on.

AddonDataURL: This custom function builds the add-ons data URL and merging in the initial props of the add-on (found in the web viewer object). This grabs the entire inlined HTML from that field and substitutes in the props.

Again, you probably don’t need to do anything with these. If you want to add props, you can do that in the web viewer object itself.

Scripts

We’ve organized the necessary scripts into “Public” and “Private” folders inside the Add-on named folder. In upcoming posts, we’ll examine many of the scripts. But just know, those in the “Public” folder can be called from buttons or triggers. The scripts in “Private” don’t need to be touched or examined at all. For fun possibly, in a later post I’ll explain the Private folder’s scripts.

Self-Booting

Each of the add-ons was built to be self loading. No action of the user, whether through a button press or moving to a layout, is necessary for the add-on to work. On its own, the web viewer loads the code, grabs the data, and renders it all.

The add-on is loaded through this web-viewer calculation:

The calculation is fairly straightforward. In the variable declaration of the Let() function, the AddonUUID is generated (see the post about multiple instances) and the config is gathered using a custom function. The InitialProps JSON object is constructed with various values, and then finally the DataURL is loaded into the web viewer with those initial props. From there, the JS takes over and renders the add-on.

Every time a user comes to the layout, this calculation runs and the add-on is loaded with the relevant data.

The Meta properties of the initial props, by the way, a lot of the rendering. For Windows or WebDirect, there’s certain rendering logic the code will execute, and the localization of the add-on is controlled by the Language property.

The Entire Platform

These add-ons are in the FileMaker product, and it was vital to get them working in all parts of the platform. They were tested and we made adjustments based on the needs of, say WebDirect. The new JavaScript functionality allowed us to ensure they work on macOS, Windows, WebDirect, and FileMaker Go.

Refreshing

Add-ons need to be able to refresh so that new data or changed data is visible. So we built mechanisms to do that. We’ll get into the weeds about this in an upcoming post, but here’s the summary. Many of the add-ons will refetch data periodically. They’ll do a complete new find of the data and display the new data in the add-on. Additionally, you can trigger a refresh of the data in the add-on. We’ll get to these in another post.

Work with Your Data

This one is obvious: these add-ons need to work with data in the app (from any table, any set of records (all or a found), and this needs to be set up easily. To accomplish these goals, the add-ons are constructed to use your data through the Configurator.

This is the only place you’ll have to do some set up right away after installing. In browse mode, click the gear icon (usually at the top right of the web viewer) and open the configurator. Here you’ll be given various required choices, a choice of filters (if applicable), and some add-on-specific settings.

Each option has some clarifying help text below, but I’ll point out some extra details:

Each add-on requires a layout choice. In most cases, this layout will be the data-source layout–the layout from which the data comes.

The Dashboard add-ons–Kanban, Calendar, photo Gallery, Heatmap, and Activity Timeline–all require a data source layout. The Single-Record addons–Timer, Barcode Generator, and the Rich Text Editor–each require a layout where the add-on is actually placed.

You choose that layout and the rest of the required settings will be fields from that layout. The choices for each field will come from the fields on the layout, and will filter by the type of field required.

Multiple Instances

You can use multiple instances of an add-on throughout a file or even on a layout. Each add-on can be configured differently in color and in source data fields, and they each run independently. Here’s a silly example, but it does demonstrate the point.

We’ll explore this in greater detail in a future post. There’s a bit to unpack here, so we’ll take a look.

Add-ons Just Work

This Claris FileMaker 19 Add-ons just work. They’re built as a complete package that function as they’re intended. So use them. Explore them and place them in apps for your clients. Use their power to solve complex use cases and move on with other things to solve.

With Claris FileMaker 19, there’s a new world of power opened for us in using web viewer widgets inside our applications. We can create and use calendars, tables, lists, date pickers, charts, data trees, data maps, and thousands of other widgets. With Claris FileMaker 19, there’s a whole lot more power given to the problem solver with JavaScript in FileMaker.

The Problem

The most obvious problem with using JavaScript in FileMaker is learning JavaScript. The language, though developed to be a beginner language, has become complex. There’s lots to learn. There’s concepts, techniques, tricks that a web developer spends years learning. A JavaScript developer will spend most of her career learning, refining, and understanding JavaScript.

We don’t have that time. We don’t have time to watch many of the hundreds of videos out there on JS or even the entire courses. What we need is to find that which will help us in our FileMaker work now.

The solution?

JavaScript in FileMaker

This learning path is all about getting a FileMaker developer using JavaScript in FileMaker in as little time as possible. This thought is not crazy at all. In all the work I’ve done over the past five years, I come back to a few JavaScript concepts and techniques over and over again. The language may be big, but the parts of it we need as FileMaker developers are well defined and smaller than the entirety of the language.

Think of it like a Entity Relationship Diagram: FileMaker on the left, and JavaScript on the right. The word “in” is the relationship. We can look at the JS language through the ‘in’ relationship and see only the parts of JS that is useful right away.

The learning path takes us along five well-trod workflows, that which  we do already in FileMaker. They are:

Five workflows: Perform Actions, Manipulate Data, Load Code, Update the Display, Retrieve Data

This path explores the JavaScript techniques and concepts that perform these five workflows. In Manipulating Data, for example, we’ll look at how to reconfigure an array of data from FileMaker for use in a JavaScript library.  In the Performing Actions workflow, we’ll explore how to create functionality in JavaScript and how to call the function from inside the web viewer or from FileMaker.

There is some technical stuff to know, for sure. We’ll need to understand how to style elements in the web viewer or what the window object means. None of this knowledge is beyond any FileMaker developer.

The Path for Everyone

This is the JavaScript learning path that I suggest any FileMaker developer take. As Cris Ippolite mentioned in a Claris Engage panel recently, this path didn’t come from some professional JavaScript developer. It came from someone (me) who first asked what one can do do with the web viewer, sat down to study how to organize JS libraries in FileMaker (and which would be useful in FileMaker). This path was marked through writing about JavaScript and using it and answering questions in the community.

Taking the Path

Very very soon we’ll have a complete set of instruction and practices around these five FileMaker workflows. Any practices we do will involve FileMaker every step of the way: The new JavaScript functionality, the new Execute FileMaker Data API script step, and the web viewer itself. We’ll build sample projects, and I’ll challenge you to construct this in (a copy of) a current app you’re developing. We’ll also review documentation, books, blog posts, and others’ videos on JavaScript so you see the whole world from the safety of the current path.

Here’s the JS Learning Path official page. Check it out and download the file.

Alternatively, you can take the specific JavaScript concepts and techniques and extract from other JS courses what you need to know. Wes Bos is a great web-development teacher (he literally says “I’m here to help you become a really good web developer.”), and I encourage you to review his videos on the specific skills that we have defined in the path. This mode of transport will not be specific to FileMaker, of course, but you can get a lot out of any JavaScript course that will help you in FileMaker.

Onward

Jump on this JavaScript learning path and work with me and hundreds of other FileMaker developers to learn JavaScript in FileMaker. Follow this official Twitter account (@JS-learnjsforfm) and of course, stay tuned to the site for more information and the complete instruction set.

Click here to view a larger version.