Better document admin form customization (#3042)

* Updated these to include theme change needs, use breadcrumb component

* document admin forms more fully

* broke out limitations to sep included file

astro/src/content/docs/_shared/_admin-user-form.mdx

@@ -1,12 +1,21 @@
+import Breadcrumb from 'src/components/Breadcrumb.astro';
 import InlineUIElement from 'src/components/InlineUIElement.astro';
 import InlineField from 'src/components/InlineField.astro';
 
 This form is what you see when you are adding or editing a user in the admin UI. This is configurable at the Tenant level.
 
-If you need to capture and validate custom data, you can do so by creating a form field, by navigating to <strong>Customizations -> Form Fields</strong>. You should create any needed fields before you create a form. Otherwise you can use the standard form fields.
+If you need to capture and validate custom data, you can do so by creating a form field, by navigating to <Breadcrumb>Customizations -> Form Fields</Breadcrumb>. You should create any needed fields before you create a form. Otherwise you can use the standard form fields.
 
-Create a form, by navigating to <strong>Customizations -> Forms</strong>. Select <InlineUIElement>Admin User</InlineUIElement> as the type. Add the needed sections and fields.
+Create a form, by navigating to <Breadcrumb>Customizations -> Forms</Breadcrumb>. Select <InlineUIElement>Admin User</InlineUIElement> as the type. Add the needed sections and fields.
 
-Configure the FusionAuth admin UI to use these forms by navigating to <strong>Tenants -> Your Tenant -> General</strong> and then to the <strong>Form settings</strong> section. Set the <InlineField>Admin user form</InlineField> field to your new form.
+You should modify your theme to add labels for these custom fields for proper display in the admin UI. For example, if you added a field stored in `user.data.favoriteColor`, you'd add the following key to the messages file of your theme to add a label of `Favorite Color` to the field in the admin UI.
+
+```
+user.data.favoriteColor=Favorite Color
+```
+
+This field is not localizable, so you'll only need to modify the default messages file. [Learn more about modifying the messages file in your theme](/docs/customize/look-and-feel/localization#messages).
+
+Configure the FusionAuth admin UI to use these forms by navigating to <Breadcrumb>Tenants -> Your Tenant -> General</Breadcrumb> and then to the <Breadcrumb>Form settings</Breadcrumb> section. Set the <InlineField>Admin user form</InlineField> field to your new form.
 
 Learn more in the [Tenant documentation](/docs/get-started/core-concepts/tenants#general).

astro/src/content/docs/_shared/_admin-user-registration-form.mdx

@@ -1,13 +1,22 @@
+import Breadcrumb from 'src/components/Breadcrumb.astro';
 import InlineUIElement from 'src/components/InlineUIElement.astro';
 import InlineField from 'src/components/InlineField.astro';
 
 This form is what you see when you are adding or editing a user registration to an application using the admin UI. This is configurable at the Application level.
 
-If you need to capture and validate custom data, you can do so by creating a form field, by navigating to <strong>Customizations -> Form Fields</strong>. You should create any needed fields before you create a form. Otherwise you can use the standard form fields.
+If you need to capture and validate custom data, you can do so by creating a form field, by navigating to <Breadcrumb>Customizations -> Form Fields</Breadcrumb>. You should create any needed fields before you create a form. Otherwise you can use the standard form fields.
 
-Create a form, by navigating to <strong>Customizations -> Forms</strong>. Select <InlineUIElement>Admin Registration</InlineUIElement> as the type. Add the needed sections and fields.
+Create a form, by navigating to <Breadcrumb>Customizations -> Forms</Breadcrumb>. Select <InlineUIElement>Admin Registration</InlineUIElement> as the type. Add the needed sections and fields.
 
-Then, configure the FusionAuth admin UI to use these forms by navigating to <strong>Applications -> Your Application -> Registration</strong> and then to the <strong>Form settings</strong> section. Set the <InlineField>Admin Registration</InlineField> field to your new form.
+You should modify your theme to add labels for these custom fields for proper display in the admin UI. For example, if you added a field stored in `registration.data.backgroundColor`, you'd add the following key to the messages file of your theme to add a label of `Desired Background Color` to the field in the admin UI.
+
+```
+registration.data.backgroundColor=Desired Background Color
+```
+
+This field is not localizable, so you'll only need to modify the default messages file. [Learn more about modifying the messages file in your theme](/docs/customize/look-and-feel/localization#messages).
+
+Then, configure the FusionAuth admin UI to use these forms by navigating to <Breadcrumb>Applications -> Your Application -> Registration</Breadcrumb> and then to the <Breadcrumb>Form settings</Breadcrumb> section. Set the <InlineField>Admin Registration</InlineField> field to your new form.
 
 Learn more in the [Application documentation](/docs/get-started/core-concepts/applications#registration).
 

astro/src/content/docs/get-started/core-concepts/limitations.mdx

@@ -23,6 +23,7 @@ import TemplateContentLimits from 'src/content/docs/_shared/_template-content-li
 import TerraformLimitations from 'src/content/docs/operate/deploy/_terraform-limitations.mdx';
 import IdentityProviderLimitations from 'src/content/docs/_shared/_identity-provider-limits.mdx';
 import GroupLimits from 'src/content/docs/get-started/core-concepts/_group-limits.md';
+import AdminCustomFormLimitations from 'src/content/docs/lifecycle/manage-users/_custom-admin-form-limitations.mdx';
 
 
 ## Overview
@@ -165,6 +166,10 @@ If you need to migrate hashes from FusionAuth to any other system, use a databas
 
 <GroupLimits />
 
+## Admin Custom Forms
+
+<AdminCustomFormLimitations />
+
 ## What's Not Limited
 
 All other objects and configuration, including but not limited to the following, are limited only by the resources of your system:

astro/src/content/docs/lifecycle/manage-users/_custom-admin-form-limitations.mdx

@@ -0,0 +1,7 @@
+import Breadcrumb from 'src/components/Breadcrumb.astro';
+
+You cannot display different forms to different types of users. If required, the best option is to use the various APIs and build your own forms. You can use the [Form Field](/docs/apis/custom-forms/form-fields) and [Form APIs](/docs/apis/custom-forms/forms) to manage the fields and forms.
+
+Custom field labels in the admin UI, like other parts of it, cannot be localized.
+
+All custom fields are always viewable in the <Breadcrumb>User data</Breadcrumb> tab. Encrypt any data stored in a custom data field that should not be viewable to an admin user.

astro/src/content/docs/lifecycle/manage-users/admin-forms.mdx

@@ -0,0 +1,106 @@
+---
+title: Custom Admin Forms
+description: How and why to customize forms in the admin UI.
+navcategory: developer
+section: lifecycle
+subcategory: manage users
+---
+import AdminCustomFormLimitations from 'src/content/docs/lifecycle/manage-users/_custom-admin-form-limitations.mdx';
+import AdminUserForm from 'src/content/docs/_shared/_admin-user-form.mdx';
+import AdminUserRegistrationForm from 'src/content/docs/_shared/_admin-user-registration-form.mdx';
+import Breadcrumb from 'src/components/Breadcrumb.astro';
+import PremiumEditionBlurb from 'src/content/docs/_shared/_premium-edition-blurb.astro';
+
+## Overview
+
+With custom admin forms, you can modify the administrative user interface (admin UI) and customize your view of Users or Registrations. While FusionAuth ships with usable admin UI forms, if you have user or registration fields that are unique to your use case or business, this feature may be useful to you.
+
+This can be useful if there are custom data fields that you want to let users of the admin UI edit, while applying validation rules. With this feature, you are changing the way user data can be edited, not the way it is viewed in the admin UI.
+
+These fields are like any other custom data fields and [can be searched](/docs/lifecycle/manage-users/search/user-search-with-elasticsearch) in the same way.
+
+<PremiumEditionBlurb />
+
+### The User Form
+
+<AdminUserForm />
+
+### The Registration Form
+
+<AdminUserRegistrationForm />
+
+## Example
+
+Suppose you needed to capture two additional fields for your application:
+
+* a user's favorite color 
+* a user's desired background color on a specific application
+
+If you want these fields to be editable in the admin UI so that customer service reps could update the colors when the user called in. (You can also make these fields editable by the end user, see [Update User Profiles and Passwords](/docs/lifecycle/manage-users/account-management/updating-user-data) for more.)
+
+You can create two custom form fields called `user.data.favoriteColor` and `registration.data.backgroundColor`. Then you create a new user form and add the `favoriteColor` field to it.
+
+You'd also create a new registration form and add the `backgroundColor` field to it. 
+
+You'd also need to update the theme's messages file as mentioned above in order to have the correct form labels. If you do not, the keys of the fields will be used as the labels.
+
+Finally, you'd update the tenant settings to use the new user form, and the application to use the new registration form. 
+
+### Results
+
+Here's the admin user form after you've added the `user.data.favoriteColor` field. 
+
+![Admin User Form after adding a custom field.](/img/docs/lifecycle/manage-users/custom-admin-forms/custom-user-form.png)
+
+Here's the admin registration form after you've added the `user.data.favoriteColor` field. 
+
+![Admin Registration Form after adding a custom field.](/img/docs/lifecycle/manage-users/custom-admin-forms/custom-registration-form.png)
+
+Here's an example of a user who has had both custom fields updated. The <Breadcrumb>User data</Breadcrumb> tab will display custom data. 
+
+
+![User details view after their custom fields have been updated.](/img/docs/lifecycle/manage-users/custom-admin-forms/display-custom-data.png)
+
+The layout and labels of the custom data can't be modified.
+
+## View Only Admin User Data Access
+
+Custom admin forms are useful for allowing users with access to the admin UI to edit profile data. If you only want to allow the user to view profile data, you can give them the [appropriate FusionAuth admin UI role](/docs/get-started/core-concepts/roles#fusionauth-application-roles), typically `user_support_viewer`.
+
+They can then navigate to <Breadcrumb>Users -> The User</Breadcrumb> and then to the <Breadcrumb>User data</Breadcrumb> tab.
+
+## Access Paths
+
+You can have multiple types of custom data fields. You can have fields that are editable in:
+
+* the admin UI, appropriate for fields that should only be edited by admin users
+* the self-service account management UI, appropriate for fields that can be edited by end users
+* neither, appropriate for fields that are used by software systems
+
+You can always edit custom data fields directly using the [User API](/docs/apis/users) or [Registration API](/docs/apis/registrations). Or, if you prefer not to make raw HTTP API calls, a [client library](/docs/sdks) with an appropriate API key.
+
+## Difference Between User And Registration Fields
+
+You have two options for storing custom data:
+
+* The `user.data` field
+* The `registration.data` field
+
+How can you choose between these? Users exist independent of any other entity, though they are contained within a Tenant, and that Registrations join Users with Applications. Therefore, if a field is part of a User, it should be stored in `user.data`. If, on the other hand, the field only makes sense in the context of a User and an Application, then use the `registration.data` field.
+
+Examples of fields that should be stored on the user:
+
+* Unchanging or slowly changing attributes like the user's shoe size or favorite color
+* Identifiers tying the user to other systems
+* Cross-application preferences like timezone
+
+Examples of fields that should be stored on the registration:
+
+* Application preferences such as background color or profile header image
+* User controllable attributes such as a displayed nickname or friends list
+* Application data such as the last access date or last file opened
+
+## Limitations
+
+<AdminCustomFormLimitations />
+