Skip to main content

Quick Start

Welcome to the Brick Next documentation! This page will give you an introduction to the 80% of Brick Next concepts that you will use on a daily basis.

For simplicity, in most examples on this page, we will use native HTML elements to build user interfaces with Brick Next.

However, the full potential of Brick Next will be realized only when combined with custom elements. We have provided a first-party brick library, containing lots of custom elements, with decent design, out of the box. There are also many free off-the-shelf third-party web components libraries, that can be easily integrated into Brick Next. Additionally, you can also create your own bricks.

Nesting bricks​

Storyboards are defined as declarative structural data, made out of bricks.

info

In most examples through our documentation, we will use YAML to define storyboards, since it has a minimal syntax, and is more human-readable at the same time, compared to JSON or others. But keep in mind that they are just structural data.

In the above example, we defined a page that is pretty the same as the following HTML:

<div>
  <h1>Welcome to my app</h1>
  <button>I'm a button</button>
</div>

Responding to events​

You can respond to events by declaring event handlers.

brick: button
properties:
  textContent: Click me
events:
  click:
    action: console.log
    args:
    - You clicked me

Displaying data​

Embed JavaScript expressions to display dynamic data.

brick: div
properties:
  textContent: <% CTX.user.name %>

Notice that the expressions have their own syntax highlighting through our documentation, but they are just strings.

Usually you should define some contexts to manage page states, and use expressions to bind the states to brick properties. You can also updating these states in response to events, thus the bound properties will be updated automatically once the states changed.

Notice that we use <%= %> instead of <% %> to enable binding mode.

Conditional rendering​

There are two ways to conditionally render bricks.

The first approach is to define a if field along with your brick.

- if: <% CTX.isAdmin %>
  brick: admin-panel
- if: <% !CTX.isAdmin %>
  brick: user-panel

The second one is to use a control node of :if. It is more convenient if your condition is complex or you have multiple bricks to render.

Specify the condition dataSource which is usually an expression, and define the bricks to render in children. If the condition is met, those children with an empty slot will be rendered, otherwise those children with slot of else will be rendered.

brick: ':if'
dataSource: <% FN.check('my', 'complex', 'expression') %>
children:
- brick: admin-panel-a
- brick: admin-panel-b
- brick: user-panel-x
  slot: else
- brick: user-panel-y
  slot: else

Rendering lists​

You can use a control node of :forEach to render lists of bricks.

Like the :if node, you should also specify a dataSource as well as children. For each item in the list (dataSource), the children will be rendered once. You can use ITEM in expressions inside the children, to access the current item of each loop.

Making templates​

You can make templates to encapsulate parts of your UI, and reuse them just like other bricks.

A template can have its own scoped states which is very similar with contexts. Template states can be internal states, or exposed as properties of the template.

Fetching data​

You can combine page states with remote HTTP APIs, and then bind these states with any brick properties.

You can also create your own provider bricks, which involves pro code, if you have complex logic to fetch and process data.

Next steps​

By now, you know the basics of how to write Brick Next storyboards!

Check out the Tutorial to put them into practice and build your first micro-app with Brick Next.