luna/kemal
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Merge pull request #22 from f/master

Browse source 
Add documentation.
This commit is contained in:
Serdar Dogruyol 2015-12-04 14:26:55 +02:00
commit 564cdcac0b
6 changed files with 204 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/README.md Normal file
View file

@ -0,0 +1,33 @@
# Kemal Documentation
This README includes documentation of Kemal, the Crystal Web Framework.
## What is Kemal?
Kemal is a web server working on Crystal language. Strongly inspired on Sinatra project.
_Needs more info_
## What is Crystal?
Crystal is a programming language based on *Ruby* syntax.
## Advantages of using Kemal
- Too easy to learn and start to develop.
- Since it's working on LLVM, it's too fast.
- You can deploy it on *Heroku*.
## The Name
Kemal means *Mature, grown up* in Turkish and Arabic.
## How to start?
- [Getting Started Tutorial](./tutorial.md)
- [Using Dynamic Templates (Not Supported Yet)](./templates.md)
- [Parsing HTTP requests and Form Data](./http-requests.md)
- [Uploading Files](./upload.md)
- [Serving Static Files](./statics.md)
- [Serving JSON API](./json.md)
- [Restful Web Services](./rest.md)
- [How to connect to Database](./database.md)

40
docs/http-requests.md Normal file
View file

@ -0,0 +1,40 @@
# HTTP Requests
You should use `env` variable to handle HTTP params. For both `get` and `post` (and others) methods, you should use `env` object.
```ruby
# Matches /hello/kemal
get "/hello/:name" do |env|
name = env.params["name"]
"Hello back to #{name}"
end
# Matches /resize?width=200&height=200
get "/resize" do |env|
width = env.params["width"]
height = env.params["height"]
end
# Easily access JSON payload from the params.
# The request content type needs to be application/json
# The payload
# {"name": "Serdar", "likes": ["Ruby", "Crystal"]}
post "/json_params" do |env|
name = env.params["name"] as String
likes = env.params["likes"] as Array
"#{name} likes #{likes.each.join(',')}"
end
# Set the content as application/json and return JSON
get "/user.json" do |env|
kemal = {name: "Kemal", language: "Crystal"}
env.content_type = "application/json"
kemal.to_json
end
# Add headers to your response
get "/headers" do |env|
env.add_header "Accept-Language", "tr"
env.add_header "Authorization", "Token 12345"
end
```

16
docs/json.md Normal file
View file

@ -0,0 +1,16 @@
# Serving JSON API
Just use `to_json` method to return.
```ruby
require "kemal"
require "json"
# You can easily access the context and set content_type like 'application/json'.
# Look how easy to build a JSON serving API.
get "/" do |env|
env.content_type = "application/json"
{name: "Serdar", age: 27}.to_json
end
```

25
docs/rest.md Normal file
View file

@ -0,0 +1,25 @@
# Restful Web Services
You can handle HTTP methods as easy as writing method names and the route with a code block. Kemal will handle all the hard work.
```
get "/" do
.. show something ..
end
post "/" do
.. create something ..
end
put "/" do
.. replace something ..
end
patch "/" do
.. modify something ..
end
delete "/" do
.. annihilate something ..
end
```

31
docs/statics.md Normal file
View file

@ -0,0 +1,31 @@
# Statics
Add your files to `public` directory and Kemal will serve these files immediately.
```
app/
src/
awesome_web_project.cr
public/
js/
jquery.js
awesome_web_project.js
css/
awesome_web_project.css
index.html
```
Open index.html and add
```html
<html>
<head>
<script src="/js/jquery.js"></script>
<script src="/js/awesome_web_project.js"></script>
<link rel="stylesheet" href="/css/awesome_web_project.css"/>
</head>
<body>
...
</body>
</html>
```

59
docs/tutorial.md Normal file
View file

@ -0,0 +1,59 @@
# Kemal Tutorial
## Install Crystal
```
brew update
brew install crystal-lang
```
## Installing Kemal
You should create your application first:
```
crystal init app awesome_web_project
cd awesome_web_project
```
Then add *kemal* to the `shard.yml` file as a dependency.
```yml
dependencies:
kemal:
github: sdogruyol/kemal
branch: master
```
You should run `shards` to get dependencies:
```
shards install
```
## Include Kemal into your project
Open `awesome_web_project/src/awesome_web_project.cr` and require `kemal` to use Kemal.
```ruby
require 'kemal'
```
## Hack your project
Do some awesome stuff with awesome Kemal.
```ruby
get "/" do
"Hello World!"
end
```
## Run your awesome web project.
```
crystal build --release src/awesome_web_project.cr
./awesome_web_project
```
Now you can be happy with your new, very fast, readable web project.