Getting Started

If you're just getting started with CustomBlocks.io, this is where to start.

Syntax - Building Blocks

CustomBlocks works with a very simple syntax, which is described here. (Where is no-code?)

It's very similar to Mustache, but with additional logic for building dynamic elements and connecting to Notion.

Basic Text

If you create a new block, you get the following:

{{#block bg-gray-200 p-5 m-5 text-black rounded-xl font-light text-center }}
    Hi there! 😊
    Just start write a simple template
{{/block}}

{{#link "https://docs.customblocks.io" "bg-indigo-500 text-white flex justify-center p-3 m-5 rounded-xl text-center font-semibold duration-200 hover:bg-indigo-400"}}
	Check out the docs
{{/link}}

1
2
3
4
5
6
7
8

As you can see, you can just write text, like you're used to in Notion. All text will just be displayed as plain text and each line will be a paragraph. What #block and #link means in this context is described below in 'Elements'

Connecting to Notion

If you want to connect a Notion resource, you can use the 'Connect Page' and 'Connect Database' buttons in the Editor. If you connect any resource from Notion, it will look like this:

{{!-- Connecting a Database --}}
>> connect.db ea30cdd6-aaa7-e4ef-b17d-d922862863a9 as Invoices

{{!-- Connecting a Page --}}
>> connect.page ea30cdd6-aaa7-e4ef-b17d-d922862863a9 as Invoice

1
2
3
4
5

You can also write this manually, if you want to.

Using Notion Resources

You can all use imported resources with the following syntax: {{ Page.PropertyName }}.

For example, if you have a Notion page called "Invoice", with the parameters "Title", "Amount" and "Customer", you can write something like:

>> connect.page ea30cdd6-aaa7-e4ef-b17d-d922862863a9 as Invoice

This is our invoice {{Invoice.Title}} with our customer {{Invoice.Customer}} 
and the Amount of {{Invoice.Amount}} dollar.

1
2
3
4

This will translate to for example:

This is our invoice #2021055 with our customer Chris
and the Amount of 451 dollar.

1
2

Styling

You can style your blocks with tailwindcss

Within #block-elements you can add your "styling" as tailwindcss-classes.

{{#block bg-gray-200 p-5 m-5 text-black rounded-xl font-light text-center }}
    Hi there! 😊
    Just start writing some simple code
{{/block}}

1
2
3
4

We prepared some simple classes for you, if you're just starting out:

{{#block card }}
    Hi there! 😊
    I'm a fancy card
{{/block}}

{{#link "https://customblocks.io" button }}
    I'm a fancy button
{{/link}}

{{#block card list text-center}}
    {{#block p-2}} List Item 1 {{/block}}
    {{#block p-2}} List Item 2 {{/block}}
    {{#block p-2}} List Item 3 {{/block}}
{{/block}}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

All styling gets realtime generated by the tailwindcss-jit-compiler. Thanks to @BeyondCode for it's awesome project Tailwinds JIT compiler via CDN, which made this feature possible.

Elements / Controlls

Just Text

You can even use no element at all, and just write some text


Hi, I'm just a little text, floating around in this vast universe.

1
2
3

Block

A #block-element is a block you can style with tailwindcss classes.

{{#block bg-gray-200 p-5 m-5 text-black rounded-xl font-light text-center }}
    Hi there! 😊
    Just start writing some simple code
{{/block}}

1
2
3
4

Link

A #link-element can direct to any external link and you can add Notion urls as well.

>> connect.page xxxx-xxxx-xxxxxxxx-xxxx-xxxx as InvoiceX

{{!-- External Link to https://customblocks.io --}}
{{#link "https://customblocks.io" }}
    I'm a fancy link
{{/link}}

{{!-- Link to Notion page of InvoiceX --}}
{{#link InvoiceX._url}}
    Url to InvoiceX
{{/link}}

1
2
3
4
5
6
7
8
9
10
11
12

If

You can create basic if-constructs:

>> connect.page xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoice

{{!-- Prints list of Invoice-Titles --}}
{{#if Invoice.Sum > 500}}
    This invoices sum is bigger than 500.
{{/if}}

1
2
3
4
5
6
7
8

Each

A #each-element iterates through your database elements

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- Prints list of Invoice-Titles --}}
{{#each Invoices as Invoice}}
    {{Invoice.Title}}
{{/each}}

1
2
3
4
5
6
7

There is also a shortcut for iterating, which you can use like this:

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- Prints list of Invoice-Titles --}}
{{#Invoices}}
    {{Title}}
{{/Invoices}}

1
2
3
4
5
6
7

Nesting ability of Elements

You can nest all elements within your block. No limitation to your creativity.

{{#link "https://customblocks.io" }}
    {{#block button }}
        Awesome button to CustomBlocks
    {{/block}}
{{/link}}

1
2
3
4
5

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- Prints links to each Invoice in a simple grid --}}
{{#block grid gap-3 m-10}}
    {{#each Invoices as Invoice}}
        {{#link Invoice._url "button"}}
            Link to {{Invoice.Title}}
        {{/link}}
    {{/each}}
{{/block}}

1
2
3
4
5
6
7
8
9
10
11

Using Notion Databases and Pages

You can use all your Notion resources you have connected through the Notion API.

With our powerfull syntax you can easily filter and display your data from Notion.

Import Notion Database

Usually you don't have to connect Notion databases manually. Simply press 'Connect to Notion' within the CustomBlocks Editor, to connect to a

To use your database information from Notion within CustomBlocks, you can simply import it like this at the top of a block:

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

>> connect.db indicates, that you want to import a Notion database.
xxxx-xxxx-xxxxxxxx-xxxx-xxxx is the uuid of the Notion database, which you can always find within your Notion url: https://www.notion.so/notionname/2e1fd1df41454182ba1ced9215fbf94e
as Invoices indicates you want this name for this database. Usually you use the same name, which you have used for your database.

Import Notion Page

Also the Notion pages don't have to be connected manually.

To display your page propertis, you can simply import it like this at the top of a block:

>> connect.page xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoice

>> connect.page indicates, that you want to import a Notion page.
xxxx-xxxx-xxxxxxxx-xxxx-xxxx is the uuid of the Notion page, which you can always find within your Notion url: https://www.notion.so/notionname/2e1fd1df41454182ba1ced9215fbf94e
as Invoice indicates you want this name for this database. Usually you use the same name, which you have used for your page.

Filter Notion Databases

You can always filter your imported Notion databases. Simply write a straighforward formular, what you want to filter:

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- Amount of items within the database 'Invoices' --}}
@count(Invoices)

{{!-- Show all Invoice Numbers, which are paid --}}
{{#each Invoices(Paid == ✅) as InvoiceItem}}
    {{InvoiceItem.Nr}}
{{/each}}

{{!-- Show all Invoice Numbers, which have a total of over 4000 --}}
{{#each Invoices(Total > 4000) as InvoiceItem}}
    {{InvoiceItem.Nr}}
{{/each}}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Display Data as JSON

If you want to display the current data - to check for certain properties - you can just put your variable within brackets and the whole data will be displayed as JSON:

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- All Invoice data will be displayed as JSON --}}
{{Invoices}}

1
2
3
4
5

Commands

Commands can be used to create complex elements or helpfull information.

Commands usually start with @.

@sum

With the command @sum(...) you can get the amount of items within the selected database.

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- Display the sum of the total of all the invoices --}}
@sum(Invoices.Total)

1
2
3
4
5

@group

With the command @group(...) you can group your database based on a property. All other properties will be summarized based on the selected grouping property.

For example, if you have customers for your invoices, you can sum up the total of all customers with the following statement:

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- Group Invoices by the propert 'Customer' and summarize them into 'GroupedInvoices' --}}
@group(Invoices by Customer as GroupedInvoices)

{{!-- Iterate through grouped invoices--}}
{{#each GroupedInvoices as Item}}

    {{!-- Display the summarized total of all invoices for each customer. --}}
    Total of Customer '{{Item.Customer}}': {{Item.Total}}

{{/each}}

1
2
3
4
5
6
7
8
9
10
11
12
13

@count

With the command @count(...) you can get the amount of items within the selected database.

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- Amount of items within the database 'Invoices' --}}
@count(Invoices)

{{!-- Amount of items within the database 'Invoices', which are paid --}}
@count(Invoices(Paid == ✅))

{{!-- Amount of items within the database 'Invoices', which have a total over 2000 --}}
@count(Invoices(Total > 2000))

1
2
3
4
5
6
7
8
9
10
11

@chart

This allows you create your own charts, based on imported Notion databases.

The syntax is:

@chart(<type>, <database>, <title-property>, <number-property>)

Height, chart color and text color are optional parameters (full examples):

@chart(<type>, <database>, <title-property>, <number-property>, <height[default:400]>, <chart-color[default:black]>, <text-color[default:lightgray]>)

>> connect.db xxxx-xxxx-xxxxxxxx-xxxx-xxxx as Invoices

{{!-- Bar Chart of the 'Sum' of each Invoice with 'Title' as Label --}}
@chart(bar, Invoices, Title, Sum)

{{!-- Line Chart of the 'Sum' of each Invoice with 'CustomerName' as Label --}}
@chart(line, Invoices, CustomerName, Sum)

1
2
3
4
5
6
7
8

@html and @endhtml

Those two commands indicate the parser you can use simple html within them.

@html

<div class="float-left">Hi, this is some html floating around 🥁💤</div>
<a href="https://customblocks.io">Links are possible</a>

<button>❌</button>
<svg>❌</svg>

@endhtml

1
2
3
4
5
6
7
8
9
10

WARNING

This is still very experimental and does not allow some critical elements, like 'svg' and 'button'. Please use with care.

Roadmap

Operations with variables

We're already working on operations within variables.

No-code features

No-code features are already planned out and will be implemented in the next few releases.

The plan is to enable more non-developers to create their own blocks easily in Version 2.0 of CustomBlocks.

# Getting Started

# Syntax - Building Blocks

# Basic Text

# Connecting to Notion

# Using Notion Resources

# Styling

# Elements / Controlls

# Just Text

# Block

# Link

# If

# Each

# Nesting ability of Elements

# Using Notion Databases and Pages

# Import Notion Database

# Import Notion Page

# Filter Notion Databases

# Display Data as JSON

# Commands

# @sum

# @group

# @count

# @chart

# @html and @endhtml

# Roadmap

# Operations with variables

# No-code features

Getting Started

Syntax - Building Blocks

Basic Text

Connecting to Notion

Using Notion Resources

Styling

Elements / Controlls

Just Text

Block

Link

If

Each

Nesting ability of Elements

Using Notion Databases and Pages

Import Notion Database

Import Notion Page

Filter Notion Databases

Display Data as JSON

Commands

@sum

@group

@count

@chart

@html and @endhtml

Roadmap

Operations with variables

No-code features