└── README.md /README.md: -------------------------------------------------------------------------------- 1 | Humble 2 | ====== 3 | 4 | Humble is a collection of loosely-coupled tools designed to build client-side 5 | and hybrid web applications using go and 6 | [gopherjs](https://github.com/gopherjs/gopherjs). 7 | 8 | Humble is designed for writing front-end code, and is entirely back-end 9 | agnostic. You can use Humble in combination with any back-end server written in 10 | any language. If you do choose to write your back-end in go as well, Humble 11 | offers some tools to make it easy to share code between the server and browser. 12 | 13 | This repository contains no code, but serves as an introduction to Humble and a 14 | central place for creating new issues and feature requests that are not related 15 | to any specific sub-package. 16 | 17 | How it Works 18 | ------------ 19 | 20 | Humble allows you to write front-end code in pure go, which you can then 21 | compile to javascript with [gopherjs](https://github.com/gopherjs/gopherjs) and 22 | run in the browser. Humble is pure go. It feels like go, compiles with the 23 | standard go tools, and follows go idioms when possible. 24 | 25 | [GopherJS](https://github.com/gopherjs/gopherjs) supports all the main features 26 | of the go language, including goroutines and channels. Most of the standard 27 | library is also supported (see the 28 | [compatibility table](https://github.com/gopherjs/gopherjs/blob/master/doc/packages.md)). 29 | 30 | 31 | Why Write Client-Side Code in Go? 32 | --------------------------------- 33 | 34 | Ultimately, Humble is not for everyone and may not be suitable for all projects. 35 | Many developers will be perfectly happy writing front-end code in javascript, 36 | and the javascript ecosystem is vast and thriving. It is not our goal to replace 37 | javascript or convince every developer to switch. However, we recognize that 38 | javascript is not everyone's favorite language, and Humble offers developers, 39 | especially those already familiar with go, a viable alternative. 40 | 41 | Go offers several benefits over javascript for writing client-side code: 42 | 43 | 1. **Built-In Type-Safety**. Go is a type-safe, compiled language which means 44 | that certain classes of mistakes can be caught before you even run your code. 45 | It also makes it possible for text editors to do static analysis and more 46 | intelligent autocomplete, increasing your productivity. While projects like 47 | [TypeScript](http://www.typescriptlang.org/) exist, go offers type-safety as 48 | a core feature, and *all* go code, whether part of the standard library or a 49 | third-party package, supports it. 50 | 2. **Robust Standard Library**. Go comes with an incredibly robust 51 | [standard library](https://golang.org/pkg/), and almost all of it is 52 | supported in gopherjs (see 53 | the [compatibility table](https://github.com/gopherjs/gopherjs/blob/master/doc/packages.md)). 54 | 3. **The Ability to Build Hybrid Applications**. If you already have a server 55 | written in go, you can use Humble to write the front-end in go too. Having 56 | your entire codebase in one language reduces cognitive load and increases 57 | maintainability. It is even possible to share code between the server and 58 | browser, just like you can with javascript and node.js. 59 | 4. **Sane Concurrency Patterns**. Go is one of few modern languages to implement 60 | [CSP concurrency patterns](https://en.wikipedia.org/wiki/Communicating_sequential_processes). 61 | Goroutines and channels offer an intuitive and standardized way to deal with 62 | concurrency and asynchronous code, and are fully supported in gopherjs. 63 | 5. **Phenomenal Tooling**. Go offers some of the best tooling of any modern 64 | language. There is standardized documentation on 65 | [godoc.org](http://godoc.org/), builtin 66 | [testing, benchmarking](http://golang.org/pkg/testing/), and 67 | [profiling](http://blog.golang.org/profiling-go-programs), and even tools for 68 | [detecting race conditions](http://blog.golang.org/race-detector) and 69 | [displaying test coverage](https://blog.golang.org/cover). 70 | 71 | 72 | Development Status 73 | ------------------ 74 | 75 | Humble is brand new and is under active development. 76 | 77 | All sub-packages are well-tested and are even tested in real browsers when 78 | applicable. We do our best to respond to critical issues as quickly as possible. 79 | As such, Humble can be considered safe for use in side-projects, experiments, 80 | and non-critical production applications. At this time, we do not recommend 81 | using Humble for critical production applications. 82 | 83 | Humble uses semantic versioning, but offers no guarantees of backwards 84 | compatibility until version 1.0. It is likely that the API will change 85 | significantly as new issues are discovered and new features are added. As such, 86 | we recommend using a dependency tool such as 87 | [godep](https://github.com/tools/godep) to ensure that your code does not break 88 | unexpectedly. 89 | 90 | 91 | Packages 92 | -------- 93 | 94 | In contrast with front-end javascript frameworks such as Angular and Ember, 95 | Humble is much more conservative. It doesn't enforce any kind of structure on 96 | your applications, but tries to provide all the tools you need for the most 97 | common use cases. The packages that make up Humble are loosely-coupled, which 98 | means they work well together but can be used separately too. Humble can be 99 | used with [gopherjs bindings](https://github.com/gopherjs/gopherjs/wiki/bindings), 100 | such as [jQuery](https://github.com/gopherjs/jquery). It is even possible to 101 | use Humble together 102 | [with existing javascript code](https://github.com/gopherjs/gopherjs#interacting-with-the-dom). 103 | 104 | ### [Detect](https://github.com/go-humble/detect) 105 | 106 | Detect is a tiny go package for detecting whether code is running on the server 107 | or browser. It is intended to be used in hybrid go applications. 108 | 109 | ### [Examples](https://github.com/go-humble/examples) 110 | 111 | Examples contains several examples of how to use Humble to build real 112 | applications. 113 | 114 | ### [Form](https://github.com/go-humble/form) 115 | 116 | Form is a package for validating and serializing html forms in the browser. It 117 | supports a variety of validations on form inputs and binding forms to arbitrary 118 | go structs. 119 | 120 | ### [Locstor](https://github.com/go-humble/locstor) 121 | 122 | Locstor provides localStorage bindings. In addition to being able to interact 123 | with the localStorage API directly, you can create a DataStore object for 124 | storing and retrieving arbitrary go data structures, not just strings. 125 | 126 | ### [Rest](https://github.com/go-humble/rest) 127 | 128 | Rest is a small package for sending requests to a RESTful API and unmarshaling 129 | the response. Rest sends requests using CRUD semantics. It supports requests 130 | with a Content-Type of either application/x-www-form-urlencoded or 131 | application/json and parses json responses from the server. 132 | 133 | ### [Router](https://github.com/go-humble/router) 134 | 135 | Router is an easy-to-use router which runs in the browser. It supports url 136 | parameters and uses history.pushState, gracefully falling back to url hashes 137 | if needed. 138 | 139 | ### [Temple](https://github.com/go-humble/temple) 140 | 141 | Temple is a library and a command line tool for sanely managing go templates, 142 | with the ability to share them between the server and browser. 143 | 144 | ### [View](https://github.com/go-humble/view) 145 | 146 | View is a small package for organizing view-related code. View includes a View 147 | interface and some helper functions for operating on views (e.g. Append, 148 | Replace, Remove, etc.). 149 | 150 | 151 | Where is the Old Code? 152 | ---------------------- 153 | 154 | If you're looking for the files that used to be in this repository, they have 155 | all been moved to stand-alone packages. Check out the 156 | [Go-Humble Organization Page](https://github.com/go-humble) on github to view 157 | all the packages! 158 | --------------------------------------------------------------------------------