Quick Start

Get up and running with MaterialSB in minutes.

TL;DR

  1. Download the latest version of MaterialSB here
  2. You can immediately start playing with the 6 examples
  3. When building your own application, import the LocalFiles folder at the root of your project
  4. Include MaterialSB.sbi and call MaterialSB::Download(@YourCallback())

Prerequisites

Before you begin, make sure you have:

  • SpiderBasic 3.x or later installed
  • A modern web browser (Chrome, Firefox, Edge, Safari)
  • Basic familiarity with SpiderBasic syntax

Setup

MaterialSB consists of two components:

  • MaterialSB.sbi — The main include file containing all MaterialSB procedures
  • LocalFiles/ — A folder containing the MaterializeCSS framework (CSS, JS, and icon fonts)

The LocalFiles folder must be placed in your application's Resource directory so that SpiderBasic can bundle it with your compiled application.

info Tip: In the SpiderBasic IDE, go to Compiler → Compiler Options → Resource directory to set your resource folder.

Directory Structure

Here's the recommended project structure:

MyProject/
├── MyApp.sb              ; Your main SpiderBasic source file
├── MaterialSB/
│   └── MaterialSB.sbi    ; The MaterialSB include file
└── Resources/            ; Your resource directory
    └── LocalFiles/
        ├── CSS/
        │   ├── materialize.min.css
        │   └── material-icons.css
        └── JS/
            └── materialize.min.js

You can also place MaterialSB.sbi directly in your project folder or any location you prefer — just adjust the IncludeFile path accordingly.

Your First Application

Let's create a simple "Hello World" application to verify everything is working:

; HelloWorld.sb
IncludeFile "MaterialSB.sbi"

Procedure OnButtonClick()
  MaterialSB::Toast("Button clicked!", 3000)
EndProcedure

Procedure Main(Success)
  If Success
    ; Create a centered container
    MaterialSB::Row(MaterialSB::#Grid_Container)
      MaterialSB::Col(12)
        ; Add a header
        MaterialSB::Append(MaterialSB::Header("Hello, MaterialSB!", 2))
        
        ; Add a paragraph
        MaterialSB::Append(MaterialSB::Paragraph("Welcome to your first MaterialSB application."))
        
        ; Add a button
        MaterialSB::Button("Click Me", @OnButtonClick())
        
      MaterialSB::CloseCurrentParent()
    MaterialSB::CloseCurrentParent()
  Else
    Debug "Failed to load MaterialSB resources"
  EndIf
EndProcedure

; Initialize MaterialSB - this must be called first!
MaterialSB::Download(@Main())

Key points to understand:

  1. Download() loads the MaterializeCSS resources and calls your callback when ready
  2. Always check the Success parameter before building your UI
  3. Row() and Col() create a responsive grid layout
  4. CloseCurrentParent() is required after adding content to containers

Core Concepts

The Parent Stack

MaterialSB uses a parent stack to track where new elements should be added. When you create a container element (like Row(), Col(), or Card()), it becomes the current parent. You must call CloseCurrentParent() when you're done adding children:

MaterialSB::Row()                    ; Push Row to parent stack
  MaterialSB::Col(12, 6)             ; Push Col to parent stack
    MaterialSB::Button("Button 1", #Null)
    MaterialSB::Button("Button 2", #Null)
  MaterialSB::CloseCurrentParent()   ; Pop Col from stack
  MaterialSB::Col(12, 6)             ; Push another Col
    MaterialSB::Button("Button 3", #Null)
  MaterialSB::CloseCurrentParent()   ; Pop Col from stack
MaterialSB::CloseCurrentParent()     ; Pop Row from stack
Component Initialization

Some components require initialization after creation. These include:

  • Carousel — Call Init() after adding all items
  • Dropdown — Call Init() after adding all options
  • Modal — Call Init() before using ModalOpen()
  • Sidenav — Call Init() to enable opening/closing
; Example: Creating a dropdown
myDropdown = MaterialSB::Dropdown("Select an option")
MaterialSB::DropdownAddOption("Option 1", "1", myDropdown)
MaterialSB::DropdownAddOption("Option 2", "2", myDropdown)
MaterialSB::DropdownAddOption("Option 3", "3", myDropdown)
MaterialSB::Init(myDropdown, #Null)  ; Initialize after adding options
HTML Helpers

Functions like Paragraph(), Header(), and Link() return HTML strings rather than creating elements directly. Use Append() to add them to the current parent:

; These return strings, so use Append()
MaterialSB::Append(MaterialSB::Header("My Title", 3))
MaterialSB::Append(MaterialSB::Paragraph("Some text with a " + MaterialSB::Link("link", @OnClick()) + " inside."))

; These create elements directly, no Append() needed
MaterialSB::Button("Click", @OnClick())
MaterialSB::TextInput("Name")

Dark & Light Theme

MaterialSB enables dark theme by default. You can toggle between themes:

; Switch to light theme
MaterialSB::SetDarkTheme(#False)

; Switch to dark theme
MaterialSB::SetDarkTheme(#True)

; Check current theme
If MaterialSB::GetDarkThemeState()
  Debug "Dark theme is active"
Else
  Debug "Light theme is active"
EndIf

You can also create a theme toggle button:

Procedure ToggleTheme()
  MaterialSB::SetDarkTheme(Bool(Not MaterialSB::GetDarkThemeState()))
EndProcedure

MaterialSB::Button("Toggle Theme", @ToggleTheme())

Using Colors

MaterialSB provides color constants based on the Material Design palette. Use them to style your components:

; Colored text
MaterialSB::Append(MaterialSB::Paragraph("Error message", MaterialSB::#Color_Red))
MaterialSB::Append(MaterialSB::Paragraph("Success!", MaterialSB::#Color_Green))

; Colored toasts
MaterialSB::Toast("Warning!", 3000, MaterialSB::#Toast_Default, MaterialSB::#Color_Orange)

; Color modifiers for shades
myColor.s = MaterialSB::#Color_Blue + MaterialSB::#Color_Lighten_2  ; Light blue
myTextColor.s = MaterialSB::#Color_Teal + MaterialSB::#Color_Text   ; Teal text

See the Colors Reference for the complete list of available colors and modifiers.

Responsive Design

MaterialSB uses a 12-column responsive grid system. Specify different column widths for different screen sizes:

; Col(Small, Medium, Large, ExtraLarge)
; Small = mobile, Medium = tablet, Large = desktop, XL = wide desktop

MaterialSB::Row()
  ; Full width on mobile, half on tablet+
  MaterialSB::Col(12, 6)
    MaterialSB::Append(MaterialSB::Paragraph("Left column"))
  MaterialSB::CloseCurrentParent()
  
  ; Full width on mobile, half on tablet+
  MaterialSB::Col(12, 6)
    MaterialSB::Append(MaterialSB::Paragraph("Right column"))
  MaterialSB::CloseCurrentParent()
MaterialSB::CloseCurrentParent()

You can also use visibility classes to show/hide elements on specific screen sizes:

; Hide on small screens
MaterialSB::AddClass(myElement, MaterialSB::#Class_Hide_On_Small_Only)

; Show only on large screens
MaterialSB::AddClass(myElement, MaterialSB::#Class_Show_On_Large)