tangramjs

README

go-http-tangramjs

go-http-tangramjs is an HTTP middleware package for including Tangram.js (v0.21.1) assets in web applications.

Documentation

go-http-tangramjs is an HTTP middleware package for including Tangram.js assets in web applications. It exports two principal methods:

• tangramjs.AppendAssetHandlers(*http.ServeMux) which is used to append HTTP handlers to a http.ServeMux instance for serving Tangramjs JavaScript files, and related assets.
• tangramjs.AppendResourcesHandler(http.Handler, *TangramJSOptions) which is used to rewrite any HTML produced by previous handler to include the necessary markup to load Tangramjs JavaScript files and related assets.

Examples

Basic

package main

import (
	"embed"
	"html/template"
	"log"
	"net/http"

	"github.com/aaronland/go-http-tangramjs"
)

//go:embed *.html
var FS embed.FS

func ExampleHandler(templates *template.Template) (http.Handler, error) {

	t := templates.Lookup("example")

	fn := func(rsp http.ResponseWriter, req *http.Request) {
		err := t.Execute(rsp, nil)
		return
	}

	return http.HandlerFunc(fn), nil
}

func main() {

	api_key := "****"
	style_url := "/tangram/refill-style.zip"

	t, _ := template.ParseFS(FS, "*.html")

	mux := http.NewServeMux()
	
	map_handler, _:= ExampleHandler(t)

	tangramjs_opts := tangramjs.DefaultTangramJSOptions()
	tangramjs_opts.NextzenOptions.APIKey = api_key
	tangramjs_opts.NextzenOptions.StyleURL = style_url

	tangramjs.AppendAssetHandlers(mux, tangramjs_opts)
	
	map_handler = tangramjs.AppendResourcesHandler(map_handler, tangramjs_opts)

	mux.Handle("/", map_handler)

	endpoint := "localhost:8080"
	log.Printf("Listening for requests on %s\n", endpoint)

	http.ListenAndServe(endpoint, mux)
}

Error handling omitted for the sake of brevity.

You can see an example of this application by running the cmd/example application. You can do so by invoking the example Makefile target. For example:

$> make example APIKEY=XXXXXX
go run -mod vendor cmd/example/main.go -api-key XXXXXX
2021/05/05 15:31:06 Listening for requests on localhost:8080

The when you open the URL http://localhost:8080 in a web browser you should see the following:

With local "tilepacks"

It is also possible to use the go-http-tangramjs with local Nextzen "tilepack" MBTiles (or SQLite) databases using tools and methods provided by the tilezen/go-tilepacks package.

Unfortunately it is not possible to enable this functionality with a single "wrapper" method and requires some additional code that you'll need to add manually to your application.

Here is an abbreviated and annotated example of how to use a local "tilepack" in conjunction with the go-tilepacks' MbtilesHandler HTTP handler to serve tiles directly from your application. Error handling has been removed for the sake of brevity.

import (
       "flag"
	"github.com/aaronland/go-http-tangramjs"
	tiles_http "github.com/tilezen/go-tilepacks/http"
	"github.com/tilezen/go-tilepacks/tilepack"
       "net/http"
       "strings"
)

func main() {

	// These are the normal flags you might set to configure Tangram.js
	
	nextzen_api_key := flag.String("nextzen-api-key", "xxxxxx", "A valid Nextzen API key")
	nextzen_style_url := flag.String("nextzen-style-url", "/tangram/refill-style.zip", "A valid Nextzen style URL")

	// These next two flags are necessary if you want to enable local tile-serving.
	// The first flag is the path to a Nextzen MVT "tilepack" as created by the `go-tilepacks/cmd/build` tool.
	// The second flag is the relative URL that Tangram.js will use to load MVT data.
	
	tilepack_db := flag.String("nextzen-tilepack-database", "", "The path to a valid MBTiles database (tilepack) containing Nextzen MVT tiles.")
	tilepack_uri := flag.String("nextzen-tilepack-uri", "/tilezen/vector/v1/512/all/{z}/{x}/{y}.mvt", "The relative URI to serve Nextzen MVT tiles from a MBTiles database (tilepack).")

	flag.Parse()

	// Create a new ServeMux for handlings requests and 
	// append Tangram.js assets handlers to the mux
	
	mux := http.NewServeMux()	

	// Create a default TangramJSOptions instance
	// Assign the API key and style URL as usual
	
	tangramjs_opts := tangramjs.DefaultTangramJSOptions()
	tangramjs_opts.NextzenOptions.APIKey = *nextzen_api_key
	tangramjs_opts.NextzenOptions.StyleURL = *nextzen_style_url

	tangramjs.AppendAssetHandlers(mux, tangramjs_opts)
	
	// If tilepack_db is not empty the first thing we want to is
	// update the tile URL that Tangram.js will use to find vector
	// data to point to the value of the `tilepack_uri` flag
	
	if *tilepack_db != "" {
		tangramjs_opts.NextzenOptions.TileURL = *tilepack_uri
	}

	// Create the `net/http` handler that will serve your appliction
	// In this example "YourWWWHandler" is just a placeholder
	
	www_handler, _ := YourWWWHandler()

	// Append the Tangram.js resources to your application handler
	// and configure the mux to serve it
	www_handler = tangramjs.AppendResourcesHandler(www_handler, tangramjs_opts)
	mux.Handle("/", www_handler)

	// If tilepack_db is not empty then use it to create a tilepack.MbtilesReader
	// instance. Then use that reader to create a `net/http` handler for serving
	// tile requests. If you are configuring a mux handler to listen for requests
	// on "/" it is important that you configure your local tile handler afterward.
	
	if *tilepack_db != "" {

		tiles_reader, _ := tilepack.NewMbtilesReader(*tilepack_db)
		tiles_handler := tiles_http.MbtilesHandler(tiles_reader)

		// In this example we take the first leaf from the value of the `tilepack_uri`
		// flag ("/tilezen/") and use it to configure the mux instance for serving
		// tile requests.
		
		u := strings.TrimLeft(*tilepack_uri, "/")
		p := strings.Split(u, "/")
		path_tiles := fmt.Sprintf("/%s/", p[0])

		mux.Handle(path_tiles, tiles_handler)
	}

	// Serve mux here...
}

You can see a working example of this in the aaronland/go-marc/cmd/marc-034d application.

The creation of Nextzen vector tile "tilepack" databases is out of scope for this document. Please consult the documentation for the go-tilepacks build tool for details on creating custom databases.

It is currently only possible to serve tiles from a single "tilepack" database.

It is not possible to dynamically limit the map to the zoom range and tile extent of a given "tilepack" database. Yet. I'm working on it.

There are precompiled databases with global tile coverage for zoom levels 1-10, 11 and 12 available on the Internet Archive:

• Global tiles, zoom levels 1 through 10 (1.8GB)
• Global tiles, zoom level 11 (3.5GB)
• Global tiles, zoom level 12 (7.9GB)

See also

• https://github.com/tangrams/tangram
• https://github.com/aaronland/go-http-leaflet
• https://github.com/tilezen/go-tilepacks

Documentation

Overview

`go-http-tangramjs` is an HTTP middleware package for including Tangram.js assets in web applications. It exports two principal methods:

* `tangramjs.AppendAssetHandlers(*http.ServeMux)` which is used to append HTTP handlers to a `http.ServeMux` instance for serving Tangramjs JavaScript files, and related assets. * `tangramjs.AppendResourcesHandler(http.Handler, *TangramJSOptions)` which is used to rewrite any HTML produced by previous handler to include the necessary markup to load Tangramjs JavaScript files and related assets.

Example

import (
	"embed"
	"github.com/aaronland/go-http-tangramjs"
	"html/template"
	"log"
	"net/http"
)

//go:embed *.html
var FS embed.FS

func ExampleHandler(templates *template.Template) (http.Handler, error) {

	t := templates.Lookup("example")

	fn := func(rsp http.ResponseWriter, req *http.Request) {
		err := t.Execute(rsp, nil)
		return
	}

	return http.HandlerFunc(fn), nil
}

func main() {

	api_key := "****"
	style_url := "/tangram/refill-style.zip"

	t, _ := template.ParseFS(FS, "*.html")

	mux := http.NewServeMux()

	tangramjs.AppendAssetHandlers(mux)

	map_handler, _:= ExampleHandler(t)

	tangramjs_opts := tangramjs.DefaultTangramJSOptions()
	tangramjs_opts.NextzenOptions.APIKey = api_key
	tangramjs_opts.NextzenOptions.StyleURL = style_url

	map_handler = tangramjs.AppendResourcesHandler(map_handler, tangramjs_opts)

	mux.Handle("/", map_handler)

	endpoint := "localhost:8080"
	log.Printf("Listening for requests on %s\n", endpoint)

	http.ListenAndServe(endpoint, mux)
}

Index

• Constants
• func AppendAssetHandlers(mux *http.ServeMux, opts *TangramJSOptions) error
• func AppendResourcesHandler(next http.Handler, opts *TangramJSOptions) http.Handler
• type NextzenOptions
  • func DefaultNextzenOptions() *NextzenOptions
• type TangramJSOptions
  • func DefaultTangramJSOptions() *TangramJSOptions

Constants

const NEXTZEN_MVT_ENDPOINT string = "https://tile.nextzen.org/tilezen/vector/v1/512/all/{z}/{x}/{y}.mvt"

NEXTZEN_MVT_ENDPOINT is the default endpoint for Nextzen vector tiles

Functions

func AppendAssetHandlers

func AppendAssetHandlers(mux *http.ServeMux, opts *TangramJSOptions) error

Append all the files in the net/http FS instance containing the embedded Tangram.js assets to an *http.ServeMux instance.

func AppendResourcesHandler

func AppendResourcesHandler(next http.Handler, opts *TangramJSOptions) http.Handler

AppendResourcesHandler will rewrite any HTML produced by previous handler to include the necessary markup to load Tangram.js files and related assets.

Types

type NextzenOptions

type NextzenOptions struct {
	// A valid Nextzen developer API key
	APIKey string
	// The URL for a valid Tangram.js style.
	StyleURL string
	// The URL template to use for fetching Nextzen map tiles.
	TileURL string
}

NextzenOptions provides configuration variables for Nextzen map tiles.

func DefaultNextzenOptions

func DefaultNextzenOptions() *NextzenOptions

Return a *NextzenOptions struct with default values.

type TangramJSOptions

type TangramJSOptions struct {
	// A list of Tangram.js Javascript files to append to HTML resources.
	JS []string
	// A list of Tangram.js CSS files to append to HTML resources.
	CSS []string
	// A NextzenOptions instance.
	NextzenOptions *NextzenOptions
	// A leaflet.LeafletOptions instance.
	LeafletOptions *leaflet.LeafletOptions
	// AppendJavaScriptAtEOF is a boolean flag to append JavaScript markup at the end of an HTML document
	// rather than in the <head> HTML element. Default is false
	AppendJavaScriptAtEOF bool
	RollupAssets          bool
	Prefix                string
	Logger                *log.Logger
	// By default the go-http-tangramjs package will also include and reference Leaflet.js resources using the aaronland/go-http-leaflet package. If you want or need to disable this behaviour set this variable to false.
	AppendLeafletResources bool
	// By default the go-http-tangramjs package will also include and reference Leaflet.js assets using the aaronland/go-http-leaflet package. If you want or need to disable this behaviour set this variable to false.
	AppendLeafletAssets bool
}

TangramJSOptions provides a list of JavaScript and CSS link to include with HTML output as well as options for Nextzen tiles and Leaflet.js.

func DefaultTangramJSOptions

func DefaultTangramJSOptions() *TangramJSOptions

Return a *TangramJSOptions struct with default values.