UI & Theming

This section details the navigation and theme properties within the blocklet.yml file. These properties are instrumental in defining a blocklet's contribution to the user interface, controlling how it appears in menus, and specifying its look and feel to ensure a cohesive user experience.

Proper configuration of these fields allows a blocklet to integrate seamlessly into a larger application, providing clear navigation paths for users and adhering to established visual guidelines.

The navigation property is an array of objects that defines the blocklet's user-facing menu structure. It allows you to specify navigation links that will be merged into the parent application's navigation, such as headers, footers, or dashboards. This system is composable, meaning a parent blocklet can reference a child component, and the child's navigation items will be intelligently integrated into the parent's structure.

Each item in the navigation array is an object that can contain the following fields:

id
string

A unique identifier for the navigation item. While optional, providing an id is best practice, especially for items that might be referenced or extended by other blocklets. The ID must conform to JavaScript variable naming rules.

title
string | object
required

The text displayed for the navigation item. This can be a simple string or an object for internationalization (i18n), where keys are locale codes (e.g., en, zh).

description
string | object

A tooltip or supplementary text for the navigation item. It also supports i18n in the same way as title.

link
string | object

The destination URL for the navigation item. This can be a relative path (e.g., /profile) which will be resolved against the blocklet's mount point, or an absolute URL (e.g., https://www.arcblock.io). It also supports i18n.

component
string

The name or DID of a child component blocklet. When specified, this navigation item acts as a container for the child's own navigation entries, which will be nested under it.

section
string | array

Specifies where the navigation item should appear in the UI. A single item can belong to multiple sections. Valid values include: header, footer, bottom, social, dashboard, sessionManager, userCenter, and bottomNavigation.

role
string | array

Defines roles that are permitted to see this navigation item, enabling role-based access control (RBAC) for the UI.

icon
string

An identifier for an icon to be displayed next to the navigation item's title.

visible
boolean
default:true

Controls the default visibility of the navigation item.

private
boolean
default:false

If true, this item will only be visible when a user is viewing their own profile or user center, not when viewing another user's.

items
array

An array of nested navigation item objects, allowing for the creation of dropdowns or sub-menus.

Example: Basic Navigation#

Here is an example of a navigation configuration that defines a main link to the blocklet's home page and an external link in the footer.

blocklet.yml

name: 'my-blocklet'
did: 'z8iZuf...s92'
version: '1.0.0'
title: 'My Blocklet'

interfaces:
  - type: 'web'
    name: 'publicUrl'
    path: '/'
    prefix: '*'
    port: 'BLOCKLET_PORT'

navigation:
  - title: 'Home'
    link: '/'
    section: 'header'
  - title:
      en: 'My Account'
      zh: '我的账户'
    link: '/profile'
    section: 'userCenter'
    role: ['guest', 'user']
    private: true
  - title: 'About Us'
    link: 'https://www.arcblock.io'

See all 2 lines

Example: Composable Navigation#

This example demonstrates how a parent blocklet can compose its navigation with a child component. The "Dashboard" entry will automatically pull in and nest the navigation items defined within the my-dashboard-component.

Parent Blocklet (blocklet.yml)

# ... (parent blocklet metadata)

components:
  - name: 'my-dashboard-component'
    source:
      store: 'https://store.arcblock.io/api'
      name: 'my-dashboard-component'

navigation:
  - title: 'Home'
    link: '/'
    section: 'header'
  - title: 'Dashboard'
    component: 'my-dashboard-component' # References the child component
    section: 'dashboard'

Child Component (my-dashboard-component/blocklet.yml)

# ... (child component metadata)

navigation:
  - title: 'Overview'
    link: '/overview'
  - title: 'Settings'
    link: '/settings'

The final, merged navigation structure would result in a "Dashboard" menu with "Overview" and "Settings" as sub-items.

Theming#

The theme property allows a blocklet to define basic visual styles, such as background colors or images, that can be applied by the host application. This ensures that the blocklet's UI aligns with the overall aesthetic.

Theme Properties#

background
string | object

Specifies the background for different UI areas. It can be a single string (URL or color value) to be used as a default, or an object to define backgrounds for specific sections.

3 subfields

Example: Theme Configuration#

This example sets a default background color and a specific image for the header.

blocklet.yml

name: 'my-themed-blocklet'
did: 'z8iZuf...s92'
version: '1.0.0'
title: 'My Themed Blocklet'

theme:
  background:
    default: '#F5F5F5'
    header: 'url(/assets/header-background.png)'
    footer: '#333333'

By leveraging the navigation and theme properties, developers can create blocklets that are not only functional but also deeply integrated into the end-user's application environment, providing a consistent and intuitive experience.

Composition (Components)
Monetization