Create a bean that represents the subscription form and add an adequate template.

  public class SubscriptionForm {
  public String email;

  public void setEmail(String email) {
    this.email = email;
  }

  public String getEmail() {
    return email;
  }
}
      

SubscriptionForm.asTeaser.ftl

        <%--@ftlvariable id="self" type="com.mycompany.SubscriptionForm "--%>
<%--@ftlvariable id="subscriptionForm" type="com.mycompany.SubscriptionForm "--%>
<%--@ftlvariable id="cmpage" type="com.coremedia.blueprint.common.contentbeans.Page"--%>
<#assign redirectUri=cm.getLink(cmpage.linkable)/>
<#assign subscriptionUri=cm.getLink(cmpage, "", {"return" : redirectUri})/>
<form method="post" action="${subscriptionUri}">
    <@spring.formInput path="subscriptionForm.email"/>
  <input type="submit" value="Subscribe"/>
</form>

      

Add a handler that is able to process the subscription as well as a link scheme that builds links pointing to the handler.

        @Link
@RequestMapping
public class SubscriptionHandler {

  @RequestMapping(value="/subscribe", method=RequestMethod.POST)
  public ModelAndView handleSubscription(@RequestParam(value="return", required=true) String redirectUri,
                                         @ModelAttribute("subscriptionForm") SubscriptionForm form,
                                         HttpServletRequest request, HttpServletResponse response)
          throws IOException {
    doSubscribe(request.getSession(), form.getEmail());
    response.sendRedirect(redirectUri);
    return null;
  }

  @Link(type=SubscriptionForm.class, parameter="return", uri="/subscribe")
  public UriComponents createSubscriptionLink(UriComponentsBuilder uri, Map<String,Object> parameters) {
    return uri.queryParam("return", (String) parameters.get("return")).build();
  }

  ...
}
      

Don't forget to register this class as a bean in the Spring application context.

Define an action substitution.

        public class SubscriptionHandler {
  ...
  @Substitution("com.coremedia.subscription", modelAttribute="subscriptionForm")
  public SubscriptionForm createSubscriptionSubstitution(CMAction original, HttpServletRequest request) {
    return new SubscriptionForm();
  }
  ...
}
      

Notes

Create a newsletter action content

The request will be accepted by the PageHandler that builds a ModelAndView containing the Page model. This model's tree of content beans contains the new CMAction instance.

The model will be rendered by initially invoking Page.ftl for the Page bean.

When the CMAction is going to be rendered in the teaser list, the template CMAction.asTeaser.ftl is invoked. This template substitutes the CMAction bean by invoking the cm.substitute() function while using the ID com.coremedia.subscription.

The substitution framework invokes the method #createSubscriptionSubstitution after checking whether SubstitutionRegistry#register has been invoked by any handler for his ID (which hasn't happened here). As the result, the substitutions result is a bean of type SubscriptionForm.

The above mentioned template CMAction.asTeaser.ftl therefore delegates to SubscriptionForm.asTeaser.ftl then.

While rendering SubscriptionForm.asTeaser.ftl, a link pointing to this form bean is going to be built. The method #createSubscriptionLink is chosen as a link scheme so that the link points to the handler method #handleSubscription.

After the user has received the rendered page, he might enter his email address and press the submit button.

This new (POST) request is accepted by the mentioned handler method #handleSubscription that performs the subscription and redirects the original page then so that the first step of this flow is repeated.

Place your flow definition file somewhere below a package named webflow somewhere in the classpath. The name of the flow definition file should be <action_id>.xml. Example: For an action com.mycompany.MyFlowAction you might create a file com.mycompany.MyFlowAction.xml that can be placed below a package com.coremedia.blueprint.mycompany.webflow.

For every flow view (such as "success" or "failure") create a ftl template. The template name needs to match the action id. Example: The action com.mycompany.MyFlowAction requires templates to be named .../templates/com.mycompany/MyFlowAction.<flowView>.ftl. These templates will be invoked for the mentioned beans of type WebflowActionState.

Create (and integrate) a new content item of type CMAction and set the property id to the action id (such as com.mycompany.MyFlowAction) and the property type to webflow.