Freeform for Craft

4.x

• 5.x✓ Latest
• 4.x
• 3.xRetired
• 2.xRetired
• 1.xRetired

Plugin Store

Overview

# Relating Submissions to Elements Pro

Freeform Relations become a suitable replacement for Comments, Ratings, Product Reviews, simple sign-up forms for Calendar events and more!

# Overview

Freeform allows you to intuitively relate form submissions to any other Craft (or third party) Element. This is done by feeding the Craft Element ID to Freeform's relations parameter in the Form query, thus allowing you to use Freeform forms to do anything such as allow users to submit comments on Craft Entries, post ratings and reviews for Entries or Commerce Products, relate submissions to Users and more!

# How it Works

When pairing the Freeform Submissions element fieldtype with the relations parameter in the Form query, you can automate attaching/relating of Freeform submissions to other Craft elements when the form is submitted. The submission(s) are then attached to the other element and appear visually in those elements the same way as Assets do in the control panel, and more importantly, can then be used to easily display those submissions tied to the Craft Element inside your templates.

# How to Setup

See the options below for some examples to get you started quickly:

• Simple Setup
• Relating More Than One Element
• Displaying Related Submissions

# Simple Setup

Here's instructions for setting up a simple relation of Freeform submissions to Craft Entries. A common use-case might be allowing comments or reviews for a product (being a Craft Entry). Let's assume you're on a single entry page.

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

{{ craft.freeform.form("productReviewsForm").render() }}

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

{{ craft.freeform.form("productReviewsForm").render({
    relations: {
        productReviews: entry.id,
    },
}) }}

# Relating More Than One Element

Let's take the above example a little further. The following guide will show you how to relate Freeform submissions to Craft Entries and the currently logged in user. A common use-case might be allowing comments or reviews for a product (being a Craft Entry) and also tying them to the currently logged in user. Let's assume you're on a single entry page again...

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

{{ craft.freeform.form("productReviewsForm").render() }}

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

{{ craft.freeform.form("productReviewsForm").render({
    relations: {
        productReviews: entry.id,
        userReviews: currentUser.id,
    },
}) }}

# Displaying Related Submissions

If you'd like to display submissions that are related to any given Craft Element, you would do this by calling the Freeform Submissions field in your element, and using the ID(s) it contains to populate a Submissions query.

Let's work off of the Relating More Than One Element example above. If you used the Simple Setup example, just ignore the Users part of this guide. Again, we're assuming you have a Freeform Submissions field with a handle of productReviews for Craft Entries, and another Freeform Submissions field with a handle of userReviews for Craft Users.

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

{{ craft.freeform.form("productReviewsForm").render({
    relations: {
        productReviews: entry.id,
        userReviews: currentUser.id,
    },
}) }}

<h2>{{ entry.title }}</h2>
<p>Posted on {{ entry.postDate.format('F d, Y') }}</p>
<p>{{ entry.description }}</p>

{{ craft.freeform.form("productReviewsForm").render({
    relations: {
        productReviews: entry.id,
        userReviews: currentUser.id,
    },
}) }}

{% if entry.productReviews|length %}

    <h3>Reviews</h3>

    {% set submissions = craft.freeform.submissions({
        id: entry.productReviews.ids(),
        orderBy: "dateCreated DESC",
        status: "open"
    }) %}

    <div class="reviews">
    {% for submission in submissions.all() %}
        <div class="review">
            <h4>{{ submission.title }}</h4>
            <p>
                {% set relatedUser = craft.users().relatedTo(submission.id).one() %}
                <i>Submitted by: <a href="{{ url('profiles/'~relatedUser.username) }}">{{ relatedUser.name }}</a></i>
            </p>
            <p>{{ submission.message }}</p>
        </div>
    {% endfor %}
    </div>

{% endif %}

# Email Notifications

To display the Craft element(s) you have related the Freeform submission to inside of an email notification, you can do that with the following code inside your email notification template:

<ul>
{% for element in craft.entries.relatedTo(submission.id).all %}
    <li>{{ element.title }}</li>
{% endfor %}
</ul>