![Gitter](https://badges.gitter.im/Join Chat.svg)
Modular web framework for Elixir
Please note that ecto
and postgrex
have been removed from Sugar's dependencies as of version 0.5.0. If your application uses Ecto, you'll need to add it to your application's mix.exs
, like so:
def project do
[ app: :my_app,
# ...
deps: deps() ]
end
def deps do
[ {:sugar, "~> 0.5.0"},
{:ecto, "~> 2.1"},
{:postgrex, "~> 0.13.0"} ]
end
Why build this when Dynamo, Weber, and Phoenix exist with growing communities? While these projects are great in their own right, Sugar aims to be another contender, sparking more development on all three projects (and/or others that may follow) and giving developers another option when deciding what framework fits their needs best. Sugar may even strive to shake things up just as ChicagoBoss has done.
# Clone this repo
git clone https://github.com/sugar-framework/simple.git
cd simple
# Get project dependencies
mix deps.get
# Start the web server
mix server # or `iex -S mix server` if you want access to iex
Sugar needs to be configured in your application's config/config.exs
in order to work. The following options are supported:
config :sugar, router: MyWebsite.Router
Tells Sugar which module to use as a router. This module should implement Sugar.Router
, and should have at least one route defined. This is required.
config :sugar, plug_adapter: Plug.Adapters.Cowboy
Tells Sugar which web server to use to handle HTTP(S) requests. Cowboy is currently the only supported option, and Sugar will default to using Plug.Adapters.Cowboy
if this is omitted.
config :sugar, MyWebsite.Router, ...
Tells Sugar how the specified router should be configured. The following options are supported:
http
: takes a key/value list with options to configure the specified :plug_adapter
. Of particular usefulness:
ip
: IP address the server should bind to. Should be a tuple in the format {x,y,z,w}
. Defaults to accepting connections on any IP address.port
: port the server should listen on. Defaults to 4000.acceptors
: the number of acceptors for the listener. Defaults to 100.max_connections
: the maximum number of connections supported. Defaults to :infinity
.compress
: whether or not the bodies of responses should be compressed. Defaults to false
.https
: takes a key/value list with the same options as http
, or can be set to false
if you don't want to enable HTTPS. The following additional options(along with others from Erlang's "ssl" module) are supported:
password
: a plaintext, secret password for the private SSL key (if it's password-protected)keyfile
: path to the PEM-format private key file to usecertfile
: path to the PEM-format certificate to useotp_app
- If present, certfile
and keyfile
can be relative paths with respect to otp_app
's priv
directory.Note: Create a self-signed certificate for easy HTTPS testing.
# Generate a keyfile $ openssl genrsa -out key.pem 2048 # Create a CSR $ openssl req -new -key key.pem -out request.pem # Generate a certfile that expires in $NUM_DAYS $ openssl x509 -req -days $NUM_DAYS -in request.pem -signkey key.pem -out cert.pem
use Mix.Config
config :sugar, router: MyWebsite.Router
config :sugar, MyWebsite.Router,
http: [
port: 80
],
https: [
port: 443,
password: "OMG_SUPER_SECRET",
keyfile: "/path/to/key.pem",
certfile: "/path/to/cert.pem"
]
Because Sugar builds upon Plug, it leverages Plug.Router
to do the heavy lifting in routing your application, adding an alternate DSL.
Routes are defined with the form:
method route [guard], controller, action
method
is get
, post
, put
, patch
, delete
, or options
, each responsible for a single HTTP method. method
can also be any
, which will match on all HTTP methods. controller
is any valid Elixir module name, and action
is any valid function defined in the controller
module.
defmodule MyWebsite.Router do
use Sugar.Router
get "/", Hello, :index
get "/pages/:id", Hello, :show
post "/pages", Hello, :create
put "/pages/:id" when id == 1, Hello, :show
end
All controller actions should have an arrity of 2, with the first argument being a Plug.Conn
representing the current connection and the second argument being a Keyword
list of any parameters captured in the route path.
Sugar bundles these response helpers to assist in sending a response:
render/2
- sends a normal responsenot_found/1
- sends a 404 (Not found) responsedefmodule MyWebsite.Controllers.Hello do
use Sugar.Controller
def index(conn, []) do
render conn, "index.html.eex", []
end
def show(conn, args) do
render conn, "show.html.eex", args
end
def create(conn, []) do
render conn, "create.html.eex", []
end
end
Why, the contributors, of course! Would you consider being one? Please send a pull request :)
The main product of this repository is the example terms in the file CONTRIBUTING.md. This project uses those guidelines as the basis for its own development process. Please refer to that file.
Sugar is released under the MIT License.
See LICENSE for details.