{"_id":"588243725507a00f002f976f","user":"542979b61215fe08007e0ee4","__v":0,"category":{"_id":"5429898d1215fe08007e0fe6","pages":["5429ad872e366c080086b5c6","5429cb1b2e366c080086b777","542db0adcb19820800c1f4a3","54380c2df15a8e1400831f88","542aee7d54d88d140075ff00","542af02f54d88d140075ff14","542f14abacabcf080095953b","54651c6df42a472000b0c611","55f81b4f59eace0d0087db2b","56b0c5d81486990d009c101a","56babbffc275570d00ce7105"],"project":"542979c51215fe08007e0ee5","version":"542979c51215fe08007e0ee8","__v":10,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-09-29T16:32:13.661Z","from_sync":false,"order":1,"slug":"helpers","title":"Helpers"},"project":"542979c51215fe08007e0ee5","parentDoc":null,"version":{"_id":"542979c51215fe08007e0ee8","project":"542979c51215fe08007e0ee5","__v":4,"createdAt":"2014-09-29T15:24:53.437Z","releaseDate":"2014-09-29T15:24:53.437Z","categories":["542979c51215fe08007e0ee9","542985897a6b690800767fab","5429898d1215fe08007e0fe6","542ac5aa54d88d140075fcaf"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-20T17:05:54.843Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The `{background}` Helper provides consistent, reliable background images in modern email clients including most versions of Outlook (through VML).  The Helper is based on Campaign Monitor's [Bulletproof Background Images](https://backgrounds.cm/).  Inkcite's implementation makes it easy to customize its appearance (such as font family, size, weight and alignment) plus support for mobile-only overrides.\n\n## Usage\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{background src=image.jpg bgcolor=#999 width=600 height=250}\\n   The background image will apppear behind this content.\\n{/background}\",\n      \"language\": \"html\",\n      \"name\": \"source.html\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Note!\",\n  \"body\": \"If VML support is disabled in your Inkcite project, the Background Helper will not include the VML code necessary to support background images in Outlook 2007+.  VML support is enabled by default.\"\n}\n[/block]\n## Required Parameters\n\n#### `src`\nThe name of the image (in your project's `images/` directory) to display in the background.\n\n## Optional Parameters\n\n#### `align`\nThe horizontal alignment of the text and elements over the background.  Defaults to `left`, also accepts `center` and `right`.\n\n#### `bgcolor`\nThe fallback background color displayed when the email client has images disabled, specified in hex.\n\n#### `bggradient`\nWhen present and images are disabled, a radial gradient will be displayed in email clients that support CSS gradients.  The center of the radial gradient is the `bgcolor` and the edge will be the `bggradient` color.\n\n#### `border`\nOptional CSS border for the background image.  The Helper also supports individual `border-bottom`, `border-left`, `border-right` and `border-top`.\n\n#### `color`\nOptional hex color of the text, if any, displayed o.\n\n#### `font`\nThis Helpers supports all of the font-related attributes including `font`, `font-family`, `font-size`, `font-weight`, `letter-spacing` and `line-height`.  Refer to the [Fonts](doc:fonts) documentation for more information.\n\n#### `height`\nOptional height of the background image in pixels.  If unspecified, the background area stretches based on the size of the content within.\n\n#### `mobile-background-position`\nSpecifies the position of the background image on mobile devices.  Defaults to `center`, accepts all standard CSS background positions.\n\n#### `mobile-background-color` and `mobile-bgcolor`\nSpecifies an alternate background color on mobile devices. \n\n#### `mobile-background-repeat`\nSpecifies how the background image will repeat on mobile devices.  Defaults to `no-repeat`, also accepts `repeat`, `repeat-x` and `repeat-y`.\n\n#### `mobile-background-size`\nSpecifies how the background image sizes on mobile devices.  Defaults to `fill`, also accepts `cover`.\n\n#### `mobile-padding`\nSpecifies padding to be applied within the background image on mobile devices.  Specify either a pixel value or in CSS standard shortcut form - e.g. `2px 10px 0`.\n\n#### `mobile-src`\nSpecifies an alternate image to display in the background when the email is viewed on mobile devices where content may be taller than it is in the desktop version of the email.  This image should be fully qualified or located in your project's `images/` directory.\n\n#### `outlook-src`\nSpecifies an alternate image to display in versions of Outlook that support VML.  This image should be fully qualified or located in your project's `images/` directory.\n\n#### `valign`\nThe vertical alignment of the text within the contained space of the background image.  Defaults to `middle`, also accepts `top` and `bottom`.  Requires that `height` be provided.  Works in most email clients except Outlook where alternative methods (e.g. spacer images inside of `{outlook-only}` tags).\n\n#### `width`\nThe width of the background image in pixels.  If unspecified, the background image will fill the available space.  You can also pass `fill` or `100%` to achieve the same effect.","excerpt":"Bulletproof, responsive background images - even in Outlook.","slug":"background","type":"basic","title":"Background"}

Background

Bulletproof, responsive background images - even in Outlook.

The `{background}` Helper provides consistent, reliable background images in modern email clients including most versions of Outlook (through VML). The Helper is based on Campaign Monitor's [Bulletproof Background Images](https://backgrounds.cm/). Inkcite's implementation makes it easy to customize its appearance (such as font family, size, weight and alignment) plus support for mobile-only overrides. ## Usage [block:code] { "codes": [ { "code": "{background src=image.jpg bgcolor=#999 width=600 height=250}\n The background image will apppear behind this content.\n{/background}", "language": "html", "name": "source.html" } ] } [/block] [block:callout] { "type": "warning", "title": "Note!", "body": "If VML support is disabled in your Inkcite project, the Background Helper will not include the VML code necessary to support background images in Outlook 2007+. VML support is enabled by default." } [/block] ## Required Parameters #### `src` The name of the image (in your project's `images/` directory) to display in the background. ## Optional Parameters #### `align` The horizontal alignment of the text and elements over the background. Defaults to `left`, also accepts `center` and `right`. #### `bgcolor` The fallback background color displayed when the email client has images disabled, specified in hex. #### `bggradient` When present and images are disabled, a radial gradient will be displayed in email clients that support CSS gradients. The center of the radial gradient is the `bgcolor` and the edge will be the `bggradient` color. #### `border` Optional CSS border for the background image. The Helper also supports individual `border-bottom`, `border-left`, `border-right` and `border-top`. #### `color` Optional hex color of the text, if any, displayed o. #### `font` This Helpers supports all of the font-related attributes including `font`, `font-family`, `font-size`, `font-weight`, `letter-spacing` and `line-height`. Refer to the [Fonts](doc:fonts) documentation for more information. #### `height` Optional height of the background image in pixels. If unspecified, the background area stretches based on the size of the content within. #### `mobile-background-position` Specifies the position of the background image on mobile devices. Defaults to `center`, accepts all standard CSS background positions. #### `mobile-background-color` and `mobile-bgcolor` Specifies an alternate background color on mobile devices. #### `mobile-background-repeat` Specifies how the background image will repeat on mobile devices. Defaults to `no-repeat`, also accepts `repeat`, `repeat-x` and `repeat-y`. #### `mobile-background-size` Specifies how the background image sizes on mobile devices. Defaults to `fill`, also accepts `cover`. #### `mobile-padding` Specifies padding to be applied within the background image on mobile devices. Specify either a pixel value or in CSS standard shortcut form - e.g. `2px 10px 0`. #### `mobile-src` Specifies an alternate image to display in the background when the email is viewed on mobile devices where content may be taller than it is in the desktop version of the email. This image should be fully qualified or located in your project's `images/` directory. #### `outlook-src` Specifies an alternate image to display in versions of Outlook that support VML. This image should be fully qualified or located in your project's `images/` directory. #### `valign` The vertical alignment of the text within the contained space of the background image. Defaults to `middle`, also accepts `top` and `bottom`. Requires that `height` be provided. Works in most email clients except Outlook where alternative methods (e.g. spacer images inside of `{outlook-only}` tags). #### `width` The width of the background image in pixels. If unspecified, the background image will fill the available space. You can also pass `fill` or `100%` to achieve the same effect.