{"_id":"5937b23a8e8d9b002f1df2a4","category":{"_id":"5937b2388e8d9b002f1df271","version":"5937b2378e8d9b002f1df26e","project":"542fe92a5eceb608003fddc8","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-05-18T14:06:32.423Z","from_sync":false,"order":2,"slug":"features","title":"Features"},"project":"542fe92a5eceb608003fddc8","user":"542c5cfcddd3190e00228849","parentDoc":null,"version":{"_id":"5937b2378e8d9b002f1df26e","project":"542fe92a5eceb608003fddc8","__v":1,"createdAt":"2017-06-07T07:58:47.936Z","releaseDate":"2017-06-07T07:58:47.936Z","categories":["5937b2388e8d9b002f1df26f","5937b2388e8d9b002f1df270","5937b2388e8d9b002f1df271","5937b2388e8d9b002f1df272","5937b2388e8d9b002f1df273","5937b2388e8d9b002f1df274"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-18T14:07:32.327Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Beta Feature\",\n  \"body\": \"The subscribers feature is currently a Beta feature and is subject to heavy change over the coming months. We'll be trying not to break things, but be aware you may need to make theme updates to keep the feature working fully.\\n\\nTo enable this feature, visit yourblog.com/ghost/settings/labs/ and tick the 'Subscribers' checkbox.\"\n}\n[/block]\n*Documentation in progress ✨*\n\nWhen a user enables the \"subscribers\" feature in labs, several new features are activated:\n\n- The route `/subscribe/` will now render `subscribe.hbs` (provides there is not already a page at that route)\n- A new `{{subscribe_form}}` helper is registered for use within the theme\n- The API gets a new `/subscribers/` endpoint\n\nIt is possible to detect whether or not this feature has been enabled from within a theme, by using the new `{{:::at:::labs}}` helper, please see [@labs](doc:labs). \n\nThe subscribe page rendered at `/subscribe/` will appear using the default template, regardless of whether a theme is updated. However, in order to get the subscribe form to appear on a post, theme changes will be needed.\n\nIt is *highly* recommended that themes be updated to support the subscribe form on the post page, as Ghost will record which post a subscriber came from, and will be able to show stats in a later version.\n\n## The subscribe page\n\nThe subscribe page is intended as a new landing page for your blog, where users can go to subscribe. The page is also used to display error and success states for the subscribe form. Currently the subscribe feature is designed to be used with a simple oldschool form posting mechanism. We'll be introducing tools for making the form work nicely with Ajax in a future release.\n\nConditionally linking to the subscribe page, if it's available can be achieve like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#if @labs.subscribers}}\\n  <a class=\\\"subscribe-button\\\" href=\\\"[email protected]}}/subscribe/\\\">Subscribe</a>\\n{{/if}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n## The subscribe form helper\n\nUsage: `{{subscribe_form}}`\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Type\",\n    \"h-1\": \"Parameters\",\n    \"h-2\": \"Attributes\",\n    \"0-1\": \"n/a\",\n    \"0-0\": \"[Output](/docs/helpers#section-output), [Template-driven](/docs/helpers#section-template-driven), [Ghost](/docs/helpers#section-ghost)\",\n    \"0-2\": \"* `form_class` (string)\\n* `input_class` (string)\\n* `button_class` (string)\\n* `placeholder` (string)\\n* `autofocus` (boolean)\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n### Description\n\nThe `{{subscribe_form}}` helper wraps up all of the internals of the form used for submitting email addresses to subscribe. It contains a lot of hidden functionality, so it's not recommended to override the HTML for the form unless you really need to, as it may mean you miss out if we add extra behaviour in future!\n\nUnder the hood, `{{subscribe_form}}` is a  [template-driven](/docs/helpers#section-template-driven) helper just like [navigation](doc:navigation) and [pagination](doc:pagination), meaning that the HTML can be overridden by providing a correctly named partial. \n\n### Attributes\n\nThe `{{subscribe_form}}` will accept values for a number of attributes. The first few are used for adding classes to the form, to make it easier to style:\n\n* `form_class` - a class, or space-separated list of classes to apply to the form element\n* `input_class` - a class, or space-separated list of classes to apply to the email input element\n* `button_class` - a class, or space-separated list of classes to apply to the submit button\n\nThe last two are additional attributes that get passed down to the email input element:\n* `placeholder` - a string to display as the placeholder\n* `autofocus` - a boolean of whether the input should be autofocused - we recommend passing true here in the `subscribe.hbs` template, but not anywhere else in your theme.\n\n### Example Code\n\nHere's how the default `subscribe.hbs` page uses the helper (it uses all of the options):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{subscribe_form\\n  form_class=\\\"gh-signin\\\"\\n  input_class=\\\"gh-input\\\"\\n  button_class=\\\"btn btn-blue btn-block\\\"\\n  placeholder=\\\"Your email address\\\"\\n  autofocus=\\\"true\\\"\\n}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nNote that all the attributes should be wrapped in quotes, even the boolean! \n\nHere's how the default theme [Casper](https://github.com/TryGhost/Casper) includes the form at the bottom of the [post.hbs](https://github.com/TryGhost/Casper/blob/1.3.0/post.hbs) template:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" {{!-- Email subscribe form at the bottom of the page --}}\\n {{#if @labs.subscribers}}\\n   <section class=\\\"gh-subscribe\\\">\\n     <h3 class=\\\"gh-subscribe-title\\\">Subscribe to [email protected]}}</h3>\\n     <p>Get the latest posts delivered right to your inbox.</p>\\n     {{subscribe_form placeholder=\\\"Your email address\\\"}}\\n     <span class=\\\"gh-subscribe-rss\\\">or subscribe <a href=\\\"http:[email protected]}}/rss/\\\">via RSS</a> with Feedly!</span>\\n   </section>\\n {{/if}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nNote that this form does **not** pass `autofocus=\"true\"` as this would cause the page to scroll down to the form. \n\n*Documentation in progress ✨*\n\n### Default template\n\nThe default template for the `{{subscribe_form}}` helper, is shown below. This can be overridden by including a file called `subscribe_form.hbs` in your `partials/` directory. \n\nIf you're overriding this form, please be **very** careful! It's easy to miss something and break functionality, and you'll also need to check back regularly to make sure we haven't updated any of the functionality. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<form method=\\\"post\\\" action=\\\"{{action}}\\\" class=\\\"{{form_class}}\\\">\\n    {{! This is required for the form to work correctly }}\\n    {{hidden}}\\n\\n    <div class=\\\"form-group{{#if error}} error{{/if}}\\\">\\n        {{input_email class=input_class placeholder=placeholder value=email autofocus=autofocus}}\\n    </div>\\n    <button class=\\\"{{button_class}}\\\" type=\\\"submit\\\">Subscribe</button>\\n    {{! This is used to get extra info about where this subscriber came from }}\\n    {{script}}\\n</form>\\n\\n{{#if error}}\\n    <p class=\\\"main-error\\\">{{{error.message}}}</p>\\n{{/if}}\\n\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nThe `subscribe_form.hbs` template is passed a set of attributes which are all **required**:\n\n- `action` - the action for the form, e.g. where it needs to send its post data\n- `hidden` - a set of hidden fields which are needed for the form to behave properly\n- `script` - a small piece of JavaScript used for setting referrer information, so that Ghost can figure out where subscribers came from.\n\nIn order to make the form work, it MUST also include the line to output the email field:\n\n`{{input_email class=input_class placeholder=placeholder value=email autofocus=autofocus}}`\n\nThis template also gets provided the `{{error}}`, `{{success}}` and `{{email}}` fields provided to the `subscribe` page after the form is submitted. \n\n\n*Documentation in progress ✨*","excerpt":"Theme tools for collecting emails from your blog","slug":"subscribers","type":"basic","title":"Subscribers"}

Subscribers

Theme tools for collecting emails from your blog

[block:callout] { "type": "warning", "title": "Beta Feature", "body": "The subscribers feature is currently a Beta feature and is subject to heavy change over the coming months. We'll be trying not to break things, but be aware you may need to make theme updates to keep the feature working fully.\n\nTo enable this feature, visit yourblog.com/ghost/settings/labs/ and tick the 'Subscribers' checkbox." } [/block] *Documentation in progress ✨* When a user enables the "subscribers" feature in labs, several new features are activated: - The route `/subscribe/` will now render `subscribe.hbs` (provides there is not already a page at that route) - A new `{{subscribe_form}}` helper is registered for use within the theme - The API gets a new `/subscribers/` endpoint It is possible to detect whether or not this feature has been enabled from within a theme, by using the new [email protected]}}` helper, please see [@labs](doc:labs). The subscribe page rendered at `/subscribe/` will appear using the default template, regardless of whether a theme is updated. However, in order to get the subscribe form to appear on a post, theme changes will be needed. It is *highly* recommended that themes be updated to support the subscribe form on the post page, as Ghost will record which post a subscriber came from, and will be able to show stats in a later version. ## The subscribe page The subscribe page is intended as a new landing page for your blog, where users can go to subscribe. The page is also used to display error and success states for the subscribe form. Currently the subscribe feature is designed to be used with a simple oldschool form posting mechanism. We'll be introducing tools for making the form work nicely with Ajax in a future release. Conditionally linking to the subscribe page, if it's available can be achieve like this: [block:code] { "codes": [ { "code": "{{#if @labs.subscribers}}\n <a class=\"subscribe-button\" href=\"[email protected]}}/subscribe/\">Subscribe</a>\n{{/if}}", "language": "handlebars" } ] } [/block] ## The subscribe form helper Usage: `{{subscribe_form}}` [block:parameters] { "data": { "h-0": "Type", "h-1": "Parameters", "h-2": "Attributes", "0-1": "n/a", "0-0": "[Output](/docs/helpers#section-output), [Template-driven](/docs/helpers#section-template-driven), [Ghost](/docs/helpers#section-ghost)", "0-2": "* `form_class` (string)\n* `input_class` (string)\n* `button_class` (string)\n* `placeholder` (string)\n* `autofocus` (boolean)" }, "cols": 3, "rows": 1 } [/block] ### Description The `{{subscribe_form}}` helper wraps up all of the internals of the form used for submitting email addresses to subscribe. It contains a lot of hidden functionality, so it's not recommended to override the HTML for the form unless you really need to, as it may mean you miss out if we add extra behaviour in future! Under the hood, `{{subscribe_form}}` is a [template-driven](/docs/helpers#section-template-driven) helper just like [navigation](doc:navigation) and [pagination](doc:pagination), meaning that the HTML can be overridden by providing a correctly named partial. ### Attributes The `{{subscribe_form}}` will accept values for a number of attributes. The first few are used for adding classes to the form, to make it easier to style: * `form_class` - a class, or space-separated list of classes to apply to the form element * `input_class` - a class, or space-separated list of classes to apply to the email input element * `button_class` - a class, or space-separated list of classes to apply to the submit button The last two are additional attributes that get passed down to the email input element: * `placeholder` - a string to display as the placeholder * `autofocus` - a boolean of whether the input should be autofocused - we recommend passing true here in the `subscribe.hbs` template, but not anywhere else in your theme. ### Example Code Here's how the default `subscribe.hbs` page uses the helper (it uses all of the options): [block:code] { "codes": [ { "code": "{{subscribe_form\n form_class=\"gh-signin\"\n input_class=\"gh-input\"\n button_class=\"btn btn-blue btn-block\"\n placeholder=\"Your email address\"\n autofocus=\"true\"\n}}", "language": "handlebars" } ] } [/block] Note that all the attributes should be wrapped in quotes, even the boolean! Here's how the default theme [Casper](https://github.com/TryGhost/Casper) includes the form at the bottom of the [post.hbs](https://github.com/TryGhost/Casper/blob/1.3.0/post.hbs) template: [block:code] { "codes": [ { "code": " {{!-- Email subscribe form at the bottom of the page --}}\n {{#if @labs.subscribers}}\n <section class=\"gh-subscribe\">\n <h3 class=\"gh-subscribe-title\">Subscribe to [email protected]}}</h3>\n <p>Get the latest posts delivered right to your inbox.</p>\n {{subscribe_form placeholder=\"Your email address\"}}\n <span class=\"gh-subscribe-rss\">or subscribe <a href=\"http:[email protected]}}/rss/\">via RSS</a> with Feedly!</span>\n </section>\n {{/if}}", "language": "handlebars" } ] } [/block] Note that this form does **not** pass `autofocus="true"` as this would cause the page to scroll down to the form. *Documentation in progress ✨* ### Default template The default template for the `{{subscribe_form}}` helper, is shown below. This can be overridden by including a file called `subscribe_form.hbs` in your `partials/` directory. If you're overriding this form, please be **very** careful! It's easy to miss something and break functionality, and you'll also need to check back regularly to make sure we haven't updated any of the functionality. [block:code] { "codes": [ { "code": "<form method=\"post\" action=\"{{action}}\" class=\"{{form_class}}\">\n {{! This is required for the form to work correctly }}\n {{hidden}}\n\n <div class=\"form-group{{#if error}} error{{/if}}\">\n {{input_email class=input_class placeholder=placeholder value=email autofocus=autofocus}}\n </div>\n <button class=\"{{button_class}}\" type=\"submit\">Subscribe</button>\n {{! This is used to get extra info about where this subscriber came from }}\n {{script}}\n</form>\n\n{{#if error}}\n <p class=\"main-error\">{{{error.message}}}</p>\n{{/if}}\n", "language": "handlebars" } ] } [/block] The `subscribe_form.hbs` template is passed a set of attributes which are all **required**: - `action` - the action for the form, e.g. where it needs to send its post data - `hidden` - a set of hidden fields which are needed for the form to behave properly - `script` - a small piece of JavaScript used for setting referrer information, so that Ghost can figure out where subscribers came from. In order to make the form work, it MUST also include the line to output the email field: `{{input_email class=input_class placeholder=placeholder value=email autofocus=autofocus}}` This template also gets provided the `{{error}}`, `{{success}}` and `{{email}}` fields provided to the `subscribe` page after the form is submitted. *Documentation in progress ✨*