While previously in our posts we’ve described in short how newsletter works and all of its parts (components, controllers, models and methods), now we will describe you in detail how to use it and how it works.
First and foremost, it’s essential to understand that newsletter is made of two major parts. First one is newsletter form for subscription and second is newsletter form for updating subscription options or for unsubscribing from all of them.
Newsletter form for subscription contains an email field - where the user should enter his email, available newsletter categories - where the user should choose one or more categories to which he wants to subscribe and a “send” button with which then he can submit data and become subscribed to newsletter.
When a user subscribes to your newsletter, he should receive a default welcome email. Also, when he subscribes, his subscriber token is automatically created and saved in your database. This token is used for subscriber validation when he wants to update his newsletter categories or if he wants to unsubscribe from your newsletter. By default, this token is valid for two days.
Welcome email consist of these parts:
Newsletter email consist of these parts:
This welcome email and newsletter email (post notification email) are using our default mail layout and mail template, and if you don’t like look of it or want something to change (color of something, font size and etc.) you can do that by going to the OctoberCMS default settings and then click on Mail section and underneath it on Mail templates menu. There you have three side menus: layout, templates and partials.
If you want to change something in newsletter email layout, you should look and change code in these three layouts:
If you want to change something in newsletter email templates, you should look and change code in these:
And finally, if you want to change newsletter email header or footer, you should look at these two partials:
Newsletter form for updating users subscription options or for unsubscribing from all of them is made up from two steps. First step is a validation page where the user's email is being validated in order to reduce spam and other malicious attempts, and another step is where the user can update his choice of newsletter categories or choose to unsubscribe from all of them.
Subscriber will come to the validation page when he clicks on the link in the welcome email or post notification email (email he receives as newsletter - when a new blog within his subscription category is published and if checkbox “Send newsletter email” is checked), which is located in the footer.
After he is at the validation page, he should then enter his email in order to check if his token and email combination match (to make sure he is not spammer or if someone didn’t break into his email). From here, two possible situations can happen. First one is that maybe his token has expired. If that happens, he would see a message which says that his token has expired and he can then click on a button to send a new token on his email. If he clicks on that button, a new token and link to the update page will be sent to his email and then he should leave this page and check that email. Inside that new email, he should click again on a link in a footer to access the update page. Once again, he’ll be at the validation page and once again he should enter his email for validation where after if everything is ok, he should proceed to update the page.
So, second possible situation is happening only if validation is successful. Subscriber would get a page which is an “update” page and here he can update his newsletter categories (choose other category and uncheck existing category) or choose to unsubscribe from newsletter (from all categories).
To add and start using newsletter on your page, first you need to have some blog categories which will act as newsletter categories where users can subscribe. In order to make some blog categories as a newsletter categories, you have to go to the Blog section, choose one of the listed categories you want to be a newsletter category, click on them and check the checkbox “Is newsletter?”. After you’ve created a newsletter category and if you are writing some new blog post, in order for that post to be sent as newsletter email, it should be in the newsletter category (which you choose in category tab), it should be published and also it should have a checkbox “Send newsletter email” checked (in manage tab). But beware, for this first version of the Blog toolbox, post published date should be set in time you are currently writing or in future (although if set in future, it will be sent right away when you submit it). This will be fixed and upgraded in future updates/versions of Blog toolbox plugin.
Second important step is to login into backend administration and decide which page or pages should contain newsletter form for subscriptions and which page should act as and contain newsletter form for updating newsletter options or for unsubscribing from all of them. After you’ve decided, you should go to the CMS page section in administration and open these pages. Then, if you open Components parts of the CMS page section, you can see our component BLOG TOOLBOX listed there and inside you have eight available components. For this part, you should only pay attention to these components: Newsletter subscribe and User newsletter options.
In order to add a newsletter form with subscription options, you should add a Newsletter subscribe component and include it in a page or pages. And in order to add a newsletter form for updating user subscription options or to unsubscribe from all of them, you should add a User newsletter options component.
Now, when you have included all necessary newsletter components on your pages, you should then set up and configure necessary settings. There are two general settings menus that are important. First one is related to OctoberCMS default settings. In these settings, there is a System section and underneath Customize back-end menu. You should now set up App Name and upload your App Logo, if you haven’t already set up before (when you’ve installed October). This is important, because the name and logo you set up in here will show up in a newsletter email (in header) your subscribers will receive from now on. Second important settings are one that you can see in the Blog toolbox section, within the Settings menu. There are three main parts there:
Social settings contain two fields: one is for Facebook url, other is for Twitter url. These fields should contain your social links/urls and these urls will show up in your subscribers email as Facebook and Twitter icons (which contain these urls), so if a user clicks on any of these two, they’ll be redirected to a specified social page.
Welcome e-mail settings are related to welcome email for your subscribers. Here you can set up some values in these three fields. First field is for message which should appear in a welcome email. You can put whatever text you want here. Second field is for a title which should appear in a welcome email. You can also put here whatever title you want. And the third field is related to the button which appears in your welcome email. This button can contain a link for anything you want but it is recommended that it should be e.g. link to one of your pages (page sections) in order to keep your subscriber attention or to keep him on your page.
Post notification settings are related to newsletter email which users should receive every time some new blog post is published (also, that post must be in the newsletter category and the checkbox for “Send newsletter email” must be checked). Like in welcome e-mail settings, here you also have three fields. In the first field you should put a url to your blog page/section. This url is important because it is used for connecting your single blog post with your blog page/section, so when a subscriber clicks on a single post link in an email, it will redirect him properly. In the second field, you should put a url to your “update newsletter” page (page which contains User newsletter options component). This url is important because the newsletter token is added to this url dynamically as a GET parameter and with this url user can access the newsletter update page. And with the third field you can either include or exclude the author section in a post notification email.