mirror of
https://gitea.invidious.io/iv-org/shard-kemal.git
synced 2024-08-15 00:53:36 +00:00
Remove docs
This commit is contained in:
Sdogruyol
parent
2503bc4e3d
commit
265bfb1db2
13 changed files with 1 additions and 404 deletions
|
|
@ -32,7 +32,7 @@ crystal run src/kemal_sample.cr
|
|||
```
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
16
docs/json.md
|
|
@ -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
|
||||
|
||||
```
|
||||
|
|
@ -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
25
docs/rest.md
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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```
|
||||
|
|
@ -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>
|
||||
```
|
||||
|
|
@ -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"
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
Loading…
Reference in a new issue