iv-org-mirror/shard-kemal
1
0
Fork 0
mirror of https://gitea.invidious.io/iv-org/shard-kemal.git synced 2024-08-15 00:53:36 +00:00
Code Issues Projects Releases Packages Wiki Activity

Remove docs

Browse source
This commit is contained in:
Sdogruyol 2016-01-06 22:00:17 +02:00
parent 2503bc4e3d
commit 265bfb1db2
13 changed files with 1 additions and 404 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -32,7 +32,7 @@ crystal run src/kemal_sample.cr
``` ```
Go to *http://localhost:3000* Go to *http://localhost:3000*
Check [documentation](https://github.com/sdogruyol/kemal/tree/master/docs) or [samples](https://github.com/sdogruyol/kemal/tree/master/samples) for more. Check [documentation](https://serdardogruyol.com/kemal) or [samples](https://github.com/sdogruyol/kemal/tree/master/samples) for more.
# Super Fast <3 # Super Fast <3

33
docs/README.md
View file

@ -1,33 +0,0 @@
# Kemal Documentation
This README includes documentation of Kemal, the Crystal Web Framework.
## What is Kemal?
Kemal is a micro web framework written in Crystal language. It's strongly inspired from [Sinatra](www.sinatrarb.com).
## What is Crystal?
Crystal is a programming language based on *Ruby* syntax.
## Advantages of using Kemal
- Easy to learn and start to develop.
- Since it's working on LLVM, it's too fast.
- Easy deployment to *Heroku*.
## The Name
Kemal means *Mature, grown up* in Turkish.
## How to start?
- [Getting Started Tutorial](./getting_started.md)
- [Restful Web Services](./rest.md)
- [Websockets](./websockets.md)
- [Using Dynamic Views](./views.md)
- [HTTP Requests and Responses](./http-requests.md)
- [Serving Static Files](./statics.md)
- [Serving JSON API](./json.md)
- [Middlewares](./middlewares.md)
- [Connecting to Database](./database.md)

11
docs/database.md
View file

@ -1,11 +0,0 @@
# Database Connection
Kemal supports database connection in an easy and extensible way. Kemal uses
a connection pool to handle all the connections meaning it's scalable by default.
Currently Kemal supports Postgresql and MySQL with:
- [kemal-pg](https://github.com/sdogruyol/kemal-pg)
- [kemal-mysql](https://github.com/sdogruyol/kemal-mysql)
You can check the relevant repo for samples and more info.

85
docs/getting_started.md
View file

@ -1,85 +0,0 @@
# Kemal Tutorial
## 1. Install Crystal
```
brew update
brew install crystal-lang
```
## 2. Installing Kemal
You should create your application first:
```
crystal init app your_app
cd your_app
```
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
```
It will output something like that:
```
$ shards install
Updating https://github.com/sdogruyol/kemal.git
Installing kemal (master)
```
## 3. Include Kemal into your project
Open `your_app/src/your_app.cr` and require `kemal` to use Kemal.
```ruby
require "kemal"
```
## 4. Hack your project
Do some awesome stuff with awesome Kemal.
```ruby
get "/" do
"Hello World!"
end
```
All the code should look like this:
```ruby
require "kemal"
get "/" do
"Hello World!"
end
```
## 5. Run your awesome web project.
```
crystal build --release src/your_app.cr
./your_app
```
You should see some logs like these:
```
[development] Kemal is ready to lead at http://0.0.0.0:3000
2015-12-01 13:47:48 +0200 | 200 | GET / - (666µs)
2015-12-05 13:47:48 +0200 | 404 | GET /favicon.ico - (14µs)
```
Now you can be happy with your new, very fast, readable web project.

39
docs/http-requests.md
View file

@ -1,39 +0,0 @@
# HTTP Request / Response Lifecycle
Accessing the HTTP request/response environment (query params, body, content_type, headers, status_code) is super easy. You can use the environment returned from the block:
```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
View file

@ -1,16 +0,0 @@
# Serving JSON API
You need to return a ```JSON``` object or need to convert the existing object via `to_json`.
```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
```

36
docs/middlewares.md
View file

@ -1,36 +0,0 @@
# Middlewares
## Built-in Middlewares
Kemal has built-in middlewares for common use cases.
### HTTP Basic Authorization
This middleware lets you add HTTP Basic Authorization to your Kemal application.
You can easily use this middleware with `basic_auth` macro like below.
```crystal
require "kemal"
basic_auth "username", "password"
get "/" do
"This won't render without correct username and password."
end
```
## Custom middlewares
You can create your own middleware by inheriting from ```HTTP::Handler```
```crystal
class CustomHandler < HTTP::Handler
def call(request)
puts "Doing some custom stuff here"
call_next request
end
end
Kemal.config.add_handler CustomHandler.new
```

25
docs/rest.md
View file

@ -1,25 +0,0 @@
# 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
```

15
docs/static_files.md
View file

@ -1,15 +0,0 @@
## Static Files
Kemal has built-in support for serving your static files. You need to put your static files under your ```/public``` directory.
E.g: A static file like ```/public/index.html``` will be served with the matching route ```/index.html```.
## Production / Development Mode
By default Kemal starts in ```development```mode and logs to STDOUT.
You can use ```production``` mode to redirect the output to a file. By default Kemal logs the output to ```kemal.log```.
You can start Kemal in production mode by:
```./your_app -e production```

31
docs/statics.md
View file

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

19
docs/utilities.md
View file

@ -1,19 +0,0 @@
# Browser Redirect
Just like other things in `kemal`, browser redirection is super simple as well. Use `environment` variable in defined route's corresponding block and call `redirect` on it.
```ruby
# Redirect browser
get "/logout" do |env|
# important stuff like clearing session etc.
redirect "/login" # redirect to /login page
end
```
_Make sure to receive `env` as param in defined route's block or you might end-up having compile-time errors._
# Custom Public Folder
Kemal mounts `./public` root path of the project as the default public asset folder. You can change this by using `public_folder`.
```ruby
public_folder "path/to/your/folder"
```

57
docs/views.md
View file

@ -1,57 +0,0 @@
# Views
You can use ERB-like built-in **ECR** views to render files.
```crystal
get '/:name' do
render "views/hello.ecr"
end
```
And you should have an `hello.ecr` view. It will have the same context as the method.
```erb
Hello <%= env.params["name"] %>
```
## Using Layouts
You can use **layouts** in Kemal. You should pass a second argument.
```crystal
get '/:name' do
render "views/subview.ecr", "views/layouts/layout.ecr"
end
```
And you should use `content` variable (like `yield` in Rails) in layout file.
```erb
<html>
<head>
<title><%= $title %></title>
</head>
<body>
<%= content %>
</body>
</html>
```
## Using Common Paths
Since Crystal does not allow using variables in macro literals, you need to generate
another *helper macro* to make the code easier to read and write.
```crystal
macro my_renderer(filename)
render "my/app/view/base/path/#{{{filename}}}.ecr", "my/app/view/base/path/layouts/layout.ecr"
end
```
And now you can use your new renderer.
```crystal
get '/:name' do
my_renderer "subview"
end
```

36
docs/websockets.md
View file

@ -1,36 +0,0 @@
# Using Websockets
Using Websockets is super easy! By nature Websockets are a bit different than standard Http Request/Response lifecycle.
You can easily create a websocket handler which matches the route of `ws://host:port/route. You can create more than 1 websocket handler
with different routes.
```ruby
ws "/" do |socket|
end
ws "/route2" do |socket|
end
```
Let's access the socket and create a simple echo server.
```ruby
# Matches "/"
ws "/" do |socket|
# Send welcome message to the client
socket.send "Hello from Kemal!"
# Handle incoming message and echo back to the client
socket.on_message do |message|
socket.send "Echo back from server #{message}"
end
# Executes when the client is disconnected. You can do the cleaning up here.
socket.on_close do
puts "Closing socket"
end
end
```