Many Ninja Forms extensions that register custom actions require mapping data from the field list to an action setting.
As an example, newsletter integrations need a way to know which field is the email address field to send to the API. The email field in the field list is connected to the newsletter action by a method called mapping.
Here is an newsletter action with a setting for the email address:
The email address setting is setup to support merge tags.
Merge Tag Menu
The merge tag configuration adds a list icon to the top-right corner of the setting’s input element. Clicking on this icon opens the merge tag menu.
From this list, you can select any field currently in the field list.
Selecting a field will add a field specific merge tag to the setting’s value.
Merge Tags and Field Keys
For this example, the email address field has a field-key of email, which uses the merge tag {field:email}.
Using this convention, a merge tag can be manually entered for any field with a known field-key.
Field Keys, not IDs
With Ninja Forms THREE, we are placing a big emphasis on portability in forms and custom code. To make both forms and code more portable, we are introducing the field-key setting. In contrast to field IDs, field keys are form specific and not database specific. This is important because database specific identifiers do not translate between forms or even WordPress installs. Instead, the field-key settings is unique within the context of the form. When a form is exported, the field-key continues to be form specific, even when the exported form is no longer attached to the database.
After years of experience supporting a form plugin, we have found that a form specific identifier, the field-key setting, is the most stable and portable method for identifying fields.
Specifically, when mapping fields in action settings, the use of the field-key allows for form exports to maintain the mapping without heavy conversion or processing.
TL;DR Field Keys, not IDs. Oh, and Merge Tags.