Go - ButterCMS Docs

Overview

This integration guide shows you how to how to update your existing project to:

install the ButterCMS package
instantiate ButterCMS
create components to fetch and display each of the three ButterCMS content types: Pages, Collections, and Blog Posts.

In order for the snippets to work, you’ll need to setup your dashboard content schemas inside of ButterCMS first.

Starter project

Or, you can jump directly to the starter project below, which will allow you to clone, install, run, and deploy a fully working starter project that’s integrated with content already inside of your ButterCMS account.

Go Starter Project

Hit the ground running with a pre-configured Go + ButterCMS setup.

Installation

go get github.com/buttercms/buttercms-go

Set your API token as an environment variable:

export BUTTERCMS_API_TOKEN=your_api_token

Initialize the Client

Standard Library
Gin Framework

// main.go
package main

import (
    "os"
    "github.com/buttercms/buttercms-go"
)

func init() {
    ButterCMS.SetAuthToken(os.Getenv("BUTTERCMS_API_TOKEN"))
}

// main.go
package main

import (
    "os"
    "github.com/buttercms/buttercms-go"
    "github.com/gin-gonic/gin"
)

func init() {
    ButterCMS.SetAuthToken(os.Getenv("BUTTERCMS_API_TOKEN"))
}

func main() {
    r := gin.Default()
    r.LoadHTMLGlob("templates/*")
    // Routes defined below
    r.Run(":8080")
}

For complete SDK documentation including all available methods and configuration options, see the Go SDK Reference.

Pages

ButterCMS Dashboard Setup

Create a Page Type:

Go to Content Types → Page Types → Click +
Add fields to your schema:
- Short Text field named headline
- Long Text field named subheadline
- Media field named hero_image
- WYSIWYG field named body
Click Create Page Type and name it Landing Page (slug: landing_page)

Create a Page:

Go to Pages → New Page → Select Landing Page
Enter a title (e.g., “Home”) which generates slug home
Fill in your content and click Publish

Standard Library
Gin Framework

// handlers/pages.go
package handlers

import (
    "html/template"
    "net/http"
    "github.com/buttercms/buttercms-go"
)

var templates = template.Must(template.ParseGlob("templates/*.html"))

func LandingPageHandler(w http.ResponseWriter, r *http.Request) {
    slug := r.URL.Query().Get("slug")
    if slug == "" {
        slug = "home"
    }

    params := map[string]string{
        "locale": "en",
    }

    page, err := ButterCMS.GetPage("landing_page", slug, params)
    if err != nil {
        http.Error(w, "Page not found", http.StatusNotFound)
        return
    }

    templates.ExecuteTemplate(w, "landing.html", page)
}

// main.go
func main() {
    http.HandleFunc("/", handlers.LandingPageHandler)
    http.HandleFunc("/page/", handlers.LandingPageHandler)
    http.ListenAndServe(":8080", nil)
}

// handlers/pages.go
package handlers

import (
    "net/http"
    "github.com/buttercms/buttercms-go"
    "github.com/gin-gonic/gin"
)

func LandingPage(c *gin.Context) {
    slug := c.Param("slug")
    if slug == "" {
        slug = "home"
    }

    params := map[string]string{
        "locale": "en",
    }

    page, err := ButterCMS.GetPage("landing_page", slug, params)
    if err != nil {
        c.HTML(http.StatusNotFound, "404.html", nil)
        return
    }

    c.HTML(http.StatusOK, "landing.html", page)
}

// main.go
r.GET("/", handlers.LandingPage)
r.GET("/page/:slug", handlers.LandingPage)

<!-- templates/landing.html -->
<!DOCTYPE html>
<html>
<head>
    <title>{{.Data.Fields.headline}}</title>
</head>
<body>
    <main>
        <h1>{{.Data.Fields.headline}}</h1>
        <p>{{.Data.Fields.subheadline}}</p>
        {{if .Data.Fields.hero_image}}
        <img src="{{.Data.Fields.hero_image}}" alt="{{.Data.Fields.headline}}" />
        {{end}}
        {{.Data.Fields.body | safeHTML}}
    </main>
</body>
</html>

Collections

ButterCMS Dashboard Setup

Create a Collection:

Go to Content Types → Collections → Click +
Add fields to your schema:
- Short Text field named name
- Media field named logo
- WYSIWYG field named description
Click Create Collection and name it Brands (key: brands)

Add Collection Items:

After saving, the create item screen loads automatically
Fill in your brand details and click Save
Add more items via Collections → hover Brands → click +

Standard Library
Gin Framework

// handlers/brands.go
func BrandsHandler(w http.ResponseWriter, r *http.Request) {
    content, err := ButterCMS.GetContentFields([]string{"brands"}, nil)
    if err != nil {
        http.Error(w, "Error fetching brands", http.StatusInternalServerError)
        return
    }

    templates.ExecuteTemplate(w, "brands.html", content)
}

// handlers/brands.go
func Brands(c *gin.Context) {
    content, err := ButterCMS.GetContentFields([]string{"brands"}, nil)
    if err != nil {
        c.HTML(http.StatusInternalServerError, "error.html", nil)
        return
    }

    c.HTML(http.StatusOK, "brands.html", content)
}

<!-- templates/brands.html -->
<!DOCTYPE html>
<html>
<body>
    <main>
        <h1>Our Brands</h1>
        <ul>
            {{range .Data.brands}}
            <li>
                <img src="{{.logo}}" alt="{{.name}}" />
                <h2>{{.name}}</h2>
                {{.description | safeHTML}}
            </li>
            {{end}}
        </ul>
    </main>
</body>
</html>

Dynamic Components

ButterCMS Dashboard Setup

Create Components:

Go to Content Types → Components → Click +
Create a Hero component with fields:
- headline (Short Text)
- subheadline (Long Text)
- image (Media)
- button_label (Short Text)
- button_url (Short Text)
Create additional components (Features, Testimonials, CTA, etc.)

Add Component Picker to Page Type:

Edit your Page Type schema
Add a Component field named body
Select which components can be used in this field
Content editors can now drag-and-drop components when creating pages

Component Renderer

// components/renderer.go
package components

import (
    "bytes"
    "html/template"
)

var componentTemplates = template.Must(template.ParseGlob("templates/components/*.html"))

type Component struct {
    Type   string                 `json:"type"`
    Fields map[string]interface{} `json:"fields"`
}

func RenderComponents(components []Component) template.HTML {
    var buf bytes.Buffer

    for _, comp := range components {
        templateName := comp.Type + ".html"
        if err := componentTemplates.ExecuteTemplate(&buf, templateName, comp.Fields); err != nil {
            continue // Skip unknown components
        }
    }

    return template.HTML(buf.String())
}

Component Template

<!-- templates/components/hero.html -->
<section class="hero">
    <h1>{{.headline}}</h1>
    <p>{{.subheadline}}</p>
    {{if .button_label}}
    <a href="{{.button_url}}" class="btn">{{.button_label}}</a>
    {{end}}
    {{if .image}}
    <img src="{{.image}}" alt="{{.headline}}" />
    {{end}}
</section>

Using in Handlers

// handlers/component_page.go
func ComponentPageHandler(w http.ResponseWriter, r *http.Request) {
    slug := r.URL.Path[len("/landing/"):]

    page, err := ButterCMS.GetPage("component_page", slug, nil)
    if err != nil {
        http.Error(w, "Page not found", http.StatusNotFound)
        return
    }

    // Extract components from page body
    bodyComponents := page.Data.Fields["body"].([]interface{})
    var comps []components.Component
    for _, c := range bodyComponents {
        comp := c.(map[string]interface{})
        comps = append(comps, components.Component{
            Type:   comp["type"].(string),
            Fields: comp["fields"].(map[string]interface{}),
        })
    }

    data := map[string]interface{}{
        "page":       page,
        "components": components.RenderComponents(comps),
    }

    templates.ExecuteTemplate(w, "component-page.html", data)
}

Blog

ButterCMS Dashboard Setup

ButterCMS includes a pre-built blog engine with posts, authors, categories, and tags.Create a Blog Post:

Go to Blog Posts → New Post
Enter a title, body content using the rich text editor
Optionally add a featured image, categories, tags, and author
Click Publish

The blog engine automatically provides:

Post slugs, summaries, and SEO fields
Author profiles with bio and social links
Categories and tags for organization
RSS and Atom feeds

Blog Post List
Single Blog Post

Standard Library
Gin Framework

// handlers/blog.go
func BlogListHandler(w http.ResponseWriter, r *http.Request) {
    page := r.URL.Query().Get("page")
    if page == "" {
        page = "1"
    }

    params := map[string]string{
        "page":      page,
        "page_size": "10",
    }

    posts, err := ButterCMS.GetPosts(params)
    if err != nil {
        http.Error(w, "Error fetching posts", http.StatusInternalServerError)
        return
    }

    templates.ExecuteTemplate(w, "blog-list.html", posts)
}

// handlers/blog.go
func BlogList(c *gin.Context) {
    params := map[string]string{
        "page":      c.DefaultQuery("page", "1"),
        "page_size": "10",
    }

    posts, err := ButterCMS.GetPosts(params)
    if err != nil {
        c.HTML(http.StatusInternalServerError, "error.html", nil)
        return
    }

    c.HTML(http.StatusOK, "blog-list.html", posts)
}

<!-- templates/blog-list.html -->
<!DOCTYPE html>
<html>
<body>
    <h1>Blog</h1>
    <ul>
        {{range .Data}}
        <li>
            <h2><a href="/blog/{{.Slug}}">{{.Title}}</a></h2>
            <p>{{.Summary}}</p>
            <span>By {{.Author.FirstName}} {{.Author.LastName}}</span>
        </li>
        {{end}}
    </ul>
    {{if .Meta.NextPage}}
    <a href="/blog?page={{.Meta.NextPage}}">Next Page</a>
    {{end}}
</body>
</html>

Standard Library
Gin Framework

// handlers/blog.go
func BlogPostHandler(w http.ResponseWriter, r *http.Request) {
    slug := r.URL.Path[len("/blog/"):]

    post, err := ButterCMS.GetPost(slug)
    if err != nil {
        http.Error(w, "Post not found", http.StatusNotFound)
        return
    }

    templates.ExecuteTemplate(w, "blog-post.html", post)
}

// handlers/blog.go
func BlogPost(c *gin.Context) {
    slug := c.Param("slug")

    post, err := ButterCMS.GetPost(slug)
    if err != nil {
        c.HTML(http.StatusNotFound, "404.html", nil)
        return
    }

    c.HTML(http.StatusOK, "blog-post.html", post)
}

<!-- templates/blog-post.html -->
<!DOCTYPE html>
<html>
<body>
    <article>
        <h1>{{.Data.Title}}</h1>
        <p>By {{.Data.Author.FirstName}} {{.Data.Author.LastName}}</p>
        {{if .Data.FeaturedImage}}
        <img src="{{.Data.FeaturedImage}}" alt="{{.Data.Title}}" />
        {{end}}
        {{.Data.Body | safeHTML}}
        <a href="/blog">Back to Posts</a>
    </article>
</body>
</html>

Caching

Use an in-memory cache for better performance:

// cache/cache.go
package cache

import (
    "sync"
    "time"
)

type CacheEntry struct {
    Data      interface{}
    ExpiresAt time.Time
}

type Cache struct {
    entries map[string]CacheEntry
    mu      sync.RWMutex
    ttl     time.Duration
}

func New(ttl time.Duration) *Cache {
    return &Cache{
        entries: make(map[string]CacheEntry),
        ttl:     ttl,
    }
}

func (c *Cache) Get(key string) (interface{}, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()

    entry, ok := c.entries[key]
    if !ok || time.Now().After(entry.ExpiresAt) {
        return nil, false
    }
    return entry.Data, true
}

func (c *Cache) Set(key string, data interface{}) {
    c.mu.Lock()
    defer c.mu.Unlock()

    c.entries[key] = CacheEntry{
        Data:      data,
        ExpiresAt: time.Now().Add(c.ttl),
    }
}

func (c *Cache) Invalidate(pattern string) {
    c.mu.Lock()
    defer c.mu.Unlock()

    for key := range c.entries {
        if strings.Contains(key, pattern) {
            delete(c.entries, key)
        }
    }
}

SEO

// handlers/pages.go
type SEOData struct {
    Title       string
    Description string
    OGTitle     string
    OGImage     string
}

func extractSEO(page *ButterCMS.PageResponse) SEOData {
    fields := page.Data.Fields
    seo := fields["seo"].(map[string]interface{})

    return SEOData{
        Title:       getStringOr(seo, "title", fields["headline"].(string)),
        Description: getStringOr(seo, "description", ""),
        OGTitle:     getStringOr(seo, "og_title", getStringOr(seo, "title", "")),
        OGImage:     getStringOr(seo, "og_image", ""),
    }
}

func getStringOr(m map[string]interface{}, key, fallback string) string {
    if v, ok := m[key].(string); ok {
        return v
    }
    return fallback
}

Resources

Go Starter

Pre-configured starter project

Go SDK

Complete SDK reference

GitHub Repository

View source code

Content API

REST API documentation

​Overview

​Starter project

Go Starter Project

​Installation

​Initialize the Client

​Pages

​Collections

​Dynamic Components

​Component Renderer

​Component Template

​Using in Handlers

​Blog

​Caching

​SEO

​Resources

Go Starter

Go SDK

GitHub Repository

Content API

Overview

Starter project

Installation

Initialize the Client

Pages

Collections

Dynamic Components

Component Renderer

Component Template

Using in Handlers

Blog

Caching

SEO

Resources