Update docs: Adding Custom Fields to the Registration Page

source/site_ops/install_configure_run_guide/configuration/customize_registration_page.rst

@@ -1,78 +1,213 @@
 .. _Customize Registration Page:
 
-#############################################
+##############################################
 Adding Custom Fields to the Registration Page
-#############################################
+##############################################
 
-.. tags:: site operator
+.. tags:: site operator, how-to
 
 This topic describes how to add custom fields to the registration page for your
-instance of Open edX.
+Open edX instance.
 
 .. contents::
    :local:
    :depth: 1
 
-*********
-Overview
-*********
+*************
+Introduction
+*************
 
-By default, the registration page for each instance of Open edX has fields that
-ask for information such as a user's name, country, and highest level of
-education completed. You can add custom fields to the registration page for
-your own Open edX instance. These fields can be different types, including
-text entry fields and drop-down lists.
+This guide explains how to add custom fields to the registration page of your
+Open edX instance. To integrate custom fields with the new Authn MFE, additional
+configuration steps are required. Custom fields can be either required — added
+directly to the registration page — or optional, and will be added to the
+progressive profiling page (welcome page) that users can skip.
 
-*********************************************
-Add Custom Fields to the Registration Page
-*********************************************
+**********************************
+Two Main Ways to Add Custom Fields
+**********************************
 
-Before you add a custom field to the registration page, you must make sure that
-the combined sign-in and registration form is enabled for your Open edX
-instance. To do this, open the ``lms.yml`` and ``studio.yml`` files, and
-set the ``ENABLE_COMBINED_LOGIN_REGISTRATION`` feature flag to True. These
-files are located one level above the ``edx- platform`` directory.
+The Open edX platform has default additional fields that can be used in the Authn
+MFE. The fields that are in `EXTRA_FIELDS
+<https://github.com/openedx/edx-platform/blob/a9355852edede9662762847e0d168663083fc816/openedx/core/djangoapps/user_authn/api/helper.py#L20-L39>`_
+already exist as columns in the user profile model, but are disabled, so
+when adding other fields that do not exist, a step to do data migration is
+required.
 
-To add custom fields to the registration page, follow these steps.
+To add fields that already exist in the user model, it is sufficient to redefine
+several constants. How to do this will be described in :ref:`Add Existing Reg Fields`. If
+you need to add fields that are not in the user model by default, see :ref:`Add New Reg Fields`.
 
-#. Start and sign in to your instance of Open edX.
+.. _Add Existing Reg Fields:
 
-#. Use Python to create a Django form that contains the fields that you want to
-   add to the page, and then create a Django model to store the information
-   from the form.
+Add Fields that Already Exist as Columns in the User Profile Model
+======================================================================
 
-   For more information about how to create Django forms, see `Django Forms`_
-   on the `Django website`_.
+You need to redefine several constants in the settings. You can use various
+methods for this:
 
-#. In the ``lms.yml`` file, add the app for your model to the
-   ``ADDL_INSTALLED_APPS`` array.
+.. _Reg Fields Site Configuration:
 
-#. In the ``lms.yml`` file, set the ``REGISTRATION_EXTENSION_FORM``
-   setting to the path of the Django form that you just created, as a dot-
-   separated Python string.
+Redefine constants using Django admin and ``Site configurations`` API. (recommended)
+----------------------------------------------------------------------------------------------
 
-   For example, if your form is named "ExampleExtensionForm" and is located at
-   "path/to/the_form.py", the value of the setting is
-   ``path.to.the_form.ExampleExtensionForm``.
+#. Go to ``Site configurations`` in admin:
+   {{LMS}}/admin/site_configuration/siteconfiguration/
 
-#. Run database migrations.
+#. Add new settings to OrderedDict (create new ``Site configurations`` if it was
+   not before):
 
-#. Restart the LMS and verify that the new fields appear on your registration
-   form.
+   .. code-block:: json
 
-.. note::
+      {
+         "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true", "MFE_CONFIG": {
+         "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true" },
 
-  For an example app for custom forms, see the OpenCraft `custom_form_app`_
-  page in `GitHub`_.
+         "REGISTRATION_EXTRA_FIELDS": { "country": "required", "gender":
+         "optional"
 
+         }
+      }
 
-.. include:: /links.txt
 
+#. All possible fields can be found in `EXTRA_FIELDS
+   <https://github.com/openedx/edx-platform/blob/a9355852edede9662762847e0d168663083fc816/openedx/core/djangoapps/user_authn/api/helper.py#L20-L39>`_.
+
+#. REST API gets cached. If you are in a hurry, you can do this command: ``tutor
+   local exec redis redis-cli flushall``. Also, you can wait a few minutes until
+   the cache is invalidated.
+
+#. The new fields should appear on the Auth page. Required fields will appear on
+   the registration form, and optional fields will appear on the progressive
+   profiling form.
+
+Redefine Settings Above by Using the Tutor Plugin
+------------------------------------------------------------
+
+#. There is a tutorial `how Tutor plugin can be created
+   <https://docs.tutor.edly.io/tutorials/plugin.html#creating-a-tutor-plugin>`_.
+
+#. Settings above should be overridden in the Tutor plugin.
+
+
+Local Development or Testing
+----------------------------
+
+For local development or testing settings, you can override in configuration files:
+
+Constants should be added in ``env/apps/openedx/settings/lms/development.py``:
+
+.. code-block:: python
+
+      ENABLE_DYNAMIC_REGISTRATION_FIELDS = "true"
+
+      MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = "true"
+
+      REGISTRATION_EXTRA_FIELDS["country"] = "required"
+
+      REGISTRATION_EXTRA_FIELDS["gender"] = "required"
+
+In total, you must redefine 3 constants using the method that is most preferable for you:
+
+.. code-block:: python
+
+      ENABLE_DYNAMIC_REGISTRATION_FIELD = True,
+
+      MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True,
+
+      REGISTRATION_EXTRA_FIELDS["field_name"] = "required/optionl/hidden"
+
+.. _Add New Reg Fields:
+
+Add Fields that Do Not Exist in the User Profile Model
+==========================================================
+
+Everything said above in :ref:`Add Existing Reg Fields` also applies to adding
+fields that do not exist in the user profile model. This is a more complex task
+and requires a basic understanding of the Open edX platform, the concept of
+plugins, as well as knowledge of the Django framework. However, there are
+additional actions that you need  to perform:
+
+#. Extend user profile model with new fields. An external plugin should be used for
+   this. **New fields must be migrated to the database.**
+
+#. Create a form with additional user profile fields and pass the path to this
+   form into ``settings``. The form can also be created in the Open edX plugin.
+   `Edx-cookiecutters <https://github.com/openedx/edx-cookiecutters>`_ can be
+   used for the plugin creation.
+
+#. Additional settings can be passed via ``Site configurations`` in the LMS
+   admin. This is described in :ref:`Reg Fields Site Configuration`.
+
+   Example:
+
+   .. code-block:: json
+
+      {
+         "REGISTRATION_EXTENSION_FORM":
+         "you_application.form.ExtendedUserProfileForm",
+
+         "extended_profile_fields": [
+               "your_new_field_id", "subscribe_to_emails",
+               "confirm_age_consent", "something_else"
+         ]
+      }
+
+#. Finally, you must migrate to DB new user profile fields and redefine 3
+   constants using the method that is most preferable for you:
+
+   .. code-block:: python
+
+        ENABLE_DYNAMIC_REGISTRATION_FIELD = True,
+
+        MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True,
+
+        REGISTRATION_EXTENSION_FORM =
+        "you_application.form.ExtendedUserProfileForm"
+
+*******************************************************
+Configuring Custom Registration Fields on the Back-End
+*******************************************************
+
+To configure dynamic registration fields within Authn, perform the following
+steps in the Open edX LMS settings or your custom form plugin:
+
+#. Install your custom form app and configure it in LMS. Follow the steps
+   outlined in the official Open edX documentation to configure custom
+   registration fields for your instance: `Customize the Registration Page <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/customize_registration_page.html>`_.
+
+#. Enable dynamic registration fields setting in the Open edX platform. Enable
+   the ``ENABLE_DYNAMIC_REGISTRATION_FIELDS`` setting in the settings file. This
+   setting should be added to the plugin where the extension form is placed.
+
+   .. note:: See the context view for the Logistration page: `user_authn API Context View <https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/user_authn/api/views.py#L61>`_.
+
+#. Add fields to the extended profile fields list. Add your `custom field
+   <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/retrieve_extended_profile_metadata.html>`_
+   to the ``extended_profile_fields`` list to ensure it is checked correctly
+   during registration.
+
+   .. warning:: If this step is missed, fields from the extension form will not be saved. For more information, please see the condition in: `helper.py <https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/user_authn/api/helper.py#L97>`_.
+
+#. After adding all required settings, verify that the context has been properly
+   extended with the new fields by inspecting the networks tab in your browser's
+   developer tools.
+
+************************************************
+Configuring Dynamic Registration Fields in Authn
+************************************************
+
+Enable dynamic fields in the MFE. Ensure that
+``ENABLE_DYNAMIC_REGISTRATION_FIELDS`` is enabled for the MFE. This can be
+configured via env tokens or through site configurations if MFE CONFIG API is
+enabled.
+
+.. include:: /links.txt
 
 **Maintenance chart**
 
 +--------------+-------------------------------+----------------+--------------------------------+
 | Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
 +--------------+-------------------------------+----------------+--------------------------------+
-|              |                               |                |                                |
+| 15/04/2026   |  edunext                      |   Ulmo         |  Pass                          |
 +--------------+-------------------------------+----------------+--------------------------------+