diff --git a/source/site_ops/install_configure_run_guide/configuration/customize_registration_page.rst b/source/site_ops/install_configure_run_guide/configuration/customize_registration_page.rst index 89b3dcaa5..00696d5cc 100644 --- a/source/site_ops/install_configure_run_guide/configuration/customize_registration_page.rst +++ b/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 +`_ +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 + `_. + +#. 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 + `_. + +#. 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 `_ 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 `_. + +#. 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 `_. + +#. Add fields to the extended profile fields list. Add your `custom field + `_ + 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 `_. + +#. 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 | +--------------+-------------------------------+----------------+--------------------------------+