Skip to content

Commit 462e2eb

Browse files
ApgomeznextApgomeznext
committed
Update docs: Adding Custom Fields to the Registration Page
PR: openedx/frontend-app-authn#1595 Restore "Adding Custom Fields to Registration" How-To Guide Context This PR restores the documentation guide for adding custom fields to the registration page in the Authn MFE. This guide was previously removed from the repository, but there is no clear trace of when or why it was deleted from the codebase. The original file is: https://github.com/openedx/frontend-app-authn/blob/63d16364fc2aa6538dd876bd3f6fd5612a20d605/docs/how_tos/adding_custom_fields_to_the_registration.rst#b-add-fields-that-do-not-exist-in-the-user-profile-model Problem The documentation for extending registration fields is currently missing from the repository, making it difficult for operators to: Understand how to add custom fields to the registration page Configure REGISTRATION_EXTRA_FIELDS properly Extend the UserProfile model with custom fields Integrate custom forms with the Authn MFE This documentation is essential for organizations that need to collect additional user information during registration beyond the standard fields (email, username, password, name). Documentation Location The restored documentation is located at: docs/how_tos/adding_custom_fields_to_the_registration.rst Key Topics Covered Introduction to custom registration fields Difference between required and optional fields Step-by-step configuration for existing fields Advanced guide for custom UserProfile field extensions Backend and frontend integration requirements Configuration examples for different deployment methods Testing I followed up the instructions and everything is working as expected
1 parent fbca9ec commit 462e2eb

1 file changed

Lines changed: 106 additions & 42 deletions

File tree

‎source/site_ops/install_configure_run_guide/configuration/customize_registration_page.rst‎

Lines changed: 106 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _Customize Registration Page:
22

3-
#############################################
4-
Adding Custom Fields to the Registration Page
5-
#############################################
3+
#######################################################
4+
Adding Custom Fields to the Registration Page in Authn
5+
#######################################################
66

77
.. tags:: site operator
88

@@ -13,66 +13,130 @@ instance of Open edX.
1313
:local:
1414
:depth: 1
1515

16-
*********
17-
Overview
18-
*********
16+
*************
17+
Introduction
18+
*************
1919

20-
By default, the registration page for each instance of Open edX has fields that
21-
ask for information such as a user's name, country, and highest level of
22-
education completed. You can add custom fields to the registration page for
23-
your own Open edX instance. These fields can be different types, including
24-
text entry fields and drop-down lists.
20+
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.
2521

26-
*********************************************
27-
Add Custom Fields to the Registration Page
28-
*********************************************
22+
**********************************
23+
Two Main Ways to Add Custom Fields
24+
**********************************
2925

30-
Before you add a custom field to the registration page, you must make sure that
31-
the combined sign-in and registration form is enabled for your Open edX
32-
instance. To do this, open the ``lms.yml`` and ``studio.yml`` files, and
33-
set the ``ENABLE_COMBINED_LOGIN_REGISTRATION`` feature flag to True. These
34-
files are located one level above the ``edx- platform`` directory.
26+
The Open edX platform has default additional fields that can be used in 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>`_ are 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.
3527

36-
To add custom fields to the registration page, follow these steps.
28+
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 instructions **A**. If you need to add fields that are not in the user model by default, use instruction **B**.
3729

38-
#. Start and sign in to your instance of Open edX.
30+
A. Add Fields that Already Exist as Columns in the User Profile Model
31+
======================================================================
32+
You need to redefine several constants in the settings. You can use various methods for this:
3933

40-
#. Use Python to create a Django form that contains the fields that you want to
41-
add to the page, and then create a Django model to store the information
42-
from the form.
34+
Method 1: Redefine constants using Django admin and `Site configurations` API. (recommended)
35+
---------------------------------------------------------------------------------------------
36+
#. Go to `Site configurations` in admin: {{LMS}}/admin/site_configuration/siteconfiguration/
37+
#. Add new settings to OrderedDict (create new `Site configurations` if it was not before)
38+
.. code-block:: json
4339
44-
For more information about how to create Django forms, see `Django Forms`_
45-
on the `Django website`_.
40+
{
41+
"ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true",
42+
"MFE_CONFIG": {
43+
"ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true"
44+
},
45+
"REGISTRATION_EXTRA_FIELDS": {
46+
"country": "required",
47+
"gender": "optional"
48+
}
49+
}
4650
47-
#. In the ``lms.yml`` file, add the app for your model to the
48-
``ADDL_INSTALLED_APPS`` array.
51+
#. 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>`_.
52+
#. 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.
53+
#. 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.
4954

50-
#. In the ``lms.yml`` file, set the ``REGISTRATION_EXTENSION_FORM``
51-
setting to the path of the Django form that you just created, as a dot-
52-
separated Python string.
55+
Method 2: Redefine Settings Above by Using the Tutor Plugin
56+
------------------------------------------------------------
57+
#. There is a tutorial `how Tutor plugin can be created <https://docs.tutor.edly.io/tutorials/plugin.html#creating-a-tutor-plugin>`_.
58+
#. Settings above should be overridden in the Tutor plugin.
5359

54-
For example, if your form is named "ExampleExtensionForm" and is located at
55-
"path/to/the_form.py", the value of the setting is
56-
``path.to.the_form.ExampleExtensionForm``.
60+
Method 3: For the Local Development or Testing Settings, It Can Be Overridden in Configuration Files
61+
-----------------------------------------------------------------------------------------------------
62+
#. Constants can be added here: `env/apps/openedx/settings/lms/development.py`:
63+
.. code-block:: python
5764
58-
#. Run database migrations.
65+
ENABLE_DYNAMIC_REGISTRATION_FIELDS = "true"
5966
60-
#. Restart the LMS and verify that the new fields appear on your registration
61-
form.
67+
MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = "true"
6268
63-
.. note::
69+
REGISTRATION_EXTRA_FIELDS["country"] = "required"
6470
65-
For an example app for custom forms, see the OpenCraft `custom_form_app`_
66-
page in `GitHub`_.
71+
REGISTRATION_EXTRA_FIELDS["gender"] = "required"
6772
73+
In total, you must redefine 3 constants using the method that is most preferable for you:
74+
75+
.. code-block:: python
76+
77+
ENABLE_DYNAMIC_REGISTRATION_FIELD = True,
78+
79+
MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True,
80+
81+
REGISTRATION_EXTRA_FIELDS["field_name"] = "required/optionl/hidden"
82+
83+
B. Add Fields that Do Not Exist in the User Profile Model
84+
==========================================================
85+
Everything said above in instructions **A** 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:
86+
#. Extend user profile model with new fields. An external plugin can be used for this (recommended). Also user profile model can be expanded inside edx-platform code base (not recommended). `New fields must be migrated to the database.`
87+
#. 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.
88+
#. Additional settings can be passed via `Site configurations` in the LMS admin. This is described in instructions **A**.
89+
Example:
90+
91+
.. code-block:: json
92+
93+
{
94+
"REGISTRATION_EXTENSION_FORM": "you_application.form.ExtendedUserProfileForm",
95+
96+
"extended_profile_fields": [
97+
"your_new_field_id",
98+
"subscribe_to_emails",
99+
"confirm_age_consent",
100+
"something_else"
101+
]
102+
}
103+
104+
#. In total, you must migrate to DB new user profile fields and redefine 3 constants using the method that is most preferable for you:
105+
.. code-block:: python
106+
107+
ENABLE_DYNAMIC_REGISTRATION_FIELD = True,
108+
109+
MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True,
110+
111+
REGISTRATION_EXTENSION_FORM = "you_application.form.ExtendedUserProfileForm"
112+
113+
.. note:: Below, you can read in detail how to create a new Application and Form, what happens when you redefine each constant, and how they can be redefined.
114+
115+
116+
Configuring Custom Registration Fields on the Back-End
117+
*******************************************************
118+
To configure dynamic registration fields within Authn, perform the following steps in Open edX LMS settings or your custom form plugin:
119+
120+
#. 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:
121+
`Customize the Registration Page <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/customize_registration_page.html>`_.
122+
#. 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.
123+
124+
.. 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>`_.
125+
126+
#. 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.
127+
.. 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>`_.
128+
#. 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.
129+
130+
Configuring Dynamic Registration Fields in Authn
131+
************************************************
132+
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.
68133

69-
.. include:: /links.txt
70134

71135

72136
**Maintenance chart**
73137

74138
+--------------+-------------------------------+----------------+--------------------------------+
75139
| Review Date | Working Group Reviewer | Release |Test situation |
76140
+--------------+-------------------------------+----------------+--------------------------------+
77-
| | | | |
141+
| 15/04/2026 | edunext | Ulmo | Pass |
78142
+--------------+-------------------------------+----------------+--------------------------------+

0 commit comments

Comments
 (0)