# Sugar
[![Build Status](https://img.shields.io/travis/sugar-framework/sugar.svg?style=flat)](https://travis-ci.org/sugar-framework/sugar)
[![Coverage Status](https://img.shields.io/coveralls/sugar-framework/sugar.svg?style=flat)](https://coveralls.io/r/sugar-framework/sugar)
[![Hex.pm Version](http://img.shields.io/hexpm/v/sugar.svg?style=flat)](https://hex.pm/packages/sugar)
[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/sugar-framework/sugar?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Modular web framework for Elixir
## Goals
- Speed. Sugar shouldn't be slow and neither should your project.
- Ease. Sugar should be simple because simple is easy to learn and use.
- Effective. Sugar should aid development. You have better things to which to devote your time.
## Reason for Existence
Why build this when [Dynamo](https://github.com/dynamo/dynamo), [Weber](http://elixir-web.github.io/weber/), and [Phoenix](https://github.com/phoenixframework/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](http://www.chicagoboss.org/) has done.
## Getting Started
```
# 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
```
### Configurations
Currently, Sugars expects a `Config` module to be defined in your project that has a `config/0` function defined for configuring your application. A simple `Keyword` list is returned with the configuration values.
Eventually, this will be replaced with a more elegant solution.
Valid options:
- `log` - `true|false` - turns logging on or off
- `server` - contains options to be sent to the underlying web server (currently, only [Cowboy](https://github.com/extend/cowboy))
- `ip` - the ip to bind the server to.
Must be a tuple in the format `{ x, y, z, w }`.
- `port` - the port to run the server.
Defaults to 4000 (http) and 4040 (https).
- `acceptors` - the number of acceptors for the listener.
Defaults to 100.
- `max_connections` - max number of connections supported.
Defaults to :infinity.
- `dispatch` - manually configure Cowboy's dispatch.
- `ref` - the reference name to be used.
Defaults to `plug.HTTP` (http) and `plug.HTTPS` (https).
This is the value that needs to be given on shutdown.
#### Example
```elixir
defmodule Config do
def config do
[
log: true,
server: [
port: 4000
]
]
end
end
```
### Routers
Because Sugar builds upon [Plug](https://github.com/elixir-lang/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.
#### Example
```elixir
defmodule 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
```
### Controllers
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 response
- `not_found/1` - sends a 404 (Not found) response
#### Example
```elixir
defmodule 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
```
## Todo Items
- basic authentication (?)
- Development error page
- Caching
- Compiled HTML
- Application Data
- Adapters
- ETS
## Who's behind this?
Why, the [contributors](https://github.com/sugar-framework/sugar/graphs/contributors), of course! Would you consider being one? Please send a pull request :)
## How to start contributing
The main product of this repository is the example terms in the file [CONTRIBUTING.md](https://github.com/sugar-framework/sugar/blob/master/CONTRIBUTING.md). This project uses those guidelines as the basis for its own development process. Please refer to that file.
## License
Sugar is released under the MIT License.
See [LICENSE](https://github.com/sugar-framework/sugar/blob/master/LICENSE) for details.