GoodNewsRequestLinks Snippet Last update: 2019-10-02 15:42:11

What is GoodNewsRequestLinks?

GoodNewsRequestLinks is a snippet which upon request - sends a subscriber an email with secure links to update or cancel his subscriptions. Those are the same links which are (or should be) included with each newsletter they receive.

Subscribers only need to enter their email address in a web form, hit the Request button and the system will send them their personal secure links via email.

A susbcriber will never need to know his MODX user credentials! Updating the subscribers profile or unsubscription will be handled through a secure link from within an email with an aditional and unique secure ID parameter.

How to use the Snippet

You need to place the GoodNewsRequestLinks Snippet in the Resource where your link request form resides.

Default properties for the Snippet

The GoodNewsRequestLinks Snippet implements the following properties:

Property	Description	Default
`unsubscribeResourceId`	The ID of the resource for one-click unsubscription.
`profileResourceId`	The ID of the resource for editing the mailing profile.
`submittedResourceId`	If set, will redirect to the specified resource after the user submits the request links form.
`requestLinksEmailSubject`	The subject of the request links email.	lexicon string
`requestLinksEmailTpl`	The template for the request links email.	sample.GoodNewsRequestLinksEmailTpl
`requestLinksEmailTplAlt`	If set, will use this template instead of requestLinksEmailTpl (e.g. for plaintext mails).
`requestLinksEmailTplType`	The type of tpl provided for the request links email.	modChunk
`errTpl`	Chunk for error output.	<span class="error">[[+error]]</span>
`emailField`	The name of the field to use for the User's email address.	email
`sendUnauthorizedPage`	Whether or not to redirect a subscriber to the unauthorized page if not verified.	0 (= false)
`submitVar`	The name of the form submit button that triggers the submission.	goodnews-requestlinks-btn
`successMsg`	If page redirects to itself, this message will be set to a placeholder.	lexicon string
`validate`	A comma-separated list of fields to validate.
`placeholderPrefix`	The prefix to use for all placeholders set by this Snippet.

Sending personal secure links upon request

To enable this, you will need to create an Request Links page by creating a new Resource, and putting the GoodNewsRequestLinks Snippet inside of it. GoodNews comes with a ready to use Resource including the required form.

Next, you'll need to specify an email template Chunk to use for the email being sent to subscribers. GoodNews comes with a preinstalled sample Chunk of an email template: sample.GoodNewsRequestLinksEmailTpl.

An example GoodNewsRequestLinks Snippet call would look like this:

[[!GoodNewsRequestLinks?
    &unsubscribeResourceId=`72`
    &profileResourceId=`73`
    &requestLinksEmailTpl=`sample.GoodNewsRequestLinksEmailTpl`
    &requestLinksEmailSubject=`Your requested links to update or cancel your subscription at [[++site_name]]`
    &validate=`
        email:email:required,
        nospam:blank`
]]

This setup will send a subscriber an email with the content specified in the sample.GoodNewsRequestLinksEmailTpl Chunk with the specified subject line. The personal secure links in this email can be used to update or cancel subscriptions.

The &requestLinksEmailTpl property can be a Chunk name by default. You can change the type of the field by setting &requestLinksEmailTplType to one of the following values:

modChunk - The default. A name of a Chunk.
file - Specify a filename with an absolute path. You can use {core_path}, {base_path} or {assets_path} as placeholders for this value.
inline - Specify the html straight in the property value.

Sample Request Links Form

For a sample and universal GoodNews Request Links form please have a look at the code below.

<div class="container">
    <div class="header">
        <h1>[[++site_name]]</h1>
    </div>
    <div class="main">
        <h2>Update or cancel your subscription</h2>
        <p>
            Please enter the email address you used for subscription and click the <strong>Request Secure Links</strong> button. 
            We will send an email to the submitted address which contains quick-links to update or cancel your subscription.
        </p>
        [[!+error.message:notempty=`
            <p class="errorMsg">[[!+error.message]]</p>
        `]]
        [[!+success.message:notempty=`
            <p class="successMsg">[[!+success.message]]</p>
        `]]
        <form id="profileform" class="gon-form" action="[[~[[*id]]]]" method="post">
            <input type="hidden" name="nospam" value="[[!+nospam]]">
            <fieldset>
                <p class="fieldbg[[!+error.email:notempty=` fielderror`]]">
                    <label for="email">
                        E-Mail Address
                        [[!+error.email]]
                    </label>
                    <input type="email" name="email" id="email" value="[[!+email]]" placeholder="Please enter your e-mail address" required>
                </p>
            </fieldset>
            <p>
                <button type="submit" role="button" name="goodnews-requestlinks-btn" value="Request" class="button green">Request Secure Links</button>
            </p>
        </form>
    </div>
    <div class="footer">
        <p>&copy; Copyright [[++site_name]]</p>
    </div>
</div>