Building your first Iridium application (manually)

For this manual getting started guide, we'll be creating and launching a basic administrator panel with a list, edit, and create screen for a single resource type. We've chosen to use an Appointment model with an array driver. Meaning we'll store, create, edit, list, etc. our appointments from an in-memory array.

Before you begin

If you'd prefer to skip a lot of manual steps please use our cli.

Additionally, this example application is avaliable here: https://github.com/iridiumgo/iridium-example. Feel free to clone and run it yourself.

Our full featured demo is also avaliable here: a. Feel free to clone and run it yourself.

1. Create a new Iridium package

Create a new go package in your application to store your iridium files

mkdir iridium

Then create a new directory for your panels, and a file for your admin panel.

# in root directory.
# Create a new panel directory & admin_panel go file
mkdir iridium/panels
touch iridium/panels/admin_panel.go

See more on panels here

Then in your admin_panel.go file paste the following code:

// admin_panel.go

func NewAdminPanel(mux *http.ServeMux) *panel.Panel {
	return panel.NewPanel(mux).
		ID("admin").
		Path("admin").
		Resources(
            /* Will register your first resource here */
        ).
		RootMiddleware(
			middleware.SetPanel,
		).
		PanelMiddleware(
			middleware.Spa,
			middleware.ErrorPages,
		)
}

We'll be attaching a resource we're about to create later so Iridium can register it.

2. Create a resource

A resource is a collection of CRUD endpoints for a single model type.

For example, we'll be using an Appointment model stored inside our models directory for the remainder of this tutorial. You, naturally, would use your own model(s).

Appointment example model

// models/appointment.go
package models

type Appointment struct {
    ID        uint
    Name      string 
    Date      time.Time
}

Now, create a resources directory.

# in root directory.
mkdir iridium/resources/

Then create a new directory and file for your chosen resource.

mkdir iridium/resources/user/
touch iridium/resources/user/user_resource.go

3. Generate your resource type aliases

Inside your user_resource.go file, paste the following command to generate your resource's type aliases at the top of your file:

//go:generate go run github.com/iridiumgo/iridium/cmd/alias -group=resource -type=<Your model name> -source=<path to model file> -driver=array

Example of valid generation command

//go:generate go run github.com/iridiumgo/iridium/cmd/alias -group=resource -type=Appointment -source=./models/appointment.go -driver=array

Then run that command. You should see a file called user_resource_iridium.go generated in your resources/user directory. You can ignore this file for now - it contains the generated type aliases and does not need to be edited.

4. Create a basic driver

In order to create a basic resource driven off an array driver, we'll need to create a new in-memory array with some example data and then register a driver for it.

INFO

In your actual application, you'd likely want to source this data from elsewhere, or use a gorm driver to connect to a database. For this example, we're just defining an array with some sample data next to our resource definition to make the initial walkthrough easier.

// resources/user/user_resource.go
package user

myAppointments := []models.Appointment{
    {ID: 1, Name: "Appointment 1", Date: time.Now()},
    {ID: 2, Name: "Appointment 2", Date: time.Now()},
}

After creating a new in-memory array of Appointments, we'll create a basic driver for it.

// resources/user/user_resource.go
package user

myAppointments := []models.Appointment{
    {ID: 1, Name: "Appointment 1", Date: time.Now()},
    {ID: 2, Name: "Appointment 2", Date: time.Now()},
} 

// Create a function that returns an array driver for our in-memory array.
func getDriver() driver.IDriver[models.Appointment] {
    return arraydriver.NewArrayDriver[models.Appointment](&myAppointments)
}

5. Create a new resource

Now that we have a driver, we can create a method that returns a new resource instance.

// resources/user/user_resource.go
package user

func GetAppointmentResource() AppointmentResource {
	return Resource("Jobs"). // Create a resource
		Driver(getDriver()) // Register the driver for this resource.
}

6. Create a new form

Now that we have a basic resource setup, we can create a method that returns a new form definition for our resource.

// resources/user/user_resource.go
package user

// Create a form definition for our resource.
// Our form will have two fields:
// - Name: A Name field to store data in the appointment's Name property
// - Date: A Date field to store data in the appointment's Date property
func GetAppointmentForm() *form.FormDefinitionResolvable[models.Job] {
    return Form(getDriver()).
        Schema(
            FormInput("Name"),
            FormTime("Date"),
        )
}

You can read more about forms here.

7. Create a new table

We can also create a method that returns a new table definition for our resource. This allows us to list all our records in a table.

// resources/user/user_resource.go
package user

func GetAppointmentTable() *table.TableDefinitionResolvable[models.Job] {
    return Table(getDriver()).
        Columns(
            TextColumn("Name"),
            TextColumn("Date"),
        )
}

You can read more about tables here.

8. Create your pages

Iridium's type alias file also provides some methods to quickly create common pages for your resource.

Below, we'll add a create, edit, view, and list page for our resource. To do this, go back to the function that defines your resource and add the following lines:

// resources/user/user_resource.go
package user

func GetAppointmentResource() AppointmentResource {
	return Resource("Jobs"). 
		Driver(getDriver()).
		Pages(
		    // List page needs your GetAppointmentTable() method passed in
			ListPage(GetAppointmentTable()),
			
			// Create, view, and edit pages need 
			// your GetAppointmentForm() method passed in
			CreatePage(GetAppointmentForm()),
			ViewPage(GetAppointmentForm()),
			EditPage(GetAppointmentForm()),
		)
}

9. Register your resource

Go back to your admin_panel.go and register your new resource.

// iridium/panels/admin_panel.go
// ...
        Resources(
            resources.GetAppointmentResource(), // Register here <---
        ).
// ...

10. Launch your application

Finally, find your main.go file and add in the following lines to create a new Iridium application and register your panel.

You'll need to create a mux and pass it into your panel's NewAdminPanel method as show below.

// main.go
package main

import (
    "net/http"
    "my-app/iridium/panels"
)

func main() {
   mux := http.NewServeMux()

   iridium.NewIridiumApp().
        RegisterPanels(
            panels.NewAdminPanel(mux),
        ).
        Serve(mux)
}

Now run your app!

go run main.go

Visit http://localhost:3333/admin to see your new panel!

Next steps

Now that you've created your first Iridium panel, you can begin exploring the rest of the Iridium documentation to learn more about the features available.