diff --git a/README.md b/README.md index 1dbf561..3f93d6d 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 026db01..0000000 --- a/docs/README.md +++ /dev/null @@ -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) diff --git a/docs/database.md b/docs/database.md deleted file mode 100644 index 3894a27..0000000 --- a/docs/database.md +++ /dev/null @@ -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. diff --git a/docs/getting_started.md b/docs/getting_started.md deleted file mode 100644 index 0d9c4da..0000000 --- a/docs/getting_started.md +++ /dev/null @@ -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. diff --git a/docs/http-requests.md b/docs/http-requests.md deleted file mode 100644 index 1e21e36..0000000 --- a/docs/http-requests.md +++ /dev/null @@ -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 diff --git a/docs/json.md b/docs/json.md deleted file mode 100644 index 7eb91f4..0000000 --- a/docs/json.md +++ /dev/null @@ -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 - -``` diff --git a/docs/middlewares.md b/docs/middlewares.md deleted file mode 100644 index d890d4a..0000000 --- a/docs/middlewares.md +++ /dev/null @@ -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 -``` diff --git a/docs/rest.md b/docs/rest.md deleted file mode 100644 index e34ccdd..0000000 --- a/docs/rest.md +++ /dev/null @@ -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 -``` diff --git a/docs/static_files.md b/docs/static_files.md deleted file mode 100644 index d4d1b2c..0000000 --- a/docs/static_files.md +++ /dev/null @@ -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``` diff --git a/docs/statics.md b/docs/statics.md deleted file mode 100644 index e4e8193..0000000 --- a/docs/statics.md +++ /dev/null @@ -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 - - - - - - - - ... - - -``` diff --git a/docs/utilities.md b/docs/utilities.md deleted file mode 100644 index c6dc9db..0000000 --- a/docs/utilities.md +++ /dev/null @@ -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" -``` diff --git a/docs/views.md b/docs/views.md deleted file mode 100644 index f30f072..0000000 --- a/docs/views.md +++ /dev/null @@ -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 - - - <%= $title %> - - - <%= content %> - - -``` - -## 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 -``` diff --git a/docs/websockets.md b/docs/websockets.md deleted file mode 100644 index 14a9bef..0000000 --- a/docs/websockets.md +++ /dev/null @@ -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 -```