From 03af30e8df93caf926f22eb6c0768a215fe07c8f Mon Sep 17 00:00:00 2001 From: Glib Glugovskiy Date: Sat, 20 Apr 2024 00:19:38 +0300 Subject: [PATCH 1/7] docs: add how-to for extending registration form with dynamic fields --- ...ding_custom_fields_to_the_registration.rst | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/how_tos/adding_custom_fields_to_the_registration.rst diff --git a/docs/how_tos/adding_custom_fields_to_the_registration.rst b/docs/how_tos/adding_custom_fields_to_the_registration.rst new file mode 100644 index 0000000000..19240cb8a1 --- /dev/null +++ b/docs/how_tos/adding_custom_fields_to_the_registration.rst @@ -0,0 +1,41 @@ +====================================================== +Adding Custom Fields to the Registration Page in Authn +====================================================== + +Introduction +------------ +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 a secondary registration page that users can skip. + +Configuring Custom Registration Fields on the Back-End +------------------------------------------------------ +To configure dynamic registration fields within Authn, perform the following steps in 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 Open edX** + + Enable the `ENABLE_DYNAMIC_REGISTRATION_FIELDS` setting in the settings file. This setting should be added in 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 added. 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. + +Following these steps should help you integrate custom fields into the Authn MFE for Open edX. From 3551e95a270a3313f7d7da2348d512466376078b Mon Sep 17 00:00:00 2001 From: KyryloKireiev Date: Tue, 23 Jul 2024 15:10:15 +0300 Subject: [PATCH 2/7] docs: Add more details --- ...ding_custom_fields_to_the_registration.rst | 79 ++++++++++++++++++- 1 file changed, 77 insertions(+), 2 deletions(-) diff --git a/docs/how_tos/adding_custom_fields_to_the_registration.rst b/docs/how_tos/adding_custom_fields_to_the_registration.rst index 19240cb8a1..856410b5fa 100644 --- a/docs/how_tos/adding_custom_fields_to_the_registration.rst +++ b/docs/how_tos/adding_custom_fields_to_the_registration.rst @@ -6,6 +6,81 @@ Introduction ------------ 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 a secondary registration page that users can skip. +Two main ways to add additional fields depending on the type of fields you want +------------ +Open edX platform has default additional fields which can be used in Authn MFE. The fields that are in `EXTRA_FIELDS `_ are already exists as column in user profile model, but are disbaled, so when adding other field that don't exits, a step to do data migration is required. + +In order to add fields that already exist in the user model, it is enough 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, then you need to use instruction **B**. + +**A. Add fields that are already exists as column in user profile model** +----------------- +You need to redefine several constants in the settings. Several methods can be used for this: + +#. **Redefine constants using Django admin and `Site configurations` API. (recommended):** + - Go to `Site configurations` in admin: {{LMS}}/admin/site_configuration/siteconfiguration/ + - Add new settings to OrderedDict (create new `Site configurations` if it wasn't before): + .. code-block:: json + { + "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true", + "MFE_CONFIG": { + "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true" + }, + "REGISTRATION_EXTRA_FIELDS": { + "country": "required", + "gender": "required" + } + } + + - All possible fields can be find in `EXTRA_FIELDS `_. + - REST API gets cached, if you are in hurry though you can do this command: `tutor local exec redis redis-cli flushall`. + - Or you can wait a few minutes until the cache is invalidated. + - After this, the new fields should appear on the Auth page. + +#. **Also it is possible to redefine settings above with using the Tutor plugin:** + - There is tutorial `how Tutor plugin can be created `_. + - Settings above should be overriden in the Tutor plugin. + +#. **For the local development or testing settings can be overriden in configuration files:** + - For example, constants can be added here: `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:` **ENABLE_DYNAMIC_REGISTRATION_FIELD = True, MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True, REGISTRATION_EXTRA_FIELDS["field_name"] = "required/optionl/hidden"**. + + +**B. Add fields that do not exist in the user profile model** +--------------------------- + +Everything said above in instructions “**A**” is also relevant for adding fields that do not exist in the user profile model. This is a more complex task and requires a basic understanding of Open EdX, the concept of plugins, as well as knowledge of the Django framework However, from the additional actions that will need to be performed: + - 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.` + - Create form with additional user profile fields and pass path to this form into `settings`. The form also can be created in the Open edX plugin. `Edx-cookiecutters `_ can be used for the plugin creation. + - Additional setting can be passed via `Site configurations` in LMS admin. This is described in instructions “**A**”. + 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" + ] + } + +`In total, you must migrate to DB new user profile fields and redefine 3 constants using the method that is most preferable for you:` **ENABLE_DYNAMIC_REGISTRATION_FIELD = True, MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True, REGISTRATION_EXTENSION_FORM = "you_application.form.ExtendedUserProfileForm"**. + +**Below you can read in detail how can you create new Application, Form, what happens when you redefine each of the constants and how they can be redefined.** + + Configuring Custom Registration Fields on the Back-End ------------------------------------------------------ To configure dynamic registration fields within Authn, perform the following steps in Open edX LMS settings or your custom form plugin: @@ -24,7 +99,7 @@ To configure dynamic registration fields within Authn, perform the following ste #. **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. + 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 added. For more information, please see the condition in: `helper.py `_. @@ -38,4 +113,4 @@ Configuring Dynamic Registration Fields in Authn 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. -Following these steps should help you integrate custom fields into the Authn MFE for Open edX. +Following these steps should help you integrate custom fields into the Authn MFE for Open edX. \ No newline at end of file From 51e8380a8bf88edabdb311306ff0412cc55077f6 Mon Sep 17 00:00:00 2001 From: Kyrylo Kireiev <90455454+KyryloKireiev@users.noreply.github.com> Date: Fri, 6 Sep 2024 11:01:04 +0300 Subject: [PATCH 3/7] fix: improve introduction description Co-authored-by: Syed Sajjad Hussain Shah <52817156+syedsajjadkazmii@users.noreply.github.com> --- docs/how_tos/adding_custom_fields_to_the_registration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_tos/adding_custom_fields_to_the_registration.rst b/docs/how_tos/adding_custom_fields_to_the_registration.rst index 856410b5fa..a23a7de2c7 100644 --- a/docs/how_tos/adding_custom_fields_to_the_registration.rst +++ b/docs/how_tos/adding_custom_fields_to_the_registration.rst @@ -4,7 +4,7 @@ Adding Custom Fields to the Registration Page in Authn Introduction ------------ -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 a secondary registration page that users can skip. +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. Two main ways to add additional fields depending on the type of fields you want ------------ From e2ea2926665a9d28a425506bc7741d5fb084de20 Mon Sep 17 00:00:00 2001 From: Kyrylo Kireiev <90455454+KyryloKireiev@users.noreply.github.com> Date: Fri, 6 Sep 2024 11:04:01 +0300 Subject: [PATCH 4/7] fix: improve description Co-authored-by: Syed Sajjad Hussain Shah <52817156+syedsajjadkazmii@users.noreply.github.com> --- docs/how_tos/adding_custom_fields_to_the_registration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_tos/adding_custom_fields_to_the_registration.rst b/docs/how_tos/adding_custom_fields_to_the_registration.rst index a23a7de2c7..1c5ba5f36e 100644 --- a/docs/how_tos/adding_custom_fields_to_the_registration.rst +++ b/docs/how_tos/adding_custom_fields_to_the_registration.rst @@ -101,7 +101,7 @@ To configure dynamic registration fields within Authn, perform the following ste 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 added. For more information, please see the condition in: `helper.py `_. + .. 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. From 6d8ceeb0ee6bc65e1c37bb4f708514e172410f3c Mon Sep 17 00:00:00 2001 From: KyryloKireiev Date: Fri, 6 Sep 2024 11:42:52 +0300 Subject: [PATCH 5/7] style: improve code sections styles, improve formatting --- ...ding_custom_fields_to_the_registration.rst | 99 +++++++++++-------- 1 file changed, 58 insertions(+), 41 deletions(-) diff --git a/docs/how_tos/adding_custom_fields_to_the_registration.rst b/docs/how_tos/adding_custom_fields_to_the_registration.rst index 1c5ba5f36e..1ea5a2f805 100644 --- a/docs/how_tos/adding_custom_fields_to_the_registration.rst +++ b/docs/how_tos/adding_custom_fields_to_the_registration.rst @@ -7,76 +7,93 @@ Introduction 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. Two main ways to add additional fields depending on the type of fields you want ------------- +------------------------------------------------------------------------------- Open edX platform has default additional fields which can be used in Authn MFE. The fields that are in `EXTRA_FIELDS `_ are already exists as column in user profile model, but are disbaled, so when adding other field that don't exits, a step to do data migration is required. In order to add fields that already exist in the user model, it is enough 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, then you need to use instruction **B**. **A. Add fields that are already exists as column in user profile model** ------------------ +------------------------------------------------------------------------- You need to redefine several constants in the settings. Several methods can be used for this: #. **Redefine constants using Django admin and `Site configurations` API. (recommended):** - Go to `Site configurations` in admin: {{LMS}}/admin/site_configuration/siteconfiguration/ - Add new settings to OrderedDict (create new `Site configurations` if it wasn't before): + .. code-block:: json - { - "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true", - "MFE_CONFIG": { - "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true" - }, - "REGISTRATION_EXTRA_FIELDS": { - "country": "required", - "gender": "required" + { + "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true", + "MFE_CONFIG": { + "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true" + }, + "REGISTRATION_EXTRA_FIELDS": { + "country": "required", + "gender": "optional" + } } - } - + - All possible fields can be find in `EXTRA_FIELDS `_. - REST API gets cached, if you are in hurry though you can do this command: `tutor local exec redis redis-cli flushall`. - Or you can wait a few minutes until the cache is invalidated. - After this, the new fields should appear on the Auth page. - + - Required fields will appear on the registration form and optional fields will appear on progressive profiling form. + #. **Also it is possible to redefine settings above with using the Tutor plugin:** - There is tutorial `how Tutor plugin can be created `_. - Settings above should be overriden in the Tutor plugin. - + #. **For the local development or testing settings can be overriden in configuration files:** - For example, constants can be added here: `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:` **ENABLE_DYNAMIC_REGISTRATION_FIELD = True, MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True, REGISTRATION_EXTRA_FIELDS["field_name"] = "required/optionl/hidden"**. - - + 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" + + **B. Add fields that do not exist in the user profile model** ---------------------------- +------------------------------------------------------------- Everything said above in instructions “**A**” is also relevant for adding fields that do not exist in the user profile model. This is a more complex task and requires a basic understanding of Open EdX, the concept of plugins, as well as knowledge of the Django framework However, from the additional actions that will need to be performed: - 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.` - Create form with additional user profile fields and pass path to this form into `settings`. The form also can be created in the Open edX plugin. `Edx-cookiecutters `_ can be used for the plugin creation. - Additional setting can be passed via `Site configurations` in LMS admin. This is described in instructions “**A**”. + 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" - ] - } - -`In total, you must migrate to DB new user profile fields and redefine 3 constants using the method that is most preferable for you:` **ENABLE_DYNAMIC_REGISTRATION_FIELD = True, MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True, REGISTRATION_EXTENSION_FORM = "you_application.form.ExtendedUserProfileForm"**. + + .. code-block:: python + { + "REGISTRATION_EXTENSION_FORM" = "you_application.form.ExtendedUserProfileForm", + + "extended_profile_fields": [ + "your_new_field_id", + "subscribe_to_emails", + "confirm_age_consent", + "something_else" + ] + } + +`In total, 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" **Below you can read in detail how can you create new Application, Form, what happens when you redefine each of the constants and how they can be redefined.** From deb4cd508a3978d6d52864b07113ac00f9cd9007 Mon Sep 17 00:00:00 2001 From: KyryloKireiev Date: Fri, 6 Sep 2024 11:58:51 +0300 Subject: [PATCH 6/7] fix: try to make code blocks visible --- ...ding_custom_fields_to_the_registration.rst | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/how_tos/adding_custom_fields_to_the_registration.rst b/docs/how_tos/adding_custom_fields_to_the_registration.rst index 1ea5a2f805..255de6c6f9 100644 --- a/docs/how_tos/adding_custom_fields_to_the_registration.rst +++ b/docs/how_tos/adding_custom_fields_to_the_registration.rst @@ -20,7 +20,7 @@ You need to redefine several constants in the settings. Several methods can be u - Go to `Site configurations` in admin: {{LMS}}/admin/site_configuration/siteconfiguration/ - Add new settings to OrderedDict (create new `Site configurations` if it wasn't before): - .. code-block:: json + .. code-block:: { "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true", "MFE_CONFIG": { @@ -45,7 +45,7 @@ You need to redefine several constants in the settings. Several methods can be u #. **For the local development or testing settings can be overriden in configuration files:** - For example, constants can be added here: `env/apps/openedx/settings/lms/development.py`: - .. code-block:: python + .. code-block:: ENABLE_DYNAMIC_REGISTRATION_FIELDS = "true" MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = "true" @@ -56,7 +56,7 @@ You need to redefine several constants in the settings. Several methods can be u `In total, you must redefine 3 constants using the method that is most preferable for you:` - .. code-block:: python + .. code-block:: ENABLE_DYNAMIC_REGISTRATION_FIELD = True, MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True, @@ -74,21 +74,21 @@ Everything said above in instructions “**A**” is also relevant for adding fi Example: - .. code-block:: python - { - "REGISTRATION_EXTENSION_FORM" = "you_application.form.ExtendedUserProfileForm", - - "extended_profile_fields": [ - "your_new_field_id", - "subscribe_to_emails", - "confirm_age_consent", - "something_else" - ] - } + .. code-block:: + { + "REGISTRATION_EXTENSION_FORM" = "you_application.form.ExtendedUserProfileForm", + + "extended_profile_fields": [ + "your_new_field_id", + "subscribe_to_emails", + "confirm_age_consent", + "something_else" + ] + } `In total, 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 + .. code-block:: ENABLE_DYNAMIC_REGISTRATION_FIELD = True, MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True, From cf2877b4d00421999363daa8ab8b30bbb8fa3c57 Mon Sep 17 00:00:00 2001 From: KyryloKireiev Date: Fri, 6 Sep 2024 12:14:18 +0300 Subject: [PATCH 7/7] fix: try to make code blcks visible 2 --- ...ding_custom_fields_to_the_registration.rst | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/how_tos/adding_custom_fields_to_the_registration.rst b/docs/how_tos/adding_custom_fields_to_the_registration.rst index 255de6c6f9..be55310dc3 100644 --- a/docs/how_tos/adding_custom_fields_to_the_registration.rst +++ b/docs/how_tos/adding_custom_fields_to_the_registration.rst @@ -20,7 +20,8 @@ You need to redefine several constants in the settings. Several methods can be u - Go to `Site configurations` in admin: {{LMS}}/admin/site_configuration/siteconfiguration/ - Add new settings to OrderedDict (create new `Site configurations` if it wasn't before): - .. code-block:: + .. code-block:: json + { "ENABLE_DYNAMIC_REGISTRATION_FIELDS": "true", "MFE_CONFIG": { @@ -45,7 +46,8 @@ You need to redefine several constants in the settings. Several methods can be u #. **For the local development or testing settings can be overriden in configuration files:** - For example, constants can be added here: `env/apps/openedx/settings/lms/development.py`: - .. code-block:: + .. code-block:: python + ENABLE_DYNAMIC_REGISTRATION_FIELDS = "true" MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = "true" @@ -56,7 +58,8 @@ You need to redefine several constants in the settings. Several methods can be u `In total, you must redefine 3 constants using the method that is most preferable for you:` - .. code-block:: + .. code-block:: python + ENABLE_DYNAMIC_REGISTRATION_FIELD = True, MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True, @@ -74,21 +77,23 @@ Everything said above in instructions “**A**” is also relevant for adding fi Example: - .. code-block:: + .. code-block:: json + { - "REGISTRATION_EXTENSION_FORM" = "you_application.form.ExtendedUserProfileForm", + "REGISTRATION_EXTENSION_FORM": "you_application.form.ExtendedUserProfileForm", "extended_profile_fields": [ - "your_new_field_id", - "subscribe_to_emails", - "confirm_age_consent", - "something_else" + "your_new_field_id", + "subscribe_to_emails", + "confirm_age_consent", + "something_else" ] } `In total, you must migrate to DB new user profile fields and redefine 3 constants using the method that is most preferable for you:` - .. code-block:: + .. code-block:: python + ENABLE_DYNAMIC_REGISTRATION_FIELD = True, MFE_CONFIG["ENABLE_DYNAMIC_REGISTRATION_FIELDS"] = True,