tangramjs

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 24, 2021 License: BSD-3-Clause Imports: 9 Imported by: 7

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 Reference

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"
	"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)
}

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()	
	tangramjs.AppendAssetHandlers(mux)

	// 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

	// 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...
}

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:

See also

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

View Source 
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

Variables

View Source 
var APPEND_LEAFLET_ASSETS = true

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.

View Source 
var APPEND_LEAFLET_RESOURCES = true

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.

Functions

func AppendAssetHandlers 

func AppendAssetHandlers(mux *http.ServeMux) error

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

func AppendAssetHandlersWithPrefix 

func AppendAssetHandlersWithPrefix(mux *http.ServeMux, prefix string) error

Append all the files in the net/http FS instance containing the embedded Tangram.js assets to an *http.ServeMux instance ensuring that all URLs are prepended with prefix.

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.

func AppendResourcesHandlerWithPrefix 

func AppendResourcesHandlerWithPrefix(next http.Handler, opts *TangramJSOptions, prefix string) http.Handler

AppendResourcesHandlerWithPrefix will rewrite any HTML produced by previous handler to include the necessary markup to load Tangram.js files and related assets ensuring that all URIs are prepended with a prefix.

func AssetsHandler 

func AssetsHandler() (http.Handler, error)

AssetsHandler returns a net/http FS instance containing the embedded Tangram.js assets that are included with this package.

func AssetsHandlerWithPrefix 

func AssetsHandlerWithPrefix(prefix string) (http.Handler, error)

AssetsHandler returns a net/http FS instance containing the embedded Tangram.js assets that are included with this package ensuring that all URLs are stripped of prefix.

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
}

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
example

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.