@travetto/email-inky/README.md

Email Inky templating module

<!-- This file was generated by @travetto/doc and should not be modified directly -->
<!-- Please modify https://github.com/travetto/travetto/tree/main/module/email-inky/DOC.tsx and execute "npx trv doc" to rebuild -->
# Email Inky Templates

## Email Inky templating module

**Install: @travetto/email-inky**
```bash
npm install @travetto/email-inky

# or

yarn add @travetto/email-inky
```

This module provides [inky](https://github.com/zurb/inky) support via [JSX](https://en.wikipedia.org/wiki/JSX_(JavaScript)) tags for integration with the [Email Compilation Support](https://github.com/travetto/travetto/tree/main/module/email-compiler#readme "Email compiling module") engine.

**Code: Sample Inky Template**
```typescript
/** @jsxImportSource @travetto/email-inky */

import { Title, Container, Summary, Row, Column, If, Button, Value, InkyTemplate } from '@travetto/email-inky';

export default <InkyTemplate>
  <Title>Test Email</Title>
  <Summary>Email Summary</Summary>
  <Container>
    <If attr='person'>
      <Row>
        <Column small={5}>
          <Button href='https://google.com/{{query}}'>Hello <Value attr='name' /></Button>
        </Column>
      </Row>
    </If>
  </Container>
</InkyTemplate>;
```

Please see the [inky](https://github.com/zurb/inky) documentation for more information on the [component specifications](#https-get-foundation-emails-docs-inky-html)

## Conditionals and Substitutions
The underlying [Email](https://github.com/travetto/travetto/tree/main/module/email#readme "Email transmission module.") module is built on [mustache](https://github.com/janl/mustache.js/), which provides enough flexibility to enable sufficient power with minimal complexity and overhead.

This means this module, while showing [inky](https://github.com/zurb/inky) components, will ultimately produce HTML/markdown that is [mustache](https://github.com/janl/mustache.js/) compatible. The syntax used by [mustache](https://github.com/janl/mustache.js/) and the syntax used by [JSX](https://en.wikipedia.org/wiki/JSX_(JavaScript)) are in conflict due to both of the tools relying on the uniqueness of `{}` brackets.

To that end, the module introduces additional components ([If Component](https://github.com/travetto/travetto/tree/main/module/email-inky/src/components.ts#L27), [Unless Component](https://github.com/travetto/travetto/tree/main/module/email-inky/src/components.ts#L29), and [For Component](https://github.com/travetto/travetto/tree/main/module/email-inky/src/components.ts#L30)) to assist with control flow logic.  When it comes to variable substitution, and a desire to intermingle seamlessly with component properties, `{{value}}` can be used within a string value. To leverage substitutions outside of string contexts, a more formal version can be found in the [Value Component](https://github.com/travetto/travetto/tree/main/module/email-inky/src/components.ts#L28) component, but this cannot be integrated into properties (e.g. an href).

## Template Extension Points
The template extension points are defined at:
   1. `email/main.scss` - The entry point for adding, and overriding any [sass](https://github.com/sass/dart-sass)
   1. `email/inky.variables.scss` - Allows for specifying any variables that should be defined before [inky](https://github.com/zurb/inky)'s styles are loaded.
   1. `email/inky.wrapper.html` - Provides direct access to override the entire base HTML document for all HTML emails.
In addition to the overrides, you can find the list of available settings at [Github](https://github.com/foundation/foundation-emails/blob/develop/scss/settings/_settings.scss)