Unify careers portal placeholders between apply and profile templates

[anonymoususer72041]

Summary

While working on #675 and #677 I noticed that the careers portal uses different <input-...> placeholders for the same logical candidate fields depending on whether the template is the public apply form or the candidate profile ("My Profile") page. In other words, there are pairs of placeholders that represent the same field and map to the same database column, but use different names in the apply and profile templates.

This issue proposes unifying these placeholders by standardising on the names used in the apply template and migrating the profile templates stored in the database, so that each logical field has a single, consistent placeholder across all careers templates.

Context

The careers portal templates are stored in the database (e.g. in career_portal_template) and rendered via modules/careers/CareersUI.php. There are two main kinds of templates:

• the public "Apply for Position" template, rendered via $template['Content']
• the candidate "My Profile" template, rendered via $content

Both templates expose candidate fields via custom <input-...> placeholders, which CareersUI.php replaces with real HTML <input> elements and then processes on form submission. However, for several fields the apply and profile templates use different placeholder names for what is effectively the same candidate field.

Examples (not exhaustive):

• Primary email:

  • Apply template: <input-email>
  • Profile template: <input-email1>
  • Both map to the candidate’s primary email (email1).

• "Best time to call":

  • Apply template: <input-best-time-to-call>
  • Profile template: <input-bestTimeToCall>
  • Both render to name="bestTimeToCall" / id="bestTimeToCall" and map to the bestTimeToCall column.

• Work phone:

  • Apply template: <input-phone>
  • Profile template: <input-phoneWork>
  • Both map to the same work phone field.

• Mobile phone:

  • Apply template: <input-phone-cell>
  • Profile template: <input-phoneCell>
  • Both map to the same mobile phone field.

• Home phone:

  • Apply template: <input-phone-home>
  • Profile template: <input-phoneHome>
  • Both map to the same home phone field.

In all of these cases, the underlying HTML name/id and database field are the same. Only the template placeholder name differs between apply and profile.

Problem

From a template-author and maintenance perspective this is confusing and fragile:

• Template authors need to know different placeholder names for the same field depending on whether they are editing the apply or profile template, even though the field is logically identical.
• For maintainers, changes to rendering or validation for a given field (for example primary email or "best time to call") must be applied to multiple placeholder names, which increases the risk of inconsistencies or missed updates.
• The placeholder naming reflects historical evolution (internal field names vs. newer, kebab-case apply placeholders) rather than a clear, documented template "API".

Currently the shipped templates work, but the template surface is unnecessarily duplicated for these fields and harder to reason about than it needs to be.

Proposed change

1. Define the apply placeholders as canonical

For each logical field that currently has different placeholders in apply vs. profile templates, define the placeholder used in the apply template as the canonical one. For example:

• Primary email: canonical <input-email> (instead of <input-email1>)
• "Best time to call": canonical <input-best-time-to-call> (instead of <input-bestTimeToCall>)
• Work phone: canonical <input-phone> (instead of <input-phoneWork>)
• Mobile phone: canonical <input-phone-cell> (instead of <input-phoneCell>)
• Home phone: canonical <input-phone-home> (instead of <input-phoneHome>)

The goal is that template authors only need to learn one placeholder per field, and that placeholder is the same regardless of whether they are editing the apply or profile template.

2. Migrate existing profile templates in the database

Provide a database migration that updates existing careers profile templates (career_portal_template.Content for the "My Profile" template and any similar entries) to use the canonical apply placeholders. For example:

• Replace <input-email1> with <input-email>
• Replace <input-bestTimeToCall> with <input-best-time-to-call>
• Replace <input-phoneWork> with <input-phone>
• Replace <input-phoneCell> with <input-phone-cell>
• Replace <input-phoneHome> with <input-phone-home>

This brings the profile templates in line with the apply template naming without changing the underlying HTML name/id attributes or the database fields they map to.

3. Backwards compatibility and upgrade path

Because the careers templates are stored in the database and can be customised, changing placeholder names is a breaking change for installations that run the new code without applying the migration. To keep the upgrade path as smooth as possible:

• The migration should update the default templates and any custom templates that still use the older placeholder names, so that they continue to work once CareersUI.php only supports the canonical placeholders.
• The release notes should clearly call out that the upgrade includes a careers template migration and that running the upgrade/migration step is required when updating to this version.
• If the project prefers an extra safety margin, the code change and migration could still be delivered in one release, but the old placeholders could be kept as fallbacks for one additional release before being fully removed.

Next steps

As a first step, it would be helpful to:

• agree on the list of fields and canonical placeholders (based on the apply template),
• add a migration that updates the profile templates in career_portal_template,
• and then consider a follow-up pull request that updates CareersUI.php accordingly in the same release.

I am happy to help with preparing the migration and the corresponding code changes once there is consensus on the desired canonical placeholder names.