# Building Blocks with DML Dyspatch blocks are modular, responsive, customizable, and straightforward to build with Dyspatch Markup Language (DML). Once a block is created you can use it in the email builder to create emails quickly. ## Using DML to Build Blocks We built DML to make coding responsive email blocks fast and effortless. Design your block with structural DML tags like `` and add common email elements with DML tags like text ``, images ``, and buttons ``. You can also use DML to create dynamic blocks and add personalizations, like variables `@{variable_name}`. The blocks you build with DML will be available in the email builder and used to create new email. Emails created from blocks can then be exported from Dyspatch to any of our ESP direct integrations or to any of our supported export languages. ## Create a New Block There are two ways to create a new block. Creating a block [from the Blocks & Apps tab](#new-block-from-blocks--apps-tab) will require toggling on all themes you'd like to make the block available in. Creating a block [from the Themes tab](#new-block-from-themes-tab) will assign the Block to that theme automatically. ### New Block from Blocks & Apps Tab Select the **Blocks & Apps** tab from the left menu, click **Create** then **New Block**. ![Make a new block in the Block tab in Dyspatch](https://docs.dyspatch.io/img/emails/new-block.png) This block will need to be [manually added](/blocks_and_themes/styling_with_themes/#adding-blocks-to-themes) to your theme or themes before it can be used in an email. ### New Block from Themes Tab From the Themes tab, select the theme you'd like to use your new block in then click **Create > New Block**. ![Create a new block from the Themes tab in Dyspatch](https://docs.dyspatch.io/img/emails/new-block-from-themes.png) ### Duplicate a Block To make a new version of an existing block, duplicate the block from either the **Blocks & Apps** tab, or the **Themes** tab. Select **Duplicate** from the " 3 dot " menu icon for the block you'd like to duplicate. Either way, your block's theme assignment settings will follow to the new block. ![Duplicate a block in Dyspatch](https://docs.dyspatch.io/img/emails/duplicate-block-menu.png) ## Starting in the Block Editor A new block will already have the basic DML structure in the Block Editor. ![The block editor starting DML ready to go](https://docs.dyspatch.io/img/emails/build-blocks-block-editor.png) ### Style with Attributes Each DML tag has attributes for adding style to the element. Using the attributes available for a `` tag we can make the text larger, add color, and assign a font to customize the style of this element. ![The block editor with attributes added to the dys-text for styling](https://docs.dyspatch.io/img/emails/build-blocks-attributes.png) See the DML docs for all available attributes for each tag.
If your theme has <dys-attributes> set for your DML element, those will be applied to the element in the email. Any style attributes set on the element in the block will override theme-level attributes
### Make Content Editable Add an `editable` attribute with a unique name to allow email creators to customize the content in the email builder. ![The block editor with an editable attribute added to the dys-text](https://docs.dyspatch.io/img/emails/build-blocks-editable.png)
Each editable attribute requires a name that is unique to the block
The editable attribute is available for many DML and HTML elements, allowing you to control which content in the block will be available for customization in the email builder. For example, an editable attribute added to a `` tag will allow the src, alt text, title, and href to be editable in the email builder. When an editable attribute is added to an element, the content becomes placeholder text that will be visible and editable in the email builder. Without the editable attribute, the content saved in the block will be locked and unavailable for editing in the email builder. Find out more about [editable content here](/blocks_and_themes/using_editable/).
For dialing in editable control, see how to enable editable styles for blocks for a theme
## DML Templating Add personalization and templating logic to your block with DML. DML supports variables `@{variable_name}` and expressions, like if statements ``. Find out more about DML templating here. ![A variable and an if statement in the block editor](https://docs.dyspatch.io/img/emails/build-blocks-templating.png) The logic you add using DML can be exported to any of our ESP direct integrations or as any of our supported export languages, so you can use your Dyspatch emails in multiple email sending platforms. ### Sample Data Add test data on the **Data** tab to preview your block's variables and check your templating logic with the same kind of data you would use to send your emails. You can input and edit your sample data with the visual editor or the Code editor by toggling the icons next to *Custom Variables*. ![Data in the sample data tab in the block editor {'firstname':'Rowan','membership': true}](https://docs.dyspatch.io/img/emails/preview-data-both-views.png) See more on [Testing Your Email with Sample Data](/emails/testing_your_email_with_preview_data/).
Use Customer Profiles to store multiple scenarios and customer types throughout your organization
### Localizations Manage your [block-level localizations](/localization/block_localization/) on the **Localizations** tab. This is typically used for non-editable content that will be the same across all emails where the block is used. ![Localizing your block](https://docs.dyspatch.io/img/emails/build-blocks-localization.png) Check out our Knowledge Base to learn more about [localization in Dyspatch](/localization) and dig deeper into [Translating Blocks with Block Localization](/localization/block_localization/).
To prevent translated content from changing, DML elements can be localizable in the block, or editable in the email builder, but not both
## Add Block to Themes From the **Settings > Theme Assignment** tab in the block editor you can preview how your block will look in different themes as well as add your block to a theme by using the toggle on the right. ![The theme tab in the block editor shows which themes the block is in](https://docs.dyspatch.io/img/emails/build-blocks-theme.png)
A theme must be active on a block to use it in an email using that theme
## Accessing Block Revision History View, rename, and restore previous saved versions of your blocks from the block version history list. Access the list from the history icon next to the block name in the block builder ![Arrow pointing to history icon in the block builder](https://docs.dyspatch.io/img/emails/block-revision.png) ### Preview Previous Block Versions Click the saved version name from the list to view a read-only preview of the block's code and appearance. ![Block revision history list of previous versions with code and image preview on the right](https://docs.dyspatch.io/img/emails/block-revision-list.png)
Users with Editor permissions can only view revision history. Developers & Admins can view, rename, and restore revisions
### Rename Previous Block Versions To rename your revisions, select **Name this version** from the three-dot menu to the right of the version name. ![Block revision history list of previous versions with code and image preview on the right](https://docs.dyspatch.io/img/emails/block-revision-naming.png) ### Restore Previous Block Versions To restore a previous version of the block, select it from the list then click the **Restore this Version** button. ![Block revision history list with restored version title and restore this version button enabled](https://docs.dyspatch.io/img/emails/block-revision-restored.png) Restoring a block verion will create a new version that is appended to the version history list.
Restoring a block revision recovers all translated text
## Add a Figma Link to your Block If your team uses Figma as the single source of truth to keep designs consistent across all channels, like ours does, link to the Figma design file under **Settings > Block Details**. ![Block builder with a figma file attached and figma interactive screen](https://docs.dyspatch.io/img/emails/block-builder-figma.png) This will allow block builders to preview and interact with the design file directly in the block builder, matching pixels 1:1 and ensuring email design accuracy. ## Importing Blocks You can import one block into another to create a single source of truth for shared elements across your design system. When you update the source block, every block that imports it reflects the change on the next save. Use the **Import Block** button in the block editor to get started. For full details and DML syntax, see [Importing Blocks](/blocks_and_themes/importing_blocks/). ## Designing Your Email System For best practices on structuring blocks and themes for reuse — including naming conventions, blueprints, and how to use the Dyspatch Figma community file — see [Designing Your Emails for Dyspatch](/blocks_and_themes/designing_for_dyspatch/). ## Check out our DML documentation Head over to our DML docs to read more about DML and do some interactive learning in our DML Playground.
If you prefer fully guided interactive training then Dyspatch University is your next stop 🎓