# Form Mapping Reference

The **Forms** tab in GravityOps Forum allows you to map Gravity Forms and their fields to the core entities of your forum (Topics and Replies). This provides the essential bridge between Gravity Forms entries and the forum content.

---

## 1. Assignment Scope (Context)

You can define form assignments at different levels. The forum uses an inheritance model to determine which form to display.

-   **Global Default**: The default Gravity Form used for all Topics or Replies across the entire board if no specific override is set.
-   **Specific Board**: An assignment that applies only to a chosen Board. This overrides the Global Default.
-   **Specific Forum**: The most granular assignment. This applies only to a single Forum and overrides both Board-level and Global assignments.

---

## 2. Form Types

Each assignment must specify which type of forum entity it handles:

-   **Topic Form**: Used when a user creates a new discussion topic within a forum.
-   **Reply Form**: Used when a user posts a reply to an existing topic.
-   **Login Form**: Used for the forum's authentication interface.
-   **Registration Form**: Used to allow users to create an account directly from the forum.

> [!WARNING]
> **Free and Pro Tiers: One Type Per Form**  
> Each Gravity Form can only be assigned to a single **Form Type** (e.g., a form can be a Topic form OR a Reply form, but not both). The plugin will prevent and display an error if you attempt to assign a form to a second type. This ensures that form entries are always processed correctly as their intended type.

> [!IMPORTANT]
> **Premium Tier and Above: Multiple Types Allowed**  
> Premium users can assign the same Gravity Form to multiple form types when needed (e.g., a single form used for Topics and Replies with different feed logic).

---

## 3. Field Mapping

Mapping determines which fields from your Gravity Form are used to populate the forum's content.

> [!IMPORTANT]
> **Free and Pro Tiers: Enforced Consistent Mappings**  
> If you use the same Gravity Form for the **same assignment type** across multiple contexts (e.g., the same Topic form for two different Forums), the field mappings **must** be identical.  
>  
> To help maintain this, the plugin will automatically populate and lock field mappings when you select a form that is already assigned to the same type elsewhere. This prevents inconsistent data processing for the same form.

> [!IMPORTANT]
> **Premium Tier and Above: Multiple Mappings Allowed**  
> Premium users can assign the same form to multiple contexts with different mappings. When doing so, use Feed Conditional Logic to ensure each feed only runs in its intended context.

> [!IMPORTANT]
> **Premium Tier and Above: Multiple Assignments per Forum/Board**  
> Premium users can assign multiple Topic or Reply forms to the same Forum or Board. This is most useful when paired with Feed Conditional Logic to direct submissions correctly.

### Topic Form Fields

When assigning a **Topic Form**, you must map the following:

-   **Title Field**: Select the Gravity Form field (usually a single-line text field) that will serve as the Topic's title in the forum index and topic view.
-   **Content Field**: (Required) Select the Gravity Form field (usually a paragraph text or textarea) that will contain the main body of the first post in the topic.
    -   **Pro Tip**: In your Gravity Form, enable the **Visual Editor** (Rich Text) setting for this field to allow users to format their posts (bold, italics, lists, etc.).
-   **Tags Field**: (Optional) Select the Gravity Form field (usually a single-line text field) that will be used to generate tags for the topic.
- **Additional Fields to Display (Paid only)**: (Optional) Multi-select Gravity Form fields that you want to display on the forum in addition to the title and content. This feature is only available on paid plans. These fields will be shown below the main post content with their respective labels.
    -   **Pro Tip**: You can use the **File Upload** field to allow users to attach files to their topics.

### Reply Form Fields

When assigning a **Reply Form**, only the content field is required:

-   **Content Field**: (Required) Select the Gravity Form field that will contain the text of the user's reply.
    -   **Pro Tip**: Just like with the Topic Form, enabling the **Visual Editor** for this field provides a better experience for users when replying.
- **Additional Fields to Display (Paid only)**: (Optional) Multi-select Gravity Form fields that you want to display on the forum in addition to the content. This feature is only available on paid plans. These fields will be shown below the reply content with their respective labels.

### Login Form Fields

When assigning a **Login Form**, you must map the following:

-   **Username or Email Field**: Select the Gravity Form field (usually a single-line text or email field) that users will use to identify themselves.
-   **Password Field**: Select the Gravity Form field (usually a password field) where users enter their account password.
    -   **Pro Tip**: Configure the Password field in Gravity Forms to **Enable Password Visibility Toggle**. This allows users to see what they are typing.

### Registration Form Fields

When assigning a **Registration Form**, you can map the following fields to WordPress user profile data:

-   **Username Field**: (Required) Select the Gravity Form field for the new user's username.
-   **Email Field**: (Required) Select the Gravity Form field for the user's email address.
-   **Password Field**: (Required) Select the Gravity Form field where the user sets their password.
    -   **Pro Tip**: For registration, enable the **Password Confirmation** setting in the Password field to ensure users enter their desired password correctly. You can also enable the **Password Strength** meter.
-   **Nickname Field**: (Optional) Select a field to map to the WordPress user's nickname.
-   **Display Name Field**: (Optional) Select a field to map to the WordPress user's public display name.

> [!NOTE]
> **Registration Role is Fixed**  
> All accounts created through public registration are hard-locked to the **Subscriber** role. This is not configurable.
