README
¶
GoRADD
A rapid Web application development framework for Go.
GoRADD is a monolithic web development framework for rapidly creating a web application from a concept in your mind and then allowing you to as easily as possible maintain that application through all the twists and turns of the change process. It is ideal for prototyping, intranet websites, websites that are very data intensive with many forms to gather information from users, websites that require the security and speed of a compiled language, websites with thousands of simultaneous users, and websites being maintained by one or a small group of developers. It is particularly good for developers new to GO and/or new to web development.
Installation
See the Quick Start guide to get started.
Requirements
- Go 1.21 or greater
- A supported database up and running on your local development computer.
Current supported databases are:
- Mysql
- Postgres
For Developing GoRADD itself
- Sass (to build the css files from the scss source)
Goals
- 80-20 rule, where out of the box GoRADD will do most of the hard work of building a website, and will quickly get you a working website, but not necessarily one that you will want to ship. GoRADD is architected to allow you to make changes and plug in other open-source software as you need.
- Incremental changes. Most development processes go through a lengthy requirement analysis process, followed by a design process, and a lengthy build process, only to find out that what you built wasn't really what was needed. Instead, GoRADD gets you a working website quickly, and then lets you build out your application incrementally. It tries to make it easy to restructure your website, even at the data structure level, and have your changes filter through your application quickly without requiring a complete rewrite.
- Layered development. GoRADD has its code, you have your code, and then there is an in-between interface that changes over time. GoRADD uses code generation to create this interface, and clearly delineates the code that you can change to modify the interface, vs. code that it will generate as you change your data model. The result is a product that is easy to change as your world and requirements change.
- Most development happens in GO. What the user does in the browser is mirrored on the server, which allows you to work in a way that feels like you are building a desktop application. This makes your developers more productive and it allows you to build your app using common GO tools like the built-in unit test environment and documentation server. You can still work in javascript if you want to or need to do custom UI work, but often you don't have to.
- Stability. We want to build applications that real people use, and that means reliance on tried and true technologies that work on a broad range of browsers and servers, rather than technologies that require lots of Polyfills for emerging standards.
- Progressive enhancement. If you use the provided widgets, you can create a website that works even if the client turns off Javascript. All major browsers are currently supported, but we hope to support Opera Mini as well.
- Rich libraries of widgets. GoRADD provides standard widgets corresponding to basic html controls, and also provides Bootstrap widgets. If you have a particular css or javascript widget library you want to support, building the GoRADD interface is fairly easy to do, and the Bootstrap library included gives you a model to follow.
- Scalability. GoRADD is architected for scalability. All user state information is serializable
to key-value stores. You might need to build the interface to the particular key-value store you
are interested in, but that is not difficult. Some specific issues to consider:
- GoRADD requires a MySQL or Postgres database at this point for your main data store. SQL is great for creating most common data structures, is great when you need to change your structure without destroying data, and is fast enough for most applications. However, all data access is done through a common API, so switching an application that is already written to another SQL database like Postgres, Oracle, or any other database is very straight-forward and is just a matter of implementing the database layer.
- GoRADD maintains the state of each user of the website in something we call the pagestate. The pagestate is serializable to any key-value store. Currently, only an in-memory store is provided, but writing an interface to any common key-value store is easy.
- Live updates work through a pub/sub mechanism. Goradd provides a single-server in-memory system out of the box, but its easy to switch to any other pub/sub mechanism, including distributed systems like pubnub, ally, google cloud messaging, etc. There are no payloads with the messages and traffic is minimal.
Future Goals
- Expand database drivers, including NoSQL support
- WebComponents. WebComponent architecture fits particularly well with goradd's architecture. However, WebComponents are not fully supported by all major browsers. As WebComponents gain traction, we hope to use them for future browser widgets.
- Automated generation of a REST Api, including generation of Flutter client code.
Anti-patterns
- GoRADD's html server is not microservice based. While you can create microservices that serve parts of your application, at its core goradd is a monolithic framework that includes an ORM, an MVC architecture, and a basic control and form management library. That said, GoRADD is still very scalable.
- Object-oriented. Some of goradd uses a code pattern that mirrors traditional object-oriented inheritance and gets around some of GO's limitations in this area, including implementing virtual functions. We have found this particularly useful in the control library. If you hate inheritance, goradd is not for you. If you don't mind it, but you still like object composition too, this is your place.
- Code generation. GoRADD relies heavily on code generation, and in particular uses the related github.com/goradd/got template engine to generate code.
Acknowledgements
GoRADD is a port of the PHP framework QCubed. QCubed itself was a fork of the PHP framework written by Mike Ho called QCodo. Mike is the original mastermind of many of the concepts in GoRADD, like:
- A code-generated ORM
- The use of "nodes" to describe database entities AND the relationships between them.
- Code-generated CRUD forms to get you started.
- Scaffolding that separates code-generated code from developer code so that code-generation can continue throughout the life of the project.
- A lightweight javascript layer for processing events and actions through ajax.
- The formstate engine to mirror the state of html and javascript widgets on the server-side so that the server-side engineer has complete control over what is happening in the html without needing to write javascript.
GoRADD relies on a number of other open-source projects, including:
- Alex Edward's SCS Session Manager Library
- Akeda Bagus' Inflector Library
- Gorilla's Websocket Library
- Kenneth Shaw's Snaker Library
- Stretchr's testing library Testify
- Andy Balholm's Brotli Library
- Microcosm's injection prevention library Blue Monday
- Russ Ross's Markdown library Black Friday
GoRADD was created and is maintained by Shannon Pekary
Thanks To
JetBrains for use of the GoLand Go Editor
BrowserStack for automated browser testing tools
Documentation
¶
Overview ¶
GoRADD is a framework for rapid development of websites and API servers. See the Readme for details and instructions to get started.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
codegen
|
|
|
Package doc contains documentation as Markdown files.
|
Package doc contains documentation as Markdown files. |
|
The ideas package contains code that is not being used, but that we might use some day and include, but right now we don't want to support it.
|
The ideas package contains code that is not being used, but that we might use some day and include, but right now we don't want to support it. |
|
internal
|
|
|
ci
Package ci contains the code performed by the continuous-integration tests
|
Package ci contains the code performed by the continuous-integration tests |
|
install/goradd-project/api
Package api is an example of a REST type api and associated handlers.
|
Package api is an example of a REST type api and associated handlers. |
|
install/goradd-project/config
Package config is the place to setup global variables and constants that impact site-wide behavior.
|
Package config is the place to setup global variables and constants that impact site-wide behavior. |
|
install/goradd-project/control
Package control contains custom controls and modifications of standard controls that are used throughout the site.
|
Package control contains custom controls and modifications of standard controls that are used throughout the site. |
|
install/goradd-project/gen
Package gen contains the code generated database model, forms and panels that make up the initial website generated from the database.
|
Package gen contains the code generated database model, forms and panels that make up the initial website generated from the database. |
|
install/goradd-project/tmp/template
The template package contains generated templates from the pre-generation process for codegen.
|
The template package contains generated templates from the pre-generation process for codegen. |
|
install/goradd-project/web/app
Package app contains your local application object.
|
Package app contains your local application object. |
|
install/goradd-project/web/form
Package form is a place for you to put your application's forms.
|
Package form is a place for you to put your application's forms. |
|
install/goradd-project/web/panel
Package panel is a place for you to put your application's panels.
|
Package panel is a place for you to put your application's panels. |
|
pkg
|
|
|
any
Package any has general purpose utility functions for working with interfaces and generic types.
|
Package any has general purpose utility functions for working with interfaces and generic types. |
|
api
Package api gives you a default pattern for registering an API, like a REST API, to be served by the app.
|
Package api gives you a default pattern for registering an API, like a REST API, to be served by the app. |
|
auth
Package auth provides one possible authentication framework based on username and password.
|
Package auth provides one possible authentication framework based on username and password. |
|
base
Package base describes the Base struct, which provides virtual functions and inheritance similar to that of C++ and Java.
|
Package base describes the Base struct, which provides virtual functions and inheritance similar to that of C++ and Java. |
|
bootstrap
Package bootstrap is an add-on module that contains bootstrap controls, static files, examples, etc.
|
Package bootstrap is an add-on module that contains bootstrap controls, static files, examples, etc. |
|
bootstrap/control
Package control contains the Bootstrap control structures that when added to a page will result in Bootstrap styled controls.
|
Package control contains the Bootstrap control structures that when added to a page will result in Bootstrap styled controls. |
|
config
Package config contains configurable default values for various aspects of goradd.
|
Package config contains configurable default values for various aspects of goradd. |
|
http
Package http contains utilities to support traditional http server output and middleware from the goradd server.
|
Package http contains utilities to support traditional http server output and middleware from the goradd server. |
|
i18n
The i18n package provides support services for translation of goradd web pages and widgets.
|
The i18n package provides support services for translation of goradd web pages and widgets. |
|
javascript
Package javascript converts go objects and types to javascript code, suitable for embedding in html or sending to the browser via a specialized ajax call.
|
Package javascript converts go objects and types to javascript code, suitable for embedding in html or sending to the browser via a specialized ajax call. |
|
log
Package log provides logging support for your application and the goradd framework developers.
|
Package log provides logging support for your application and the goradd framework developers. |
|
math
Package math contains number utilities that are not included in the Go math library, but that are useful.
|
Package math contains number utilities that are not included in the Go math library, but that are useful. |
|
messageServer
Package messageServer implements a general purpose messaging platform based on the gorilla websocket implementation.
|
Package messageServer implements a general purpose messaging platform based on the gorilla websocket implementation. |
|
orm/db
Package db works with the rest of the orm to interface between a database and the ORM abstraction of reading and querying a database.
|
Package db works with the rest of the orm to interface between a database and the ORM abstraction of reading and querying a database. |
|
orm/db/sql
Package sql contains helper functions that connect a standard Go database/sql object to the GoRADD system.
|
Package sql contains helper functions that connect a standard Go database/sql object to the GoRADD system. |
|
orm/op
The op package contains operation and aggregation nodes that can be added to a QueryBuilder.
|
The op package contains operation and aggregation nodes that can be added to a QueryBuilder. |
|
orm/query
The query package primarily contains code used internally by the framework to build queries.
|
The query package primarily contains code used internally by the framework to build queries. |
|
page
Package page is the user-interface layer of goradd, and implements state management and rendering of an html page, as well as the framework for rendering controls.
|
Package page is the user-interface layer of goradd, and implements state management and rendering of an html page, as well as the framework for rendering controls. |
|
page/action
Package action defines actions that you can trigger using events.
|
Package action defines actions that you can trigger using events. |
|
page/control
Package control contains implementations of standard HTML controls in GoRADD.
|
Package control contains implementations of standard HTML controls in GoRADD. |
|
page/control/button
Package button includes button and button-like controls that are clickable, including things that toggle.
|
Package button includes button and button-like controls that are clickable, including things that toggle. |
|
page/control/dialog
Package dialog contains dialog controls.
|
Package dialog contains dialog controls. |
|
page/control/generator
Package generator contains helper objects to describe controls to the code generator so that they can generate customizable data connectors that associate controls with data in the database.
|
Package generator contains helper objects to describe controls to the code generator so that they can generate customizable data connectors that associate controls with data in the database. |
|
page/control/list
Package list contains list-type controls.
|
Package list contains list-type controls. |
|
page/control/table
Package table implements various table controls.
|
Package table implements various table controls. |
|
page/control/textbox
Package textbox implements textbox-like form controls.
|
Package textbox implements textbox-like form controls. |
|
page/event
Package event contains functions that specify various kinds of javascript events that GoRADD controls respond to.
|
Package event contains functions that specify various kinds of javascript events that GoRADD controls respond to. |
|
page/widget
The widget package contains supported composite and special purpose controls that are not part of the html standard
|
The widget package contains supported composite and special purpose controls that are not part of the html standard |
|
session/location
Package location implements a location queue built on top of the session service.
|
Package location implements a location queue built on top of the session service. |
|
stringmap
Package stringmap contains utilities to handle common map operations
|
Package stringmap contains utilities to handle common map operations |
|
time
Package time has some utilities for time.Time values
|
Package time has some utilities for time.Time values |
|
url
package url contains url utilities beyond what is available in the net/url package
|
package url contains url utilities beyond what is available in the net/url package |
|
test
|
|
|
browsertest
Package test contains the test harness, which controls browser based tests.
|
Package test contains the test harness, which controls browser based tests. |
|
manualtest
Package manualtest contains tests of the framework that require manual setup or execution.
|
Package manualtest contains tests of the framework that require manual setup or execution. |
|
Package web contains the default web application that you can customize through the goradd-project/web package.
|
Package web contains the default web application that you can customize through the goradd-project/web package. |
|
app
Package app contains the default web application server.
|
Package app contains the default web application server. |
|
assets
Package assets contains the css and javascript required to run a goradd server.
|
Package assets contains the css and javascript required to run a goradd server. |
|
examples
Package examples contains the example and tutorial code for learning how to use GoRADD.
|
Package examples contains the example and tutorial code for learning how to use GoRADD. |
|
examples/controls
Package controls contains example pages that demonstrate how to set up and use various Goradd controls.
|
Package controls contains example pages that demonstrate how to set up and use various Goradd controls. |
|
examples/gen/goradd/model
Package model contains the ORM for objects for the goradd database.
|
Package model contains the ORM for objects for the goradd database. |
|
examples/tutorial
Package tutorial contains the tutorial for learning about GoRADD.
|
Package tutorial contains the tutorial for learning about GoRADD. |
Click to show internal directories.
Click to hide internal directories.