Blue Jay | Go Toolkit for the Web

Blue Jay Overview

Mon, 01 Jan 0001 00:00:00 +0000

Blue Jay is a web toolkit for Go. It’s a collection of command-line tools and a web blueprint that allows you to easily structure your web application. There is no rigid framework to which you have to conform and the tools are easy to start using.

There are a few components:

Blueprint is a model-view-controller (MVC) style web skeleton.
Jay is a command line tool with find/replace, database migrations, and code generation.
Core is a collection of packages used by Blueprint and Jay that can also be used by other projects.

High Level

Blueprint is a web application with a built-in web server and MySQL integration. The application has a public home page, authenticated home page, login page, register page, about page, and a simple notepad to demonstrate GET, POST, PATCH, and DELETE operations.

The entrypoint for the web app is blueprint.go which uses the boot package to load the application settings, create the session store, connect to the database, set up the views, load the routes, attach the middleware, and then start the web server.

The front end is built using Bootstrap with a few small changes to fonts and spacing. The flash messages are customized so they show up at the bottom right corner of the screen. All of the error and warning messages should display to the user or in the console. Informational messages are displayed to the user via flash messages that disappear after 4 seconds.

Blueprint also works well with npm and Gulp. A Gulp script is included that automates the compiling of SASS, concatenation of JavaScript, generation of favicons, and copying of static assets like Bootstrap and jQuery (which are managed by npm) to the asset/static folder.

Jay is a command-line tool that pairs nicely with Blueprint. It has find/replace functionality to make code refactoring is a little easier. It performs database migration to easily update your database when sharing code between teams. Jay provides template-based code generation that allows you to build files like controllers, models, middleware, or even multiple views. All templates (*.gen files) are parsed using the text/template package from the Go standard library and all generation instructions (*.json files) allow you to specify which variables to pass via Jay as well as in which folder to create the templates. You can also build collections of templates to generate more than one file set which is great when you want to scaffold out a component with CRUD (create, read, update, and delete).

Quick Start Website with Jay

To download Blueprint, run the following command: go get github.com/blue-jay/blueprint
To download Jay, run the following command: go get github.com/blue-jay/jay
In your terminal, CD to the blueprint folder.
Run this command to create the env.json file from env.json.example: jay env make
Set the environment variable, JAYCONFIG, to the env.json file path. For example:
- On Windows: SET JAYCONFIG=C:\bluejay\workspace\src\github.com\blue-jay\blueprint\env.json
- On Linux/OS X: export JAYCONFIG=$HOME/workspace/src/github.com/blue-jay/blueprint/env.json
Start a MySQL instance.
Edit the MySQL section of env.json to match your database login information.
Create the database and tables using the command: jay migrate:mysql all
Run the application: go run blueprint.go
Open your web browser to http://localhost and you should see the welcome page.
Navigate to the register page at http://localhost/register and create a new user.
You can now login at http://localhost/login.

OS Specific Instructions

There are also more detailed guides available by operating system:

Quick Start Website without Jay

To download Blueprint, run the following command: go get github.com/blue-jay/blueprint
Start a MySQL instance.
Make a copy of env.json.example and name it: env.json
Edit the MySQL section in env.json so the connection information matches your MySQL instance.
In the Session section, you should generate new passwords for the following keys:
- AuthKey should be a 64 byte password and then base64 encoded
- EncryptKey should be a 32 byte password and then base64 encoded
- CSRFKey should be a 32 byte password and then base64 encoded
Create a database called blueprint in MySQL.
Import migration/mysql/20160630_020000.000000_init.up.sql to create the tables.
In your terminal, CD to the blueprint folder.
Run the application using the command: go run blueprint.go
Open your web browser to http://localhost and you should see the welcome page.
Navigate to the register page at http://localhost/register and create a new user.
You can now login at http://localhost/login.

Why Blue Jay?

After 300 stars on GitHub, I realized people really liked the boilerplate Model-View-Controller (MVC) web application in Go called gowebapp so I rewrote it with better documentation.

Go is a blast to code in and it’s great being part of a helpful community. Blue Jay provides a quickstart for developers with a lean web skeleton called Blueprint that demonstrates how to structure a web application with sample code.

One of the things you’ll notice while using Blueprint is how to abstract out external packages to make it easy to swap out components. Ultimately, you should be able to write code once and use it in all of your other projects. The lib folder is a great place for all these packages with very few dependencies.

You’ll also notice certain packages need to be thread-safe when building web applications. An example is the github.com/core/view package which provides thread-safe template caching.

The other reason for Blue Jay is the command-line tool, jay, which provides an easy way to find/replace in a project when refactoring, migrate your database forwards or backwards, and generate a file or sets or files using the Go html/template package. Code generation can help you build faster and more efficiently with less mistakes.

Why Go?

One of the big draws to Go is the rich standard library. The standard library includes a web server, web-safe templating, and many other tools necessary to build a web application. Any features missing from the standard library are written by other Go developers who are happy to contribute to the thriving community.

Go allows you to write code that compiles to the majority of the architectures we use today so all your code is pretty much portable. Go excels when you want to write command line apps instead of just scripts, but that’s not the only niche. The designers of Go wanted to build a language that solved problems between the Google development teams. It’s a modern language that allows you to easily multi-thread your applications. It’s a “get stuff done” language.

Screenshots

Public Home

About

Register

Authenticated Home

View All Notes

Add Note

View One Note

Edit Note

Feedback

All feedback is welcome. Let me know if you have any suggestions, questions, or criticisms. If something is not idiomatic to Go, please let me know know so we can make it better.

Structure

Mon, 01 Jan 0001 00:00:00 +0000

It helps to understand the folder structure so you know where each of the components lives.

Blueprint Structure

The project is organized into the following folders:

asset/
|----dynamic/    - private assets like SASS files, single JavaScript files, and logo.png for favicon generation
|----static/     - public assets like CSS, JavaScript, and favicon.ico for Android, Apple, etc
controller/      - packages with routes and application logic
filestorage/     - files uploaded from an HTML form
generate/          - template pairs (.gen and .json) for generating code using jay
lib/             - packages you'll build that are used by the application (recommended to build with minimum dependencies)
|----boot/       - package for registering services and setting up all the components
|----env/        - package that holds the structure for the application settings
|----flight/     - package with a context that can be used by controllers to access application settings
middleware/      - packages that return a http.Handler to wrap around routes for ACL, request logging, etc
migration/       - migration database files
|----mysql/      - MySQL files for migrating database up and down
model/             - packages with database queries and structs matching tables
view/            - HTML templates parsed using the Go html/template package
viewfunc/        - packages that return a template.FuncMap for use in views
viewmodify/      - packages that modify view prior to rendering to add varibles like CSRF token and auth level

The following files exist at the project root:

blueprint.go     - entrypoint for the application
env.json.example - application config template for variables
gulpfile.js      - Gulp configuration that compiles SASS, concatenates JavaScript, etc
package.json     - npm configuration that loads Gulp, Boostrap, Underscore.js, etc

Blueprint External Go Packages

There are a few external packages used in Blueprint:

github.com/gorilla/context              - registry for global request variables
github.com/gorilla/csrf                 - CSRF protection for gorilla sessions
github.com/gorilla/sessions             - cookie and filesystem sessions
github.com/go-sql-driver/mysql          - MySQL driver
github.com/husobee/vestigo              - HTTP router with wildcards
github.com/jmoiron/sqlx                 - MySQL general purpose extensions
github.com/justinas/alice               - middleware chaining
golang.org/x/crypto/bcrypt              - password hashing algorithm

Jay Structure

The project is simply a command-line interface for packages in the Core library https://github.com/blue-jay/core. The packages that Jay uses from the Core library are:

env/       - package that creates and updates the env.json config file
find/      - package that finds case-sensitive matched text in files
generate/  - package that generates code from template pairs
migrate/   - package that handles the database migrations
replace/   - package that replaces case-sensitive matched text in files

The following file exists at the project root of Jay:

jay.go     - entrypoint for the application

Jay External Go Packages

There is only one external packages used in Jay (not including the Core library):

gopkg.in/alecthomas/kingpin.v2    - command-line and flag parser

Core Structure

The Core project contains many packages that are all divided into individual folders. Each is well documented so the GoDoc page should provide enough information on each one.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

Throughout this documentation, keep in mind everything in Blueprint is configurable. You are not using a framework so don’t be afraid to change code. You don’t need to use any of the components included with Blueprint, but it does give you a nice foundation to start from. If you want to use YAML instead of JSON, it’s recommended to create a wrapper library in the lib folder and then load your env.yaml file via the blueprint.go file.

Jay Command: env

One of the first steps before using Blueprint is to create env.json. You can make a copy of env.json.example and then name it env.json, just be sure to generate a new AuthKey, EncryptKey, and CSRFKey in the Session section.

You can also use jay to create the env.json file with new session keys. Just CD to the blueprint folder and then run: jay env make

Here are the commands you can use with jay env:

# Create a new env.json file from env.json.example with newly generated session keys
jay env make

# Show a new set of session keys that can be copied and pasted into env.json
jay env keyshow

# Generate a new set of session keys and automatically apply them to env.json
env env keyupdate

The env.json file is a good place to set variables for the application so you don’t have to hardcode them. If you want to add any of your own settings, you can add them to env.json and update the Info struct in the lib/env package. Here is an example env.json:

{
	"Asset":{
		"Folder":"asset"
	},
	"Email":{
		"Username":"",
		"Password":"",
		"Hostname":"",
		"Port":25,
		"From":""
	},
	"Form":{
		"FileStorageFolder":"filestorage"
	},
	"Generation":{
		"TemplateFolder":"generate"
	},
	"MySQL":{
		"Username":"root",
		"Password":"",
		"Database":"blueprint",
		"Charset":"utf8mb4",
		"Collation":"utf8mb4_unicode_ci",
		"Hostname":"127.0.0.1",
		"Port":3306,
		"Parameter":"parseTime=true",
		"Migration":{
			"Folder":"migration/mysql",
			"Table":"migration_blueprint",
			"Extension":"sql"
		}
	},
	"Server":{
		"Hostname":"",
		"UseHTTP":true,
		"UseHTTPS":false,
		"RedirectToHTTPS":false,
		"HTTPPort":80,
		"HTTPSPort":443,
		"CertFile":"tls/server.crt",
		"KeyFile":"tls/server.key"
	},
	"Session":{
		"AuthKey":"PzCh6FNAB7/jhmlUQ0+25sjJ+WgcJeKR2bAOtnh9UnfVN+WJSBvY/YC80Rs+rbMtwfmSP4FUSxKPtpYKzKFqFA==",
		"EncryptKey":"3oTKCcKjDHMUlV+qur2Ve664SPpSuviyGQ/UqnroUD8=",
		"CSRFKey":"xULAGF5FcWvqHsXaovNFJYfgCt6pedRPROqNvsZjU18=",
		"Name":"sess",
		"Options":{
			"Path":"/",
			"Domain":"",
			"MaxAge":28800,
			"Secure":false,
			"HttpOnly":true
		}
	},
	"Template":{
		"Root":"base",
		"Children":[
			"partial/favicon",
			"partial/menu",
			"partial/footer"
		]
	},
	"View":{
		"BaseURI":"/",
		"Extension":"tmpl",
		"Folder":"view",
		"Caching":true
	}
}

Production

When you move your application to production, you should make the following changes:

Set Server.Hostname to the server
Set Server.UseHTTPS to true
Generate a certificate and key for HTTPS and place in the tls folder
Set Session.Secure to true

Configuration Structure

The env.json file contains the configuration for Blueprint and Jay. It removes the need to hardcode any of these values and makes it easy to move Blueprint to another system with a different setup. The env.json file is parsed to the Info struct from the lib/env package:

Source

// Info contains the application settings.
type Info struct {
  Asset      asset.Info    `json:"Asset"`
  Email      email.Info    `json:"Email"`
  Form       form.Info     `json:"Form"`
  Generation generate.Info `json:"Generation"`
  MySQL      mysql.Info    `json:"MySQL"`
  Server     server.Info   `json:"Server"`
  Session    session.Info  `json:"Session"`
  Template   view.Template `json:"Template"`
  View       view.Info     `json:"View"`
  path       string
}

The Info struct is a container that nests structs from packages in the Core library that need variables configured. The Path variable is the location of the env.json file. Here is a list mapping the JSON keys to structs:

Asset     - Info struct in core/asset
Email     - Info struct in core/email
Form      - Info struct in core/form
Generate  - Info struct in core/generate
MySQL     - Info struct in core/mysql
Server    - Info struct in core/server
Session   - Info struct in core/session
Template  - Template struct in core/view
View      - Info struct in core/view

Using Flight

The flight package provides access to the session variables, env.json settings, database connections, views, and general shortcuts. It’s mostly designed for controllers, but it can be used by other packages as well.

To use package, you would call the flight.Context() function like this:

// Index displays the items.
func Index(w http.ResponseWriter, r *http.Request) {
	c := flight.Context(w, r)

	items, _, err := note.ByUserID(c.DB, c.UserID)
	if err != nil {
		c.FlashError(err)
		items = []note.Item{}
	}

	v := c.View.New("note/index")
	v.Vars["items"] = items
	v.Render(w, r)
}

Flight needs a http.ResponseWriter and a http.Request so it can access the sessions variables and provide shortcuts for the following tasks:

reading URL parameters: c.Param(name string)
redirecting to a page: c.Redirect(urlStr string)
validation a form and sets a flash message: c.FormValid(fields …string)
repopulating a form: c.Repopulate(v map[string]interface{}, fields …string)
setting flash messages and then saving the session: c.FlashSuccess(message string)

Flight also provides access to the following:

configuration settings from env.json: c.Config.Asset.Folder
session: c.Sess.Values["email"]
current user ID: c.UserID
view package: c.View.New("home/index")
database connection: items, _, err := note.ByUserID(c.DB, c.UserID)

It is not a requirement to use the flight package, but it makes working with the different web components much easier. Feel free to modify the package to fit your needs. Just make sure it is thread-safe.

Enable HTTPS

To enable HTTPS:

Set UseHTTPS to true in the env.json file
Create a folder called tls in the project root folder
Place your own certificate and key files in the tls folder

Note: If you want to redirect HTTP to HTTPS, you can set RedirectToHTTPS to true in the env.json file as well.

Tip: Add a Section

To add a new key called Captcha, your workflow would consist of the following:

Create a new package in the lib folder called captcha
Create a struct called Info in the lib/captcha package
Add the struct to the Info struct in the lib/env package
Add the Captcha key and any values to the env.json file
Add code to the RegisterServices() function in the lib/boot package to pass the any additional settings to the lib/flight package at start up
Add code to your controllers that references uses flight.Context() to retrieve your lib/captcha package settings

Tip: Remove a Section

To remove the Email key, your workflow would consist of the following:

Remove the Email key and value from the env.json file
Remove the Email nested struct from the Info struct in the lib/env package
Remove any code setting up the package from the RegisterServices() function in the boot package
Remove the lib/email package from the filesystem
Find any references to the lib/email package in your code using the jay command line, jay find . "lib/email", then delete the imports and referencing code

Assets

Thu, 30 Jun 2016 21:07:13 +0100

Basic Usage

Out of the box, all of the static assets like CSS and JavaScript are ready to demo. If you want to make changes to the file, it’s best to use the tools provided. The asset folder contains a dynamic folder and a static folder.

The dynamic folder contains the Syntactically Awesome Style Sheets (SASS), individual JavaScript files, and a large PNG image which is used to generate favicons for different platforms like Android, iPhone, etc. This is the folder in which you want to make your changes. The dynamic folder holds some of the assets required to generate the assets in the static folder.

The static folder contains the minified CSS and JavaScript as well as the generated favicons. The static folder is designed to be served up so the files can be accessed like this:

<!-- Favicons -->
<link rel="apple-touch-icon" sizes="57x57" href="/static/favicon/apple-touch-icon-57x57.png?v1.0=3eepn6WlLO">
<link rel="apple-touch-icon" sizes="60x60" href="/static/favicon/apple-touch-icon-60x60.png?v1.0=3eepn6WlLO">
<link rel="apple-touch-icon" sizes="72x72" href="/static/favicon/apple-touch-icon-72x72.png?v1.0=3eepn6WlLO">
<!-- CSS and Fonts -->
<link media="all" rel="stylesheet" type="text/css" href="/static/css/bootstrap.min.css?1466973904" />
<link media="all" rel="stylesheet" type="text/css" href="//fonts.googleapis.com/css?family=Open+Sans:300,400,bold,italic" />
<link media="all" rel="stylesheet" type="text/css" href="/static/css/all.css?1466973904" />

Check out the Controllers and Views pages for how the files are served and how timestamps are append to them for cach management.

If you make changes to any of the files in the dynamic folder, you still need a way to compile/minify them and then move them to the static folder so we’ll use Gulp to do that.

Install npm

The Node Package Manager (npm) helps install packages that work with NodeJS. If you don’t have NodeJS and npm installed, you can install the latest version from https://nodejs.org.

Install Gulp and Dependencies

Once npm is installed, you can open your terminal and CD to the root of the project folder. You can then run these commands:

# Install Gulp globally
npm install -g gulp-cli

# Install Gulp locally and dependencies from package.json
npm install

Gulp

Once the environment is set up, you should have your terminal open to the root of the project folder. There are a couple commands you can use with Gulp that are in the gulpfile.js.

# Compile the SASS from asset/dynamic/sass and store CSS in asset/static/css/all.css
gulp sass

# Concat the JavaScript from asset/dynamic/js and store JS in asset/static/js/all.js
gulp javascript

# Copy the jQuery files from node_modules/jquery to asset/static/js
gulp jquery

# Copy the Bootstrap files from node_modules/bootstrap to asset/static
gulp bootstrap

# Copy the Underscore files from note_modules/underscore to asset/static/js
gulp underscore

# Run tasks favicon-generate and favicon-inject
gulp favicon

# Generate favicons from asset/dynamic/logo.png and copy to /asset/static/favicon
gulp favicon-generate

# Generate view/partial/favicon.tmpl with favicon tags
gulp favicon-inject

# Update the asset/dynamic/favicon/data.json file with the latest version from the RealFaviconGenerator website
gulp favicon-update

# Run the sass and javascript tasks when any of the files change
gulp watch

# Run all the tasks once
gulp init

# Run just the sass and javascript tasks once
gulp default

It is best to run gulp watch so when you are working with the SASS and JavaScript files so they will automatically generate in the static folder for you.

Routing

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

When a user requests a page from your application, the routes determine which page is shown. The route is a URL that is mapped to a controller function. To simplify the organization, the routes are stored in the controller files. The controller files are all organized under the controller folder.

Routing

In the boot package, the RegisterServices() function calls the controller.LoadRoutes() function. The LoadRoutes() function in the controller package loads the routes for each of the individual controllers:

// LoadRoutes loads the routes for each of the controllers.
func LoadRoutes() {
    about.Load()
    debug.Load()
    register.Load()
    login.Load()
    home.Load()
    static.Load()
    status.Load()
    notepad.Load()
}

Here is the Load() function from the controller/notepad package:

Source

// Package static serves static files like CSS, JavaScript, and images.
package static

import (
    "net/http"
    "os"
    "path"

    "github.com/blue-jay/blueprint/controller/status"
    "github.com/blue-jay/blueprint/lib/flight"

    "github.com/blue-jay/core/router"
)

// Load the routes.
func Load() {
    // Serve static files
    router.Get("/static/*filepath", Index)
}

// Index maps static files.
func Index(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)

    // File path
    path := path.Join(c.Config.Asset.Folder, r.URL.Path[1:])

    // Only serve files
    if fi, err := os.Stat(path); err == nil && !fi.IsDir() {
        http.ServeFile(w, r, path)
        return
    }

    status.Error404(w, r)
}

Error Pages

A few errors pages are already defined for you like the 404 (Page Not Found) and 405 (Method Not Allowed) pages.

Source

// Package status provides all the error pages like 404, 405, 500, 501,
// and the page when a CSRF token is invalid.
package status

import (
    "net/http"

    "github.com/blue-jay/blueprint/lib/flight"
    "github.com/blue-jay/core/router"
)

// Load the routes.
func Load() {
    router.MethodNotAllowed(Error405)
    router.NotFound(Error404)
}

// Error404 - Page Not Found.
func Error404(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)
    w.WriteHeader(http.StatusNotFound)
    v := c.View.New("status/index")
    v.Vars["title"] = "404 Not Found"
    v.Vars["message"] = "Page could not be found."
    v.Render(w, r)
}

// Error405 - Method Not Allowed.
func Error405(allowedMethods string) func(w http.ResponseWriter, r *http.Request) {
    return func(w http.ResponseWriter, r *http.Request) {
        c := flight.Context(w, r)
        w.WriteHeader(http.StatusMethodNotAllowed)
        v := c.View.New("status/index")
        v.Vars["title"] = "405 Method Not Allowed"
        v.Vars["message"] = "Method is not allowed."
        v.Render(w, r)
    }
}
...

Middleware

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

Middleware, in the context of Go, is applied during routing to provide features like request/response logging, access controls lists (ACLs), and header modification. Middleware is either applied to every request (like for request logging) or specified routes (like for ACLs).

There are a few pieces of middleware included. The package called csrf protects against Cross-Site Request Forgery attacks. The logrequest package will log every request made against the website to the console. The rest package allows the HTTP method to be changed during a form submission to DELETE or PATCH instead of POST.

Creating Middleware

An example of a piece of middleware that is applied to every request is middleware/logrequest. When a page is requested, the middleware will print to the console: the time of the request, remote IP address, HTTP method, and the URL requested.

Source

// Package logrequest provides an http.Handler that logs when a request is
// made to the application and lists the remote address, the HTTP method,
// and the URL.
package logrequest

import (
    "fmt"
    "net/http"
    "time"
)

// Handler will log the HTTP requests.
func Handler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        fmt.Println(time.Now().Format("2006-01-02 03:04:05 PM"), r.RemoteAddr, r.Method, r.URL)
        next.ServeHTTP(w, r)
    })
}

This is an example of the minimum code required for middleware:

// Handler
func Handler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Logic BEFORE the other handlers and function goes here
        next.ServeHTTP(w, r)
        // Logic AFTER the other handlers and function goes here
    })
}

Chaining

The more middleware you use, the more it stacks up like this and makes it hard to read:

return context.ClearHandler(rest.Handler(logrequest.Handler(setUpCSRF)))

Before justinas/alice, a workaround was to use a variable and reassign it multiple times like this:

h = setUpCSRF(h)
h = logrequest.Handler(h)
h = rest.Handler(h)
return context.ClearHandler(h)

You can see chaining in action in controller/notepad where the controller uses the router.ChainHandler() function. The function is a wrapper for the justinas/alice package which makes using middleware more scalable and a little “prettier”. If you look at the lib/boot package, you’ll see the ChainHandler() function. There is also a Chain() function that can be used to chain middleware for routes or to pass to ChainHandler().

// Apply middleware to routes individually
router.Get("/notepad", Index, acl.DisallowAnon, logrequest.Handler)
router.Get("/notepad/create", Create, acl.DisallowAnon, logrequest.Handler)

// Use Chain() to apply middleware
c := router.Chain(acl.DisallowAnon, logrequest.Handler)
router.Get("/notepad", Index, c...)
router.Get("/notepad/create", Create, c...)

// Pass Chain() to ChainHandler()
c := router.Chain( // Chain middleware, bottom runs first
    h,                    // Handler to wrap
    setUpCSRF,            // Prevent CSRF
    rest.Handler,         // Support changing HTTP method sent via query string
    logrequest.Handler,   // Log every request
    context.ClearHandler, // Prevent memory leak with gorilla.sessions
)
return router.ChainHandler(c...)

ChainHandler() accepts one or more of the http.Handler type and returns a http.Handler.

Chain() accepts one or more of the http.Handler type and returns an array of the alice.Constructor type.

Apply to Every Request

In blueprint.go, the application calls boot.SetUpMiddleware(router.Instance()) which applies the middleware to the router. The middleware is called on every request.

Source

// SetUpMiddleware contains the middleware that applies to every request.
func SetUpMiddleware(h http.Handler) http.Handler {
    return router.ChainHandler( // Chain middleware, top middlware runs first
        h,                    // Handler to wrap
        setUpCSRF,            // Prevent CSRF
        rest.Handler,         // Support changing HTTP method sent via query string
        logrequest.Handler,   // Log every request
        context.ClearHandler, // Prevent memory leak with gorilla.sessions
    )

Apply to Specific Routes

In controller/notepad, the application creates a chain of middleware and then applies it to only certain routes. In this scenario, the pages are only accessible if the user is authenticated.

Source

func Load() {
    // Add middleware that disallows anonymous access
    c := router.Chain(acl.DisallowAnon)

    // Map HTTP methods and URLs to functions wrapped in the middleware chain
    router.Get("/notepad", Index, c...)
    router.Get("/notepad/create", Create, c...)
    router.Post("/notepad", Store, c...)
    router.Get("/notepad/view/:id", Show, c...)
    router.Get("/notepad/edit/:id", Edit, c...)
    router.Patch("/notepad/edit/:id", Update, c...)
    router.Delete("/notepad/:id", Destroy, c...)
}

Controllers

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

The controller files are all organized under the controller folder. The controllers handle the interactions between the models and the views as well as specify which routes to map to which functions.

It’s a good idea to follow a naming convention for the different pieces. Laravel developers will notice it’s very similar, but with a few changes.

Method	Path	Function	View
GET	/notepad	Index	index.tmpl
GET	/notepad/create	Create	create.tmpl
POST	/notepad/create	Store
GET	/notepad/view/:id	Show	show.tmpl
GET	/notepad/edit/:id	Edit	edit.tmpl
PATCH	/notepad/edit/:id	Update
DELETE	/notepad/:id	Destroy

Here is a controller that follows the naming convention. Notice the model name (note) matches the view folder (note/index). The model does not need to match the controller because you’ll be working with many different models in your controllers.

func Load() {
	...
	// "Get" is the Method
	// "/notepad" is the Path
	router.Get("/notepad", Index, acl.DisallowAnon)
	...
}

// Index displays the items.
func Index(w http.ResponseWriter, r *http.Request) {
	c := flight.Context(w, r)

	items, _, err := note.ByUserID(c.DB, c.UserID)
	if err != nil {
		c.FlashError(err)
		items = []note.Item{}
	}

	v := c.View.New("note/index")
	v.Vars["items"] = items
	v.Render(w, r)
}

Access a Session

Sessions provide access to flash messages as well as variables that are set at login. You must remember to save the sessions once you make a change to them.

// Get the current session
sess, _ := session.Instance(r)
...
// Save the session after you are finished making changes
sess.Save(r, w)

Trigger Flash Message

Flash messages will appear to the user on next page load. They only display once. The built-in messages are tied to Bootstrap classes:

flash.Success is green (alert-success)
flash.Warning is yellow (alert-warning)
flash.Notice is blue (alert-info)
flash.Error is red (alert-danger)

sess.AddFlash(flash.Info{"Welcome to Blueprint!", flash.Success})
sess.Save(r, w) // Ensure you save the session after making a change to it

Validate a Form

The form package makes it easy to validate required fields. It works on the inputs: text, textarea, checkbox, radio, and select. The function, form.Required(), requires the request and then any number of fields as it is a variadic function. You can use the form package by itself it you want more control over the error message or you can use the flight package which handles the error message for you:

// Without flight
if valid, missingField := form.Required(r, "email", "password"); !valid {
	sess.AddFlash(flash.Info{"Field missing: " + missingField, flash.Error})
	sess.Save(r, w)
	LoginGET(w, r)
	return
}

// With flight
c := flight.Context(w, r)
if !c.FormValid("name", "email", "password") {
	Create(w, r)
	return
}

Repopulate Form Fields

The form package can also repopulate the form fields after a submission that is missing information. It is also a variadic function so it can accepts more than one field. You’ll need to use blocks from the form package in your view as well. Check out the Views page to see how to use them.

// Without flight
c := flight.Context(w, r)
v := c.View.New("note/create")
form.Repopulate(r.Form, v.Vars, "name")
v.Render(w, r)

// With flight
c := flight.Context(w, r)
v := c.View.New("note/create")
c.Repopulate(v.Vars, "name")
v.Render(w, r)

Render a Template

You can render a template a few ways (check out the Views page for more clarification):

// Render without adding any variables
c := flight.Context(w, r)
c.View.New("about/index").Render(w, r)

// Render with variables
c := flight.Context(w, r)
v := c.View.New("home/index")
v.Vars["first_name"] = c.Sess.Values["first_name"]
v.Render(w, r)

// Render with different base template (base.tmpl is used by default)
c := flight.Context(w, r)
v := c.View.New("home/index").Base("single")
v.Render(w, r)

Return Flash over Ajax

If you’re using Ajax to retrieve content, you can also retrieve the flash messages this way so they can be displayed without refreshing the page. There is JavaScript that is already designed to show a Flash message and it’s called: ShowFlash(). You’ll just need to make a call to the page and then pass the output to ShowFlash(). The code is below.

Code for the controller:

// Load the routes.
func Load() {
	router.Get("/flashes", Index)
}

// Index displays the flash messages in JSON.
func Index(w http.ResponseWriter, r *http.Request) {
	c := flight.Context(w, r)

	// Set the flash message
	c.Sess.AddFlash(flash.Info{"An error occurred on the server. Please try again later.", flash.Error})
	c.Sess.Save(r, w)

	// Display the flash messages as JSON
	flash.SendFlashes(w, r)
}

Code in JavaScript:

$.get("/flashes", function(data) {
	showFlash(data);
});

Interact with a Model

The models contain all the SQL code so the controllers just call the model functions to interact with the data.

// Get database result
result, norows, err := user.ByEmail(email)

if nowrows {
	// User does not exist
} else if err != nil {
	// Display error message
} else if passhash.MatchString(result.Password, password) {
	// Password matches!
} else {
	// Password does not match
}

Send an Email

There is also a simple package that sends emails once the SMTP settings in env.json point to your SMTP server.

// Email a user
c := flight.Context(w, r)
err := c.Config.Email.Send("This is the subject", "This is the body!")
if err != nil {
	c.FlashError(err)
	return
}

Models

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

It’s a good idea to abstract the database layer out so if you need to make changes, you don’t have to look through the controllers to find the queries. All the queries are stored in the model folder.

Blue Jay supports MySQL by default, but can easily be expanded to use other database systems. There is also a PostgreSQL package you can use here. The instructions are at the bottom of this page.

Connect to the database

You only need to connect to the database once. The connection pool is handled by the go-sql-driver/mysql package. The connection is started by the lib/boot package:

Source

// Connect to the MySQL database
mysqlDB, _ := config.MySQL.Connect(true)

Model Layout

Every model should have a table name, a struct to represent the columns, and a Connection interface. The interface makes the model much more testable so it can be easily mocked and interchanged.

A good interface for each model looks like this:

// Connection is an interface for making queries.
type Connection interface {
    Exec(query string, args ...interface{}) (sql.Result, error)
    Get(dest interface{}, query string, args ...interface{}) error
    Select(dest interface{}, query string, args ...interface{}) error
}

And a good create function looks like this:

// Create adds an item.
func Create(db Connection, name string, userID string) (sql.Result, error) {
    result, err := db.Exec(fmt.Sprintf(`
        INSERT INTO %v
        (name, user_id)
        VALUES
        (?,?)
        `, table),
        name, userID)
    return result, err
}

CRUD Operations

Below are common operations and how controllers can interact with models. All the controller functions are from notepad.go and the model functions are from note.go.

Create an Item

Use db.Exec() to create an item or a table.

Controller

// Store handles the create form submission.
func Store(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)

    if !c.FormValid("name") {
        Create(w, r)
        return
    }

    _, err := note.Create(c.DB, r.FormValue("name"), c.UserID)
    if err != nil {
        c.FlashError(err)
        Create(w, r)
        return
    }

    c.FlashSuccess("Item added.")
    c.Redirect(uri)
}

Model

// Create adds an item.
func Create(db Connection, name string, userID string) (sql.Result, error) {
    result, err := db.Exec(fmt.Sprintf(`
        INSERT INTO %v
        (name, user_id)
        VALUES
        (?,?)
        `, table),
        name, userID)
    return result, err
}

Get an Item by Item ID

Use db.Get() to get a single item.

Controller

// Show displays a single item.
func Show(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)

    item, _, err := note.ByID(c.DB, c.Param("id"), c.UserID)
    if err != nil {
        c.FlashError(err)
        c.Redirect(uri)
        return
    }

    v := c.View.New("note/show")
    v.Vars["item"] = item
    v.Render(w, r)
}

Model

// ByID gets item by ID.
func ByID(db Connection, ID string, userID string) (Item, bool, error) {
    result := Item{}
    err := db.Get(&result, fmt.Sprintf(`
        SELECT id, name, user_id, created_at, updated_at, deleted_at
        FROM %v
        WHERE id = ?
            AND user_id = ?
            AND deleted_at IS NULL
        LIMIT 1
        `, table),
        ID, userID)
    return result, err == sql.ErrNoRows, err
}

Get Items by User ID

Use db.Select() to get multiple items.

Controller

// Index displays the items.
func Index(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)

    items, _, err := note.ByUserID(c.DB, c.UserID)
    if err != nil {
        c.FlashError(err)
        items = []note.Item{}
    }

    v := c.View.New("note/index")
    v.Vars["items"] = items
    v.Render(w, r)
}

Model

// ByUserID gets all entities for a user.
func ByUserID(db Connection, userID string) ([]Item, bool, error) {
    var result []Item
    err := db.Select(&result, fmt.Sprintf(`
        SELECT id, name, user_id, created_at, updated_at, deleted_at
        FROM %v
        WHERE user_id = ?
            AND deleted_at IS NULL
        `, table),
        userID)
    return result, err == sql.ErrNoRows, err
}

Update an Item

Use db.Exec() to update one or more items.

Controller

// Update handles the edit form submission.
func Update(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)

    if !c.FormValid("name") {
        Edit(w, r)
        return
    }

    _, err := note.Update(c.DB, r.FormValue("name"), c.Param("id"), c.UserID)
    if err != nil {
        c.FlashError(err)
        Edit(w, r)
        return
    }

    c.FlashSuccess("Item updated.")
    c.Redirect(uri)
}

Model

// Update makes changes to an existing item.
func Update(db Connection, name string, ID string, userID string) (sql.Result, error) {
    result, err := db.Exec(fmt.Sprintf(`
        UPDATE %v
        SET name = ?
        WHERE id = ?
            AND user_id = ?
            AND deleted_at IS NULL
        LIMIT 1
        `, table),
        name, ID, userID)
    return result, err
}

Soft Delete an Item

A soft delete leaves the item in the database, but marks it as deleted with a timestamp.

Controller

// Destroy handles the delete form submission.
func Destroy(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)

    _, err := note.DeleteSoft(c.DB, c.Param("id"), c.UserID)
    if err != nil {
        c.FlashError(err)
    } else {
        c.FlashNotice("Item deleted.")
    }

    c.Redirect(uri)
}

Model

// Delete marks an item as removed.
func DeleteSoft(db Connection, ID string, userID string) (sql.Result, error) {
    result, err := db.Exec(fmt.Sprintf(`
        UPDATE %v
        SET deleted_at = NOW()
        WHERE id = ?
            AND user_id = ?
            AND deleted_at IS NULL
        LIMIT 1
        `, table),
        ID, userID)
    return result, err
}

Hard Delete an Item

A hard delete removes the item from the database.

Controller

// Destroy handles the delete form submission.
func Destroy(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)

    _, err := note.DeleteHard(c.DB, c.Param("id"), c.UserID)
    if err != nil {
        c.FlashError(err)
    } else {
        c.FlashNotice("Item deleted.")
    }

    c.Redirect(uri)
}

Model

// DeleteHard removes an item.
func DeleteHard(db Connection, ID string, userID string) (sql.Result, error) {
    result, err := db.Exec(fmt.Sprintf(`
        DELETE FROM %v
        WHERE id = ?
            AND user_id = ?
            AND deleted_at IS NULL
        `, table),
        ID, userID)
    return result, err
}

PostgreSQL Support

To use PostgreSQL, you need to a few lines of code. The migration support is not built into Jay yet so you’ll have to run them manually.

Add the PostgreSQL structure to the env.json.example file:

"PostgreSQL":{
    "Username":"root",
    "Password":"",
    "Database":"blueprint",
    "Hostname":"127.0.0.1",
    "Port":5432,
    "Parameter":"",
    "MigrationFolder":"migration/postgresql",
    "Extension":"sql"
},

Ensure the JSON is readable by to the Info struct in lib/env so add this line:

PostgreSQL postgresql.Info `json:"PostgreSQL"`

Add these lines to the RegisterServices() function in lib/boot:

// Connect to the PostgreSQL database
postgresqldb, _ := config.PostgreSQL.Connect(true)

If you want to replace MySQL, you can change the line at the bottom of the RegisterServices() function in lib/boot to pass PostgreSQL instead of MySQL:

// Store the database connection in flight
flight.StoreDB(postgresqldb)

If you want to add instead of replacing MySQL, you need to: - Add a new function to the lib/flight package similar to StoreDB() - And a new line to the Info struct in the lib/flight - Add the new variable to the Context() function in lib/flight

Views

Tue, 08 Mar 2016 21:07:13 +0100

Basic Usage

Views contain the HTML served by your application and separate your controller/application logic from your presentation logic. The views are parsed by the html/template package.

A view should include the four define blocks (title, head, content, and foot) and may look like this:

{{define "title"}}About Blueprint{{end}}
{{define "head"}}{{end}}
{{define "content"}}
	<div class="page-header">
		<h1>{{template "title" .}}</h1>
	</div>
	<p>Blueprint lays the foundation for your web application using the Go language.</p>
	{{template "footer" .}}
{{end}}
{{define "foot"}}{{end}}

Since this view is stored at view/about/index.tmpl, we render it using the view helper package like so:

// import "github.com/blue-jay/core/view"
c := flight.Context(w, r)
v := c.View.New("about/index")
// Variables would go here like this: v.Vars["first_name"] = session.Values["first_name"]
v.Render(w, r)

If you don’t have to pass any variables to the template, you could shorten it like this:

// import "github.com/blue-jay/core/view"
c := flight.Context(w, r)
c.View.New("about/index").Render(w, r)

Base Template

By default, the view/base.tmpl template is used as the base template (as specified in env.json). If you want to change the base template for a template, you can try this:

c := flight.Context(w, r)
v := c.View.New("about/index").Base("alternate")
v.Render(w, r)

A shorter way to specify the view with a different base template and then render is like this:

c := flight.Context(w, r)
c.View.New("about/about").Base("alternate").Render(w, r)

View Package

The core/view package is a wrapper for the Go html/template package and provides the following:

thread-safe template caching
ability to extend the list of functions available in templates
ability to modify the variables available in templates

The set up of the view package is handled by the lib/boot package. The config is then passed to flight so it can be accessed by controllers.

// Set up the views
config.View.SetTemplates(config.Template.Root, config.Template.Children)

// Set up the functions for the views
config.View.SetFuncMaps(
	config.Asset.Map(config.View.BaseURI),
	link.Map(config.View.BaseURI),
	noescape.Map(),
	prettytime.Map(),
	form.Map(),
)

// Set up the variables and modifiers for the views
config.View.SetModifiers(
	authlevel.Modify,
	uri.Modify,
	xsrf.Token,
	flash.Modify,
)

// Store the variables in flight
flight.StoreConfig(*config)

Organization

The HTML templates are organized in folders under the view folder:

about/index.tmpl	 - quick blurb about the app
home/index.tmpl      - public and authenticated home page
login/index.tmpl     - login page
note/create.tmpl	 - create a note
note/edit.tmpl		 - edit a note
note/index.tmpl		 - view all notes
note/show.tmpl		 - view a note
partial/favicon.tmpl - favicon metadata generated by gulpfile.js
partial/footer.tmpl	 - footer at the bottom of all pages
partial/menu.tmpl	 - menu at the top of all pages
register/index.tmpl	 - register page
base.tmpl            - base template for all pages

View Functions

The Go template packages supports passing a FuncMap which maps names to a function. This means you can add functions so they are available to the views. These functions are stored in the viewfunc folder. Here is an example of a LINK function that can be used to create hyperlinks and the code is stored in viewfunc/link/link.go:

// Package link provides a funcmap for html/template to generate a hyperlink.
package link

import (
	"fmt"
	"html/template"
)

// Map returns a template.FuncMap for LINK that returns a hyperlink tag.
func Map(baseURI string) template.FuncMap {
	f := make(template.FuncMap)

	f["LINK"] = func(path, name string) template.HTML {
		return template.HTML(fmt.Sprintf(`<a href="%v%v">%v</a>`, baseURI, path, name))
	}

	return f
}

To use this function in a template, you would write it like this:

{{LINK "register" "Create a new account."}}

And the code would render like this:

<a href="/register">Create a new account.</a>

Once you create a new funcmap, you make it available to the views by adding it to the view.SetFuncMaps() function in the lib/boot/boot.go file:

// Set up the functions for the views
config.View.SetFuncMaps(
	config.Asset.Map(config.View.BaseURI),
	link.Map(config.View.BaseURI),
	noescape.Map(),
	prettytime.Map(),
	form.Map(),
)

Included Functions

There are a few functions that are included to make working with the templates and static files easier:

<!-- CSS file with media attribute -->
{{CSS "static/css/normalize3.0.0.min.css" "all"}}
<!-- parses with timestamp to -->
<link media="all" rel="stylesheet" type="text/css" href="/static/css/normalize3.0.0.min.css?1435528339" />

<!-- JS file -->
{{JS "static/js/jquery1.11.0.min.js"}}
<!-- parses with timestamp to -->
<script type="text/javascript" src="/static/js/jquery1.11.0.min.js?1435528404"></script>

<!-- Hyperlinks -->
{{LINK "register" "Create a new account."}}
<!-- parses to -->
<a href="/register">Create a new account.</a>

<!-- Output an unescaped variable (not a safe idea, but it is useful when troubleshooting) -->
{{.SomeVariable | NOESCAPE}}

<!-- Time format for mysql.NullTime -->
{{NULLTIME .SomeTime}}
<!-- parses to format -->
3:04 PM 01/02/2006

<!-- Time format helper for mysql.NullTime that shows the latest of the two variables -->
{{PRETTYTIME .CreatedAt .UpdatedAt}}
<!-- parses to format -->
3:04 PM 01/02/2006

View Variables

There is an easy way to add variables so they are available in the views. The viewmodify folder contains packages that define variables in the view.Vars map. Since you are editing the map right before it renders, it will overwrite any other variables that were set in the controllers so it’s best to choose names or pick a naming convention for your variables.

You can also modify the view.Info struct before it renders if you need to display a different view or use a different base template.

In the viewmodify/authlevel/authlevel.go file, the AuthLevel variable is made available so the views can determine if the user is authenticated or not:

Source

// Package authlevel adds an AuthLevel variable to the view template.
package authlevel

import (
	"net/http"

	"github.com/blue-jay/blueprint/lib/flight"
	"github.com/blue-jay/core/view"
)

// Modify sets AuthLevel in the template to auth if the user is authenticated.
// Sets AuthLevel to anon if not authenticated.
func Modify(w http.ResponseWriter, r *http.Request, v *view.Info) {
	c := flight.Context(w, r)

	// Set the AuthLevel to auth if the user is logged in
	if c.Sess.Values["id"] != nil {
		v.Vars["AuthLevel"] = "auth"
	} else {
		v.Vars["AuthLevel"] = "anon"
	}
}

To use the variable, you could write this type of logic into your view:

{{if eq .AuthLevel "auth"}}
You are logged in.
{{else}}
You are not logged in.
{{end}}

Once you create a new package, you make it available to the views by adding it to the view.SetModifiers() function in the lib/boot/boot.go file:

// Set up the variables and modifiers for the views
config.View.SetModifiers(
	authlevel.Modify,
	uri.Modify,
	xsrf.Token,
	flash.Modify,
)

Included Variables

There are a few included variables you can use in templates:

<!-- Use AuthLevel=auth to determine if a user is logged in (if session.Values["id"] != nil) -->
{{if eq .AuthLevel "auth"}}
You are logged in.
{{else}}
You are not logged in.
{{end}}

<!-- Use BaseURI to print the base URL specified in the env.json file, ends in slash -->
<li><a href="{{.BaseURI}}about">About</a></li>
<!-- Use CurrentURI to print the current URL, does not end in slash -->
<li><a href="{{.CurrentURI}}">Current Page</a></li>
<!-- Use ParentURI to print the URL up one level, does not end in slash -->
<li><a href="{{.ParentURI}}">Parent Page</a></li>
<!-- Use GrandparentURI to print the URL up two levels, does not end in slash -->
<li><a href="{{.GrandparentURI}}">Grandparent Page</a></li>

<!-- Use token to output the CSRF token in a form -->
<input type="hidden" name="token" value="{{.token}}">

Repopulate Form Fields

When a form is submitted and there are errors like when a required field is missing, the same web page should reload. Unfortunately, forms are not refilled so there are a few helpers from the form package that will help you refill, select, and check.

These functions actually do both form population (filling in a form from a database record) and form repopulation (filling in a form from a form submission where something went wrong like a required field was left blank). These functions will fill the form with values from the form submission over the values from the database record. If you refresh the page, the form submission values will be forgotten and the values from the database record will return.

For instance, say your form has two fields: name and age. Both are required fields. You type in your name, John Doe, forget to type in your age, and click the submit button. The page will reload, show an error message, and the functions will automatically refill the name field with your name. The record has not been saved in the database, but the name field is remembered from the form submission (form repopulation). You enter in your age as 30, click the submit button, and the record is successfully added to the database.

Let’s say you want to edit the database record and you want to enter in a new age. You load the edit page and the functions will automatically refill the name field and the age field with the values from the database (form population). You try to be sneaky and change your age to the word “thirty”, instead of the number 30. You click the submit button, the page reloads, shows an error message, and refills the name field and the age. The age field will be filled with the word “thirty” because the form submission values take priority over the values from the database. If you clicked the refresh button in your browser, the age field would then load the number 30 from the database instead.

There are two views that benefit from these functions: create.tmpl and edit.tmpl. You don’t have to use these names, but it’s just an example to show you these functions will primarily be used in the the template to create a new record in the database (create.tmpl) and the template to edit an existing record in the database (edit.tmpl).

In the create.tmpl view, there may be required fields. If the form requires typing in a long block of text for a couple answers and the user forgets one of the required fields, when the page reloads, all the text will not be there. These functions will refill, select, and check all the form inputs specified in the controller. The create.tmpl does not use the “default value” field in these functions so you can set them to an empty string (“”) or set them to a view variable so you can copy and paste the same code between create.tmpl and edit.tmpl. The edit.tmpl view requires the same logic, but also needs the “default value” to prefill, select, and check the form values from view variables (which will probably be pulled from a model struct).

Check out the Repopulate Form Fields section on the Controllers page. It will show you the single line of code needed in your controller so these fields repopulate on form submission.

These are the functions/blocks to use in your templates. Notice that some of the HTML attributes are missing like name, value, and type from the elements. The blocks will automatically fill these in for you so you don’t have the write the name of the element multiple times. By the way, it took very little code to add this functionality so check out the form package to see how it was accomplished.

<!-- TEXT accepts the element name, a default value, and then a period -->
<input {{TEXT "email" .item.Email .}} type="email" class="form-control" id="email" />
<!-- then parses to a name attribute when no repopulation value is passed -->
<input name="email" type="email" class="form-control" id="email" />
<!-- and parses to a name and a value when a repopulation value is passed -->
<input name="email" value="[email protected]" type="email" class="form-control" id="email" />

<!-- TEXTAREA accepts the element name, a default value, and then a period -->
<textarea rows="5" class="form-control" id="name" name="name" />{{TEXTAREA "name" .item.Name .}}</textarea>
<!-- then parses to nothing when no repopulation value is passed -->
<textarea rows="5" class="form-control" id="name" name="name" /></textarea>
<!-- and parses to a value when a repopulation value is passed -->
<textarea rows="5" class="form-control" id="name" name="name" />Sample text</textarea>

<!-- CHECKBOX accepts the element name, value, default value, and then a period -->
<label><input {{CHECKBOX "rememberme" "r1" .item.RememberMe .}}> Remember me</label>
<!-- then parses to a type, name, and value attribute when no repopulation value is passed -->
<label><input type="checkbox" name="rememberme" value="r1"> Remember me</label>
<!-- and parses to a type, name, value, and the word 'checked' when a repopulation value is passed -->
<label><input type="checkbox" name="rememberme" value="r1" checked> Remember me</label>

<!-- RADIO accepts the element name, value, default value, and then a period -->
<label><input {{RADIO "options" "burger" .item.Option .}}> Burger</label>
<!-- then parses to a type, name, and value attribute when no repopulation value is passed -->
<label><input type="radio" name="options" value="burger"> Burger</label>
<!-- and parses to a type, name, value attribute, and the word 'checked' when a repopulation value is passed -->
<label><input type="radio" name="options" value="burger" checked> Burger</label>

<!-- OPTION accepts the element name, value, default value, and then a period -->
<select name="select"><option {{OPTION "select" "Apple" .item.Select .}}>Apple</option></select>
<!-- then parses to a value attribute when no repopulation value is passed -->
<select name="select"><option value="Apple">Apple</option></select>
<!-- and parses to a value attribute and the word 'selected' when a repopulation value is passed -->
<select name="select"><option value="Apple" selected>Apple</option></select>

Here are examples of all the fields with the Bootrap structure and classes:

<div class="form-group">
	<label for="email">Email Address</label>
	<div><input {{TEXT "email" .item.Email .}} type="email" class="form-control" id="email" maxlength="48" placeholder="Email" /></div>
</div>

<div class="form-group">
	<label for="name">Item</label>
	<div><textarea rows="5" class="form-control" id="name" name="name" placeholder="Type your text here..." />{{TEXTAREA "name" .}}</textarea></div>
</div>

<div class="checkbox">
    <label>
        <input {{CHECKBOX "rememberme" "r1" .item.RememberMe .}}> Remember me
    </label>
</div>
<div class="checkbox">
    <label>
        <input {{CHECKBOX "rememberme" "r2" .item.RememberMe .}}> Remember me
    </label>
</div>

<div class="radio">
    <label>
        <input {{RADIO "options" "burger" .item.Option .}}> Burger
    </label>
</div>
<div class="radio">
    <label>
        <input {{RADIO "options" "taco" .item.Option .}}> Taco
    </label>
</div>

<select class="form-control" name="select">
    <option {{OPTION "select" "Apple" .item.Select .}}>Apple</option>
    <option {{OPTION "select" "Banana" .item.Select .}}>Banana</option>
    <option {{OPTION "select" "cherry" .item.Select .}}>Cherry</option>
</select>

<select multiple class="form-control" name="mselect">
    <option {{OPTION "mselect" "red" .item.Select .}}>Red</option>
    <option {{OPTION "mselect" "green" .item.Select .}}>Green</option>
    <option {{OPTION "mselect" "blue" .item.Select .}}>Blue</option>
</select>

Change HTTP Methods

When you submit a form a a website, the site most likely sends a POST request to the server. In order for us to make our application more RESTful, we can use utilize the simple rest package to change the HTTP method from a URL query string. The rest middleware is already applied to every request which is configured in the boot package.

To change the form method, add this line to your form action and change the value to match a method like DELETE or PATCH. It will automatically be converted to uppercase.

The query string key should be: _method.

<!-- Example of a PATCH request -->
<form method="post" action="{{$.CurrentURI}}?_method=patch">

<!-- Example of a DELETE request -->
<form class="button-form" method="post" action="{{$.GrandparentURI}}/{{.item.ID}}?_method=delete">

This is an example of a form that is updating and email and a password using the PATCH HTTP method:

<form method="post" action="{{$.CurrentURI}}?_method=patch">
	<div class="form-group">
		<label for="email">Email Address</label>
		<div><input {{TEXT "email" .item.Email .}} type="email" class="form-control" id="email" /></div>
	</div>

	<div class="form-group">
		<label for="password">Password</label>
		<div><input {{TEXT "password" .item.Password .}} type="password" class="form-control" id="password" /></div>
	</div>

	<input type="submit" class="btn btn-primary" value="Change" class="button" />

	<input type="hidden" name="_token" value="{{$.token}}">
</form>

The routes for this page would look something like this:

// Display the Update Page - typical GET HTTP method
router.Get("/user/edit/:id", Edit, c...)

// Handle the Update Page Form Submissions - PATCH HTTP method
router.Patch("user/edit/:id", Update, c...)

Header and Footer

It’s also easy to add template-specific code before the closing and tags:

<!-- Code is added before the closing </head> tag -->
{{define "head"}}<meta name="robots" content="noindex">{{end}}

...

<!-- Code is added before the closing </body> tag -->
{{define "foot"}}{{JS "//www.google.com/recaptcha/api.js"}}{{end}}

JavaScript

There are a few built-in functions that you can use to trigger a flash notification using JavaScript.

flashError("An error occurred on the server.");

flashSuccess("Item added!");

flashNotice("Item deleted.");

flashWarning("Field missing: email");

Library

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

If you look through the Core library, you’ll see packages that provide different functionality. These packages are designed to be shared and used through the application. Since Blueprint is a web application, some of the packages must be thread-safe to ensure they won’t throw any errors if they are accessed at the same time by two separate threads.

As you create your own packages, you can store them in the blueprint/lib folder to keep them organized and separate.

It’s a good idea to keep them light on dependencies so you can reuse them again in later projects. Packages that are too tightly-coupled require time to rework so you might as well do it right from the start.

Let’s take a look at the email package in sections. The first of the three sections is the package declaration and import section. Notice how the only packages the email package uses are part of the standard library. This is a good indicator that the package could be moved to a different project without rewriting.

Source

// Package email provides email sending via SMTP.
package email

import (
    "encoding/base64"
    "fmt"
    "net/smtp"
)

The Info struct holds the details for the SMTP server and it should be added to the Info struct of the lib/env package and then parsed from the env.json file. See the Configuration section for more information about adding to env.json.

// Info holds the details for the SMTP server.
type Info struct {
    Username string
    Password string
    Hostname string
    Port     int
    From     string
}

The final section of the email package sends an email using the configuration settings. You’ll notice the function is a struct method which makes it really easy to use from the flight package.

// Send an email.
func (c Info) Send(to, subject, body string) error {
    auth := smtp.PlainAuth("", c.Username, c.Password, c.Hostname)

    // Create the header
    header := make(map[string]string)
    header["From"] = c.From
    header["To"] = to
    header["Subject"] = subject
    header["MIME-Version"] = "1.0"
    header["Content-Type"] = `text/plain; charset="utf-8"`
    header["Content-Transfer-Encoding"] = "base64"

    // Set the message
    message := ""
    for k, v := range header {
        message += fmt.Sprintf("%s: %s\r\n", k, v)
    }
    message += "\r\n" + base64.StdEncoding.EncodeToString([]byte(body))

    // Send the email
    err := smtp.SendMail(
        fmt.Sprintf("%s:%d", c.Hostname, c.Port),
        auth,
        c.From,
        []string{to},
        []byte(message),
    )

    return err
}

To use in a controller, you would get the context from the flight package and then from the Config variable, you could access the email struct and then the Send() function.

// Index sends an email.
func Index(w http.ResponseWriter, r *http.Request) {
    c := flight.Context(w, r)

    err := c.Config.Email.Send("This is the subject", "This is the body!")
    if err != nil {
        c.FlashError(err)
        return
    }
}

Code Generation

A new lib package can be generated using this command: jay generate lib/default package:value

Jay Overview

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

The command-line tool, Jay, has been mentioned throughout this documentation quite a few times now so it’s a good time to talk a little about the tool.

Jay uses the brilliant github.com/alecthomas/kingpin package to manage the help documents, commands, subcommands, and arguments. It takes care of groundwork so it can focus on the actual tasks.

If you ever want to see the help documents for a command or subcommand, add -h or --help to the end and the help documentation should be able to assist. If you are still having problems, check out the Jay GoDoc.

When using Jay, there are flags, commands, and subcommands.

The available flags throughout are:

-h or --help for help documentation
-v or --version for version information
-c or --config to specify the env.json config file (otherwise JAYCONFIG environment variable will be used)

The available commands are:

jay env for managing the env.json file
jay find for locating text inside files in subfolders
jay replace for replacing text inside files in subfolder
jay generate for creating code based on templates using the text/template package
jay migrate:mysql for managing the MySQL database state

The available subcommands are:

jay env make for creating env.json from env.json.example
jay env keyshow for showing newly generated session keys
jay env updateshow for updating env.json with newly generation session keys
jay migrate:mysql make for creating a new migration ‘up’ file and ‘down’ file
jay migrate:mysql all for applying all ‘up’ migrations
jay migrate:mysql reset for applying all ‘down’ migrations
jay migrate:mysql refresh for applying all ‘down’ then ‘up’ migrations
jay migrate:mysql status for displaying the current database state
jay migrate:mysql up for applying only one ‘up’ migration
jay migrate:mysql down for applying one one ‘down’ migration

There is also a common syntax used by each of the commands, subcommands, and arguments that make the help documents easy to follow.

Flags have one or two dashes in the front: -h, --help
Commands follow the application name (jay): jay migrate:mysql
Subcommands follow the command: jay migrate:mysql make
Arguments follow the command or subcommand: jay migrate:mysql make <description>
Required arguments: <required>
Optional arguments: [<optional>]

Find and Replace

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

Jay includes the ability to do a case-sensitive find and replace. This is great when you have many files to look through and need simple way to find and replace quickly.

Find Usage

usage: jay find <folder> <text> [<extension>] [<recursive>] [<filename>]

Search for files containing matching text.

Flags:
  -h, --help     Show context-sensitive help (also try --help-long and
                 --help-man).
  -v, --version  Show application version.

Args:
  <folder>       Folder to search
  <text>         Case-sensitive text to find.
  [<extension>]  File name or extension to search in. Use * as a wildcard.
                 Directory names are not valid.
  [<recursive>]  True to search in subfolders. Default: true
  [<filename>]   True to include file path in results if matched. Default: false

Replace Usage

usage: jay replace <folder> <find> [<replace>] [<extension>] [<recursive>] [<filename>] [<commit>]

Search for files containing matching text and then replace it with new text.

Flags:
  -h, --help     Show context-sensitive help (also try --help-long and
                 --help-man).
  -v, --version  Show application version.

Args:
  <folder>       Folder to search
  <find>         Case-sensitive text to replace.
  [<replace>]    Text to replace with.
  [<extension>]  File name or extension to search in. Use * as a wildcard.
                 Directory names are not valid.
  [<recursive>]  True to search in subfolders. Default: true
  [<filename>]   True to include file path in results if matched. Default: false
  [<commit>]     True to makes the changes instead of just displaying them.
                 Default: true

Find and Replace Examples

Here are examples are how to use find and replace:

# Find the word "red" in all *.go files in the current folder and in subfolders.
jay find . red

# Find the word "red" in all files in the current folder only.
jay find . red "*.*" false

# Find the word "red" in *.go files in current folder and in subfolders and 
# include file paths that match also.
jay find . red "*.go" true true

# Replace the word "red" with the word "blue" in all *.go files in the current
# folder and in subfolders.
jay replace . red blue

# Replace the word "red" with the word "blue" in all *.go files in current
# folder only.
jay replace . red blue "*.go" false

# Change the name of the project in current folder and in subfolders and all
# imports to another repository.
jay replace . "blue-jay/blueprint" "user/project"

Database Migration

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

Database migrations are a great way to manage incremental database changes. The migration state is stored in the same database (the one specified in env.json) and recorded in the migration table. This is how the jay migrate:mysql statuscommand knows which migration was performed last.

Each incremental change should have a set of two files: an ‘up’ file and a ‘down’ file. The ‘up’ file contains code (like SQL) which is applied to the database you add features or fix bugs in your database. The ‘down’ file contains the code to remove the change or undo it.

More than one migration can now be run on a database. You just have to specify a different table value in the env.json file under the MySQL.Migration.Table key.

Note 1: The jay migrate commands requires the environment variable, JAYCONFIG, to point to the env.json file path. The migration folder is specified in the env.json file under MySQL.Migration.Folder. If the environment variable is not set, you can specify the –config or -c flag and pass the path to env.json.

Note 2: Make sure you do not create any migrations with a date earlier than any applied migrations. Jay will not go back and apply them. They must be created sequentially.

When you start using Blueprint you’ll see two migration files already exist in the migration/mysql folder:

20160630_020000.000000_init.up.sql - adds the initial tables and data
20160630_020000.000000_init.down.sql - removes the tables and data

Jay provides a few commands to make the migrations easier. Here is a list of the commands:

jay migrate:mysql make "test" # Create new migration
jay migrate:mysql all         # Advance all migrations
jay migrate:mysql reset       # Rollback all migrations
jay migrate:mysql refresh     # Rollback all migrations then advance all migrations
jay migrate:mysql status      # See last 'up' migration
jay migrate:mysql up          # Apply only the next 'up' migration
jay migrate:mysql down        # Apply only the current 'down' migration

Workflow

Let’s walk through an typical workflow. Assume the blueprint folder is the root of a git repository. Developer Joe needs to add a feature to the application to store books. Joe creates a new branch called feature-store-books. He needs to create a new table called book so he creates a new database migration: jay migrate:mysql make "feature-store-books". He opens the ‘up’ file and adds the SQL query to create a new table with the following columns: title, author, and publication_date. In the ‘down’ file, he writes the code to drop the table. He also writes the code to create, read, update, and delete the books in his Go code and then performs a git merge and then a git push. Developer Steve needs to add an additional column to the book table called: publisher. Steve performs a git pull to download the latest code from the repository. In order to update his local database to the latest version of code, runs: jay migrate:mysql all. Then, Steve creates a new migration for the new requirement: jay migrate:mysql make "feature-add-publisher". Steve adds the SQL ADD COLUMN code to the new ‘up’ file and the SQL DROP COLUMN code to the new ‘down’ file and then performs a git merge and a git push again.

migrate make

The jay migrate:mysql make [description] command create a new ‘up’ and ‘down’ migration in the database/migration folder.

migrate all

The jay migrate:mysql all command finds the current status of the database and then applies all the code from each of the ‘up’ files in chronological order based on filename.

migrate reset

The jay migrate:mysql reset command finds the current status of the database and then applies all the code from each of the ‘down’ files in reverse chronological order based on filename which should remove all tables and data with the exception of an an empty migration table.

Note: If any tables were created outside of the migrations, they should still be in the database.

migrate refresh

The jay migrate:mysql refresh command runs a jay migrate reset and then applies all the code from each of the ‘up’ files in chronological order based on filename.

migrate status

The jay migrate:mysql status command reads the latest record in the migration table which is the last ‘up’ file that was applied to the database.

migrate up

The jay migrate:mysql up command applies only the code in the next ‘up’ file in chronological order based on filename.

migrate down

The jay migrate:mysql down command applies only the code in the current ‘down’ file.

Other Database Changes

If the ‘up’ and ‘down’ files are written properly, tables created manually outside the migrations should be left untouched by the jay migrate commands. The only changes jay migrate makes to the database outside of the migrations are the creation of the database itself based on the settings in env.json and the modification of the migration table.

Code Generation

Mon, 01 Jan 0001 00:00:00 +0000

Basic Usage

Code generation makes it easy to build out new features so you don’t have to retype or copy and paste the same code over again. It’s especially useful when prototyping and need to see how something will look or work.

Note: The jay generate commands requires the environment variable, JAYCONFIG, to point to the env.json file path. The generation folder containing the templates is specified in the env.json file under Generation.TemplateFolder. If the environment variable is not set, you can specify the –config or -c flag and pass the path to env.json.

Jay tries to make it easy to generate code by using tools that you already know: the text/template package from the standard Go library and JSON.

A template pair consists of a .json file and a .gen file. The .gen file contains the text/template parsable code. The .json file contains other information needed for the generation process like:

config.type - either ‘single’ if creating one file or ‘collection’ if referencing one or more other .json files
config.output - relative path at which to create the file
config.parse - either true or false

In the .json file, any other keys outside these three will be applied directly to the .gen file. If you leave a key blank, that tells jay generate that it needs to be passed via command-line.

Don’t worry, there are already a boatload of templates ready to use. They are organized by type in the generate folder of Blueprint. If .json file does not have a .gen pair in the same folder, then it has a config.parse value of collection which means it references other .json files with a config.parse value of single.

The lib/flight package is a helper package that reduces a lot of code from the controller. It contains functions to simplify the use of flash messages, form validation, form repopulation, and URL parameters.

controller
- bare.gen | bare.json - creates a bare controller with only placeholder functions
- default.gen | default.json - creates a controller with CRUD ready code with the flight package
- nameonly.gen | nameonly.json - creates a controller with CRUD ready code with the flight package and only a name column
- noflight.gen | noflight.json - creates a controller with CRUD ready code without the flight package
crud
- bare.json - creates a bare controller, model, and four views
- default.json - creates a controller, model, and four views CRUD ready with the flight package
- nameonly.json - creates a controller, model, and four views CRUD ready with the flight package and only a name column
- noflight.json - creates a controller, model, and four views CRUD ready without the flight package
- table.json - creates a controller, model, and four views CRUD ready with the flight package and only a name column that displays in a table view
lib
- default.gen | default.json - creates a thread-safe wrapper package
middleware
- default.gen | default.json - creates a middleware package
model
- bare.gen | bare.json - creates a bare model with only placeholder functions
- default.gen | default.json - creates a model with CRUD ready code
- nameonly.gen | nameonly.json - creates a model with CRUD ready code and only a name column
view
- bare.json - creates four bare views with only a basic structure
- create.gen | create.json - creates a CRUD ready creation form view
- create_bare.gen | create_bare.json - creates a bare view with only a basic structure
- default.json - creates four views with CRUD ready code
- edit.gen | edit.json - creates a CRUD ready edit form view
- edit_bare.gen | edit_bare.json - creates a bare view with only a basic structure
- index.gen | index.json - creates a CRUD ready display view for multiple items
- index_bare.gen | index_bare.json - creates a bare view with only a basic structure
- index_table.gen | index_table.json - creates a CRUD ready table view for multiple items
- show.gen | show.json - creates a CRUD ready display view for a single item
- show_bare.gen | show_bare.json - creates a bare view with only a basic structure
- show_table.gen | show_table.json - creates a CRUD ready table view for a single item
- single.gen | single.json - creates a bare view with only a basic structure
- table.json - creates four views with CRUD ready code in a table view
viewfunc
- default.gen | default.json - creates a FuncMap package for use with the html/template package
viewmodify
- default.gen | default.json - creates a package to modify the lib/view package before rendering

Let’s view a couple examples.

Middleware Example

The generate/middleware/default.gen file contains this template. The {{.package}} variable is the only required variable for this template so it must be added to the .json file as a key with blank value. This forces jay generate to require the user to pass a package variable before it will generate the template.

// Package {{.package}}
package {{.package}}

import (
    "net/http"
)

// Handler
func Handler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Logic BEFORE the other handlers and function goes here
        next.ServeHTTP(w, r)
        // Logic AFTER the other handlers and function goes here
    })
}

The generate/middleware/default.json file contains this JSON. The config.type is set to single because it’s only generating one file. The config.output is the relative path where the file will be generated. Notice that the config.output also uses the package variable. This is the beauty of the jay generate tool: the .json files are actually parsed multiple times (limit is set to 100) to ensure all variables are set.

In the first iteration of parsing, the package key is set to value passed via the command-line. In the second iteration of parsing, the {{.package}} variables are set to the same value because the top level package key becomes a variable itself.

All first level keys (config.type, config.output, package) become variables after the first iteration of parsing. If a variable is misspelled and is never filled, a helpful error will display to the command-line.

The folder structure of the templates (model, controller, etc) has no effect on the generation, it’s purely to aid with organization of the template pairs.

{
    "config.type": "single",
    "config.output": "middleware/{{.package}}/{{.package}}.go",
    "package": ""
}

To generate this template, the command would look like this. The package key is separated from the value by a colon (:). An argument of package: without a value is also acceptable, but would end up creating a file called .go in the middleware folder.

jay generate middleware/default package:test

The final output would be to the file, middleware/test/test.go, and would look like this:

// Package test
package test

import (
    "net/http"
)

// Handler
func Handler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Logic BEFORE the other handlers and function goes here
        next.ServeHTTP(w, r)
        // Logic AFTER the other handlers and function goes here
    })
}

Controller Example

This is a snippet of the template in generate/controller/bare.gen. In this template, there are two variables: package and url.

// Package {{.package}}
package {{.package}}

import (
    "net/http"

    "github.com/blue-jay/blueprint/controller/status"

    "github.com/blue-jay/core/router"
)

var (
    uri = "/{{.url}}"
)

// Load the routes.
func Load() {
    c := router.Chain()
    router.Get(uri, Index, c...)
    router.Get(uri+"/create", Create, c...)
    router.Post(uri+"/create", Store, c...)
    router.Get(uri+"/view/:id", Show, c...)
    router.Get(uri+"/edit/:id", Edit, c...)
    router.Patch(uri+"/edit/:id", Update, c...)
    router.Delete(uri+"/:id", Destroy, c...)
}

// Index displays the items.
func Index(w http.ResponseWriter, r *http.Request) {
    status.Error501(w, r)
}

// Create displays the create form.
func Create(w http.ResponseWriter, r *http.Request) {
    status.Error501(w, r)
}

...

The generate/controller/bare.json file contains this JSON.

{
    "config.type": "single",
    "config.output": "controller/{{.package}}/{{.package}}.go",
    "package": "",
    "url": ""
}

To generate this template, the command would look like this. Notice the second variable, url.

jay generate controller/bare package:monkey url:banana

The final output would be to the file, controller/monkey/monkey.go, and would look like this:

// Package monkey
package monkey

import (
    "net/http"

    "github.com/blue-jay/blueprint/controller/status"

    "github.com/blue-jay/core/router"
)

var (
    uri = "/banana"
)

// Load the routes.
func Load() {
    c := router.Chain()
    router.Get(uri, Index, c...)
    router.Get(uri+"/create", Create, c...)
    router.Post(uri+"/create", Store, c...)
    router.Get(uri+"/view/:id", Show, c...)
    router.Get(uri+"/edit/:id", Edit, c...)
    router.Patch(uri+"/edit/:id", Update, c...)
    router.Delete(uri+"/:id", Destroy, c...)
}

// Index displays the items.
func Index(w http.ResponseWriter, r *http.Request) {
    status.Error501(w, r)
}

// Create displays the create form.
func Create(w http.ResponseWriter, r *http.Request) {
    status.Error501(w, r)
}

...

Single View Example

The generate/view/single.gen file contains this template. We don’t actually want to parse this code because it’s a view itself. We can tell the parser not to parse in the single.json file by setting the value of config.parse to false.

{{define "title"}}{{end}}
{{define "head"}}{{end}}
{{define "content"}}
    <div class="page-header">
        <h1>{{template "title" .}}</h1>
    </div>

    <p>Not Implemented</p>

    {{template "footer" .}}
{{end}}
{{define "foot"}}{{end}}

The generate/view/single.json file contains this JSON. Again, we set config.parse to false and only use the variables for specifying the config.output path. The variables are not used inside the single.json template at all.

{
    "config.type": "single",
    "config.output": "view/{{.model}}/{{.name}}.tmpl",
    "config.parse": false,
    "model": "",
    "name": ""
}

To generate this template, the command would look like this. Notice the second variable, url.

jay generate view/single model:test name:create

The final output would be to the file, view/test/create.tmpl, and would look like this - no difference from the template itself since it was not parsed, just copied.

{{define "title"}}{{end}}
{{define "head"}}{{end}}
{{define "content"}}
    <div class="page-header">
        <h1>{{template "title" .}}</h1>
    </div>

    <p>Not Implemented</p>

    {{template "footer" .}}
{{end}}
{{define "foot"}}{{end}}

Multiple View Example

The generate/view/default.json file contains this JSON, but does not have a matching default.gen file. This is because the .json file simply passes variables to other .json files which have matching .gen files that generate files. First, the config.type key has a value of collection, that’s how you know it doesn’t have a matching .gen file. Next, the config.collection key contains an array of items that specify which template pairs to pass variables to.

The model key under each template receives the model variable from the root of the package which is required from the command-line.

{
    "config.type": "collection",
    "config.collection": [
        {
            "view/create": {
                "model": "{{.model}}"
            }
        },
        {
            "view/edit": {
                "model": "{{.model}}"
            }
        },
        {
            "view/index": {
                "model": "{{.model}}"
            }
        },
        {
            "view/show": {
                "model": "{{.model}}"
            }
        }
    ],
    "model": ""
}

In this example, the default.json file will pass variables to the following files:

generate/view/create.json
generate/view/edit.json
generate/view/index.json
generate/view/show.json

The files are all still relative to the root generate folder. Also, if you look at each of the four files, you’ll see that they require only one variable: model. Here is the contents of generate/view/create.json:

{
    "config.type": "single",
    "config.output": "view/{{.model}}/create.tmpl",
    "config.parse": false,
    "model": ""
}

To generate all four of these templates, the command would look like this.

jay generate view/default model:test

The final output would be to the following files:

view/test/create.json
view/test/edit.json
view/test/index.json
view/test/show.json

CRUD Example

If you put all those piece above together, you can generate the controller, model, and all four views necessary for a working CRUD component in a single command.

The generate/crud/default.json file contains this JSON:

{
    "config.type": "collection",
    "config.collection": [
        {
            "model/default": {
                "package": "{{.model}}",
                "table": "{{.model}}"
            }
        },
        {
            "controller/default": {
                "package": "{{.controller}}",
                "url": "{{.controller}}",
                "model": "{{.model}}",
                "view": "{{.view}}"
            }
        },
        {
            "view/default": {
                "model": "{{.view}}"
            }
        }
    ],
    "model": "",
    "controller": "",
    "view": ""
}

To generate all the components, the command would look like this.

jay generate crud/default model:note controller:notepad view:note