Feature request: New contact buttons on the API 4 autocomplete widget
Overview
For using the APIv4 autocomplete widget, such as for the Existing Contact field, it would be useful to be able to create new contacts, as is possible with the Select2 drop downs, such as for selecting a Contributor on a backend contribution.
Example use-case
- Add the Existing Contact field to a FormBuilder form
- A user can look up a contact to select, but if there are no results/a new one is needed, they can click a New Individual button to add one without being redirected from the original form
Current behaviour
The APIv4 autocomplete widget does not allow for creating new contacts.
Proposed behaviour
The APIv4 autocomplete widget should have feature parity when it comes to creating new contacts on the spot as the Select2 option
Activity
added improvement label
@brienne Sounds like a nice addition. Are you able to develop this functionality? And provide it as a merge request?
added in-triage label
removed in-triage label
added Concept approved triaged labels
As @brienne says, Autocomplete (APIv4 EntityReference) Fields do not currently support adding a new referenced record "on the fly".
In some of Civi's legacy forms with APIv3 EntityRef autocomplete fields, a "Create New" button is included, which typically pops up an abbreviated creation form, and when the pop-up form is submitted, the newly-created record is referenced by the entityref field.
What would be involved in porting this feature to APIv4, using only APIv4/Afform technology?
For each supported entity type:
-
Define a default "quick add" Afform for the entity type/subtype. (The legacy version uses QuickForm-based Profiles.) For contacts, this is a significantly abbreviated version of the normal contact creation form.
-
Include an "Add New" button/option in the autocomplete widget, which when triggered by mouseclick or arrow key + enter key, would launch the "quick add" Afform (in a modal window? below/in place of the autocomplete widget?)
-
Upon successful submission of the "quick add" Afform, the parent Afform needs to be updated -- the autocomplete widget should link to the newly created record.
Additional thoughts
In the past, on-the-fly creation was limited to Contacts and a couple other Entities. When we implement this, why limit ourselves that way? Why not make it available for any entity type referenced by an API4 EntityReference field?
Regarding the "quick add" form:
-
This sometimes is just a single-field form, e.g. for Organizations, we probably just need the Organization Name field. For Tags, just the tag name. So a pop-up form might be overkill. "Add-in-place" might be a better UI. However if we need to start out with just one UI, the pop-up form is the solution that would accomodate a wide range of form sizes.
-
Ideally a custom Afform could be swapped in for the default if desired. (e.g. for Individuals, First Name, Nickname, Last Name and Primary Phone).
-
Would it be a problem to have cascading quick-add forms? E.g. Relationship -> quick-add Individual -> quick-add Current Employer
-
mentioned in issue #4504 (closed)
@noah that's a good summary. Since it's now possible to load an Afform in a pop-up, none of this is too difficult. I was just pondering how to create a mapping between forms and entity types so we indicate one form as the official "quick-add" for a particular type of entity (should it be a property of the form? a type of form? a system setting?) and then I hit upon a ridiculously simple idea that might be perfect: what about a url convention?
civicrm/quick-add/Individualcivicrm/quick-add/Organizationcivicrm/quick-add/Individual/Studentcivicrm/quick-add/Activitycivicrm/quick-add/Activity/Meeting
It's easy to extend, it's easy to scan for and load, and the very nature of system paths automatically enforces the "one and only" rule so we don't have to re-invent a way to enforce one quick-add form per entity type. And the path structure gives us some extra flexibility about sub-types. Also, the nature of Afform is that we can ship system default versions of all these forms, but they can be overridden by the site-builder or the end-user.
-
What if we needed to have different "quick-add" Contact forms for different parent forms on a single Civi instance?
Well, the existing (profile-based) system doesn't support anything like that and no one's complained... actually I'm not quite sure what kind of use-case you're talking about. Can you give an example?
Here's an example: say on our Civi instance,
- In most places with a Contact Autocomplete widget (like the Relationship form, or the Activity form), we're happy just collecting a name for quick-added contacts.
- But we also have a custom field on Participants called "Emergency Contact". It's a contact EntityReference field using the autocomplete widget. When an Individual is added on the fly here, we want to collect name AND phone number.
Maybe not a perfect example; I have other real use cases in mind which just aren't as pithy.
Anyway what if we used your URL convention, but also added a configuration option to the autocomplete widget to override the quick-add-form URL?
-
Well, first we need https://github.com/civicrm/civicrm-core/pull/27647
- A deleted user
added has-pull-request label
mentioned in issue #5661
