Building blocks provide a quick reference to how to achieve a specific single concern task. They are designed to be easily readable and light on content to allow the user to context switch between the documentation and their codebase without too much distraction. Below you'll find a typical structure of how a building block should be structured.
Examples of when a building block is appropriate
- How to send an SMS
- Making an outbound call
- Send verification code
- Get details about a phone number
- Buy a number
You can see examples of Building Blocks in the Voice API docs.
❎ Examples of when a building block is not appropriate
Two factor authentication
Although the components of this should be building blocks the subject in itself is too involved for a building block.
A building block is made of many moving parts, so below is a screenshot of an example building block, with the various elements labelled. More details on each element is below.
The introduction for a building block consists of the title, an opening paragraph about the topic, and then a section introducing the example that this block illustrates. All these elements are contained in the markdown file for the block.
The placeholder are also in the markdown file, these values are per-block and the same ones should be used by each language-specific code example.
The code snippets of the building blocks are available in a variety of programming languages to support developers from different communities. The tabbed content contains a tab for each per-language config file available at the path configured in the markdown file for each building block. If the file exists, then there will be a tab for it.
The setup steps are automatically generated from the information in the per-language config files. The renderer (
app/filters/building_block_filter.rb) creates these collapsible sections from the configuration supplied. The filename in the "Write the code" section and the command to "Run your code" are also controlled here.
The source code is actually snippets of code in the quickstart repos. These are external repositories that hold full working examples and we use sections of those examples to demonstrate the code. The source repository, file and range of lines to include are all defined in the per-language config files for each building block language example.
A user will want to see a demo of the code, so this section describes how to interact with or use the main feature of the building block. This should be the same for all the languages and is defined in the markdown file for each building block.
Finally, any additional links and resources may also be added to the markdown file for each building block.
This is the entry point that causes the building block to exist in the first place. It's a markdown file in the
building_blocks directory for the documentation section it applies to, with a path such as
It contains some basic front matter include the page title and navigation weight:
--- title: Quick howto on a simple thing navigation_weight: 5 ---
This file has the title, and some opening content about what the building block does or what it's for. Most users may have come from another part of the docs, such as a specific guide, but others may have landed here via search and will lack context.
The placeholders are also included here in the markdown file for the building block itself.
Within the building block markdown file, we define a "building block" - this is what renders everything inside the tabbed content block.
```building_blocks source: '_examples/concepts/sample-building-block' application: name: 'Example Application' ```
This block points to the directory that contains the per-language config files for the tabbed content block. The settings here are combined with the per-language config files, so it's possible to set common settings in this section.
For each of the tabs in the tabbed content block, the content is controlled entirely by a language-specific yaml file. This yaml file will be in the location specified by the
source field in the
building_blocks code sample, and will be named for the language it covers, such as
The options available in these config files combine to a very consistent output format across the building blocks. Here's an example from one of our voice applications.
--- title: Java language: java dependencies: - 'com.nexmo:client:4.0.0' code: source: .repos/nexmo-community/nexmo-java-quickstart/src/main/java/com/nexmo/quickstart/voice/TransferCall.java from_line: 42 to_line: 42 client: source: .repos/nexmo-community/nexmo-java-quickstart/src/main/java/com/nexmo/quickstart/voice/TransferCall.java from_line: 17 to_line: 22 run_command: java-ide file_name: TransferCall.java unindent: true
These options control everything from the pre-requisites and setup steps, to showing and running the code. Set as many or as few of these options as you need: only
code are vital.
||Displayed on the tab, usually the title-cased language name.|
||The language used, usually lowercase language name (NodeJS is spelled "node").|
||Set up the initial application setup instructions:
||If the block needs extra libraries, describe them here in a comma-separated list. This will be transformed into the "Install dependencies" collapsible block.|
||Configuration describing the code snippet to display:
||Configuration describing any setup required, such as setting up the appropriate library. See
||If the code samples have leading tabs, remove as many as make the included code not be indented.|
||Name of the file that the user should put the example code into, used in the copy on the page and closely related to `run_command.|
||How to run the example once the user created it. Probably related to
If the same value for an option applies to every language example, it can be set in the building block definition in the overall building block markdown file.
The code displayed within the tabbed examples belongs in external repositories; these are our "Quick Start" repositories on the Nexmo Community GitHub organisation. The directory structure follows that of the
_documentation directory on Nexmo Developer.
The examples on the Quick Start repositories should be self-contained and executable. In the building blocks, we only include the section(s) that are directly relevant to the task that the building block is intended to illustrate.