Tutorial: Creating custom form input experiences in Brightspot

Occasionally, there is a need to provide users with a form input that does not save anything to the database upon submission. Instead, submitting the form should trigger some other action or side effect. Although you could create such a form from scratch, it is often much easier to leverage Brightspot's native form rendering system.

In this tutorial, you will use Brightspot's form rendering capabilities outside of a standard content edit page. As a concrete example, you will build a form that allows users to send an email with a link to edit the content they are viewing.

Despite not saving data to the database, this custom form will still benefit from Brightspot's built-in form rendering, validation, and error handling mechanisms. By following this tutorial, you' will learn how to create a fully functional custom form input experience that provides a seamless and user-friendly interface for your Brightspot application.

The example form you will build will allow users to input the following fields:

From Email
To Email(s)
Subject
Message Body

Upon submission, the form will send an email with the provided details, including a link to edit the current content object.

Step 1: Defining the Form

Before diving into creating the custom form experience, you need to model the form itself. Since you will be leveraging Brightspot's native form rendering system, you can take advantage of Brightspot's data modeling techniques and features. This gives us access to everything Brightspot's data models and form UI have to offer, from custom validation to dynamic placeholders and notes.

The ShareEditLinkForm class below defines the form you want users to fill out:

showLineNumbers

1class ShareEditLinkForm extends Record {
2
3    @Required
4    @DynamicPlaceholderMethod("getDefaultFromEmail")
5    private String fromEmail;
6
7    private Set<String> to;
8
9    private String subject;
10
11    @Note("Use {{editLink}} to include the edit link in the message.")
12    private String message;
13
14    public String getFromEmail() {
15        return Optional.ofNullable(fromEmail).orElseGet(this::getDefaultFromEmail);
16    }
17
18    public Set<String> getTo() {
19        if (to == null) {
20            to = new HashSet<>();
21        }
22        return to;
23    }
24
25    //other getters and setters omitted
26
27    private String getDefaultFromEmail() {
28        return WebRequest.getCurrent().as(ToolRequest.class).getCurrentUser().getEmail();
29    }
30}

Note that this class extends Record even though you will never save it to the database. This is required to allow you to use Brightspot's form rendering capabilities. The class then defines fields for the from email, to email(s), subject, and message body. The fromEmail field is marked as @Required and uses the @DynamicPlaceholderMethod annotation to provide a default value (the current user's email address) if no value is provided.

Step 2: Create the ToolPage

Next, you need to create the ToolPage that will render the custom form input experience. This is done in the ShareEditLinkToolPage class:

showLineNumbers {1,4,7}

1@WebPath("/share-edit")
2public class ShareEditLinkToolPage extends ToolPage {
3    @WebParameter
4    private UUID contentId;
5
6    @WebParameter
7    private UUID id;
8
9    public void setContentId(UUID contentId) {
10        this.contentId = contentId;
11    }
12
13    ...
14}

1. Defines the CMS path where this ToolPage will serve requests from.
4. The contentId field allows us to pass in the ID of the content that the content edit link should point to. Using @WebParameter allows Brightspot to automatically bind the request parameter to the field. It also allows us to create URLs in type-safe manner via UrlBuilder which is shown later on in the tutorial.
7. The id field is used internally in this class to maintain a consistent State#id for the ShareEditLinkForm object.

Step 3: Rendering the Form

The onGet method is responsible for rendering the initial form:

showLineNumbers

1@Override
2protected void onGet() throws Exception {
3    ShareEditLinkForm form = new ShareEditLinkForm();
4    if (id != null) {
5        State.getInstance(form).setId(id);
6    }
7    writePageResponse(() -> createForm(form));
8}

It creates a new instance of the ShareEditLinkForm class and sets the ID of the current content object if it's available. It then calls the createForm method to render the form HTML. Note that the createForm method is passed as a lambda expression to the helper method writePageResponse (also shown below), which wraps the main content of the pop-up in some standard HTML and includes error handling.

showLineNumbers

1private Collection<FlowContent> createForm(ShareEditLinkForm form) throws Exception {
2    return Collections.singleton(FORM
3        .method(FormMethod.POST)
4        .action(new UrlBuilder(this.getClass()).build())
5        .className("standardForm")
6        .with(
7            INPUT.typeHidden().name("id").value(form.getId().toString()),
8            INPUT.typeHidden().name("typeId").value(form.getState().getTypeId().toString()),
9            capture(page, p -> p.writeFormFields(form)),
10            DIV.className("actions")
11                .with(
12                    INPUT.typeSubmit()
13                        .className("button")
14                        .value("Submit"))
15        )
16    );
17}
18
19private void writePageResponse(Callable<Collection<FlowContent>> getWidgetMainContent) {
20    response.toBody().write(DIV.className("widget").with(div -> {
21        div.add(H1.with("Share Edit Link"));
22        try {
23            div.addAll(getWidgetMainContent.call());
24        } catch (Exception e) {
25            FormRequest formRequest = WebRequest.getCurrent().as(FormRequest.class);
26            formRequest.getErrors().add(e);
27            div.add(formRequest.getErrorMessages());
28        }
29    }));
30}

The createForm method creates an HTML <form> element with the appropriate attributes, including hidden inputs for the ID and type ID. It then uses ToolPageContext#writeFormFields to render the individual form fields based on the ShareEditLinkForm class, and adds a submit button.

Step 4: Processing Form Submissions

The onPost method is responsible for processing form submissions:

showLineNumbers {5,7,27,30}

1@Override
2protected void onPost() throws Exception {
3    ShareEditLinkForm form = new ShareEditLinkForm();
4    if (id != null) {
5        State.getInstance(form).setId(id);
6    }
7    page.updateUsingParameters(form);
8
9    if (form.getState().validate()) {
10        //Send share edit link email
11        MailProvider mailProvider = MailProvider.Static.getDefault();
12        for (String to : form.getTo()) {
13            mailProvider.send(new MailMessage()
14                .to(to)
15                .from(form.getFromEmail())
16                .subject(form.getSubject())
17                .bodyPlain(form.getMessage().replace("{{editLink}}", editUrl)));
18        }
19
20        writePageResponse(() -> Arrays.asList(
21            DIV.with(
22                DIV.className("message message-success").with("Email sent!"),
23                BR,
24                DIV.className("actions")
25                    .with(INPUT.typeSubmit()
26                        .className("button")
27                        .attr("onClick", "window.location.reload();")
28                        .value("Done")))));
29    } else {
30        writePageResponse(() -> createForm(form));
31    }
32}

5. This ensures the form object has the correct State#id based on the request parameters. Without this Line # 7 will not function correctly.
7. Populates the form object with form submission data.
27. In this case, the "Done" button refreshes the page. You could choose other methods of closing the pop-up window if desired.
30. The form does not pass validation, so we write the form again which will include the error messages

This method creates a new instance of the ShareEditLinkForm class and populates it with the request parameters using ToolPageContext#updateUsingParameters. If the form is valid, it sends an email using the MailProvider with the data from the form (to email(s), from email, subject, and message body). If the form is invalid, it re-renders the form, which will include any error messages.

Step 5: Create an access link to your Custom Form

Lastly, now that you have the ShareEditLinkForm and ToolPage defined, you need to create a way for users to access the custom form input experience. In this case, you are going to leverage the ContentEditAction API to place a link in the Content Tools dropdown on the Content Edit page. When clicked, this link will open the target URL in a pop-up window in the CMS.

Note that using ContentEditAction for this step is just one option of many. The link could just as well have been included in a Widget or in a Dynamic Note on a field. How you give users access to your form is based on your unique feature requirements.

showLineNumbers {5,10}

1public class ShareEditLink implements ContentEditAction {
2
3    @Override
4    public void writeHtml(ToolPageContext page, Object content) throws IOException {
5        page.write(LI
6            .with(
7                A.href(new UrlBuilder(
8                        ShareEditLinkToolPage.class,
9                        p -> p.setContentId(State.getInstance(content).getId())).build())
10                    .target("request")
11                    .with("Share Edit Link")
12            )
13        );
14    }
15}

5. Uses Dari HTML and UrlBuilder to create an HTML link to the ShareEditLinkToolPage
10. The request link target tells Brightspot to load the URL in a pop-up window.

Conclusion

With all the steps completed, you now have a fully functional custom form input experience that allows users to share an edit link for the current content object via email. By leveraging Brightspot's native form rendering system, you have been able to create a user-friendly interface with built-in validation and error handling, while still maintaining the flexibility to perform custom actions upon form submission.

Full Code

Here's the full code for the tutorial:

showLineNumbers

1package brightspot.docs;
2
3import java.util.HashSet;
4import java.util.Optional;
5import java.util.Set;
6
7import com.psddev.cms.ui.ToolRequest;
8import com.psddev.cms.ui.form.DynamicPlaceholderMethod;
9import com.psddev.cms.ui.form.Note;
10import com.psddev.dari.db.Record;
11import com.psddev.dari.web.WebRequest;
12
13class ShareEditLinkForm extends Record {
14
15    @Required
16    @DynamicPlaceholderMethod("getDefaultFromEmail")
17    private String fromEmail;
18
19    private Set<String> to;
20
21    private String subject;
22
23    @Note("Use {{editLink}} to include the edit link in the message.")
24    private String message;
25
26    public String getFromEmail() {
27        return Optional.ofNullable(fromEmail).orElseGet(this::getDefaultFromEmail);
28    }
29
30    public Set<String> getTo() {
31        if (to == null) {
32            to = new HashSet<>();
33        }
34        return to;
35    }
36
37    public String getSubject() {
38        return subject;
39    }
40
41    public void setSubject(String subject) {
42        this.subject = subject;
43    }
44
45    public String getMessage() {
46        return message;
47    }
48
49    public void setMessage(String message) {
50        this.message = message;
51    }
52
53    private String getDefaultFromEmail() {
54        return WebRequest.getCurrent().as(ToolRequest.class).getCurrentUser().getEmail();
55    }
56}

showLineNumbers

1package brightspot.core.article;
2
3import java.util.Arrays;
4import java.util.Collection;
5import java.util.Collections;
6import java.util.UUID;
7import java.util.concurrent.Callable;
8
9import com.psddev.cms.ui.ToolPage;
10import com.psddev.cms.ui.form.FormRequest;
11import com.psddev.dari.db.State;
12import com.psddev.dari.html.content.FlowContent;
13import com.psddev.dari.html.enumerated.FormMethod;
14import com.psddev.dari.util.MailMessage;
15import com.psddev.dari.util.MailProvider;
16import com.psddev.dari.web.UrlBuilder;
17import com.psddev.dari.web.WebRequest;
18import com.psddev.dari.web.annotation.WebParameter;
19import com.psddev.dari.web.annotation.WebPath;
20
21import static com.psddev.cms.ui.Components.*;
22
23@WebPath("/share-edit")
24public class ShareEditLinkToolPage extends ToolPage {
25
26    @WebParameter
27    private UUID contentId;
28
29    @WebParameter
30    private UUID id;
31
32    public void setContentId(UUID contentId) {
33        this.contentId = contentId;
34    }
35
36    @Override
37    protected void onGet() throws Exception {
38        ShareEditLinkForm form = new ShareEditLinkForm();
39        if (id != null) {
40            State.getInstance(form).setId(id);
41        }
42        writePageResponse(() -> createForm(form));
43    }
44
45    @Override
46    protected void onPost() throws Exception {
47        ShareEditLinkForm form = new ShareEditLinkForm();
48        if (id != null) {
49            State.getInstance(form).setId(id);
50        }
51        page.updateUsingParameters(form);
52
53        if (form.getState().validate()) {
54            String editUrl = new UrlBuilder("/content/edit.jsp").setParameter("id", contentId).build();
55            MailProvider mailProvider = MailProvider.Static.getDefault();
56            for (String to : form.getTo()) {
57                mailProvider.send(new MailMessage()
58                    .to(to)
59                    .from(form.getFromEmail())
60                    .subject(form.getSubject())
61                    .bodyPlain(form.getMessage().replace("{{editLink}}", editUrl)));
62            }
63
64            writePageResponse(() -> Arrays.asList(
65                DIV.with(
66                    DIV.className("message message-success").with("Email sent!"),
67                    BR,
68                    DIV.className("actions")
69                        .with(INPUT.typeSubmit()
70                            .className("button")
71                            .attr("onClick", "window.location.reload();")
72                            .value("Done")))));
73        } else {
74            writePageResponse(() -> createForm(form));
75        }
76    }
77
78    private Collection<FlowContent> createForm(ShareEditLinkForm form) throws Exception {
79        return Collections.singleton(FORM
80            .method(FormMethod.POST)
81            .action(new UrlBuilder(this.getClass()).build())
82            .className("standardForm")
83            .with(  INPUT.typeHidden().name("id").value(form.getId().toString()),
84                INPUT.typeHidden().name("typeId").value(form.getState().getTypeId().toString()),
85                capture(page, p -> p.writeFormFields(form)),
86                DIV.className("actions")
87                    .with(
88                        INPUT.typeSubmit()
89                            .className("button")
90                            .value("Submit"))
91            )
92        );
93    }
94
95    private void writePageResponse(Callable<Collection<FlowContent>> getWidgetMainContent) {
96        response.toBody().write(DIV.className("widget").with(div -> {
97            div.add(H1.with("Share Edit Link"));
98            try {
99                div.addAll(getWidgetMainContent.call());
100            } catch (Exception e) {
101                FormRequest formRequest = WebRequest.getCurrent().as(FormRequest.class);
102                formRequest.getErrors().add(e);
103                div.add(formRequest.getErrorMessages());
104            }
105        }));
106    }
107
108}

showLineNumbers

1package brightspot.core.article;
2
3import java.io.IOException;
4
5import com.psddev.cms.tool.ContentEditAction;
6import com.psddev.cms.tool.ToolPageContext;
7import com.psddev.dari.db.State;
8import com.psddev.dari.web.UrlBuilder;
9
10import static com.psddev.dari.html.Nodes.*;
11
12public class ShareEditLink implements ContentEditAction {
13
14    @Override
15    public void writeHtml(ToolPageContext page, Object content) throws IOException {
16        page.write(LI
17            .with(
18                A.href(new UrlBuilder(
19                        ShareEditLinkToolPage.class,
20                        p -> p.setContentId(State.getInstance(content).getId())).build())
21                    .target("request")
22                    .with("Share Edit Link")
23            )
24        );
25    }
26}

Step 1: Defining the Form​

Step 2: Create the ToolPage​

Step 3: Rendering the Form​

Step 4: Processing Form Submissions​

Step 5: Create an access link to your Custom Form​

Full Code​

Step 1: Defining the Form

Step 2: Create the ToolPage

Step 3: Rendering the Form

Step 4: Processing Form Submissions

Step 5: Create an access link to your Custom Form

Full Code