-
Notifications
You must be signed in to change notification settings - Fork 0
Getting Started
(The code for this demo is in github under demo/basic_example)
Kul is designed to be as simple as possible to start working with. Assuming you have ruby or JRuby installed, simply run gem install kul to install the Kul gem, and then create or find a likely folder to host your content and run kul server from that location. That will start the Kul server in development mode in the current directory.
Yeah, that's really it.
Let's make some content then! In the folder you started Kul, create a file named index.html and add this markup:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Kul simple example</title>
</head>
<body>
This is my Kul server!
</body>
</html>
Save the file and browse to localhost:4567 and observe that you've just built a web page. Feel free to modify and refresh - note that you don't have to restart the server in order to see changes.
Yay! We've just demonstrated what Apache could do in 1995! Okay, you want to see something more interesting.
In that same folder, create a file named test.html.erb and add the following markup:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Kul simple example</title>
</head>
<body>
Server time: <%= Time.now %>
</body>
</html>
A slight change from the first example, but here we go. Browse to localhost:4567/test.html - and you see the server time! We can now get rid of all the clocks in your house.
Don't actually do that. However, we have demonstrated the ability to create a file that runs Ruby code that gets turned into HTML. You could write a bunch of code that runs inside that erb file, that calls out to databases, loads gems, etc. You could even write common Ruby code and require that inside your erb to avoid reproducing code everywhere.
Let's try a slightly more complex example. Create a directory called foo in the Kul server directory. And inside that folder, add the following code to index.html.erb:
<%
def fact(n)
return 1 if n < 1
n * fact(n-1)
end
def fib(n)
return n if (0..1).include? n
fib(n-1) + fib(n-2) if n > 1
end
%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Kul simple example</title>
</head>
<body>
<% (1..10).each do |n| %>
<div>
The number <%= n %>!<br/>
Factorial: <%= fact n %> and fibonacci: <%= fib n %>
</div><br/>
<% end %>
</body>
</html>
Browsing to localhost:4567/foo, you can see the results of the computer doing math for us. Yay!
There are a couple of things of note here. Defined a couple of functions, did a loop - you can take those parts and run with them as far as you want. We've also demonstrated directories are reflected in the URL path. Those also can be run as deep as you like, although eventually it'd be a bit cumbersome. Also note that you can change the template and refresh and the changes are immediately visible.
So now we've got the Ruby equivalent of JSPs. We're up to 1999!
... I can tell that you're one of those programmers that wants more, aren't you? You want your MVC, and you want it NOW!
We've got your MVC right here. First we should talk about applications. Controllers are nested inside of applications. Don't worry about what an application is or how it works, we'll get to that later. Just know that in the example we're building, /foo is the "foo" application path.
So if we add a bar directory underneath the foo directory, we will have taken the first step to creating a "bar" controller. So... go do that. I'll wait.
Now we get to it - let's create a controller! Add a file named controller.rb into the bar folder. By default, this is where Kul will look for your controller code. Into this file insert the following code:
module Foo
module Bar
get test
'This is my test'
end
end
end
If you're used to Rails or most other MVC frameworks, you might be a bit confused here. There is no controller object. Controller actions in Kul are simply functions that are defined inside of a module. It is important to note that there are two modules and they're named after the application and the controller folders respectively. If you don't name your module correctly the framework won't be able to find it and you'll be left hitting your head against the keyboard.
So now browse to localhost:4567/foo/bar/test - and surprisingly, you see the text returned from the controller action. By default, if your controller action returns text then that is what gets returned to the client request (the content-type will indicate that it's HTML though). Pretty simple, right? Also note that you can change what the controller action is returning and refresh and the content changes without restarting the server.
So that's a controller, where are my views?
Okay, now add the following code to a file named test.html.erb inside of the bar controller folder.
<!DOCTYPE html>
<html>
<head>
<title>Kul app template example</title>
</head>
<body>
<div>
Thing: <%= @thing %>
</div>
<div>
Other thing: <%= @other_thing %>
</div>
</body>
</html>
Now we can browse to it: localhost:4567/foo/bar/test.html - note the utter lack of things. That's because we haven't defined them. It's important to note that by default, views can be reached on their own. There's no actual difference between a view and a template, other than how they're constructed.
So let's add a controller action with things! Add the following method to your controller:
get test_render
@thing = 'this is a cool thing!'
@other_thing = 'this is another cool thing!'
render_template 'foo/bar/test.html.erb'
end
Then go ahead and browse to localhost:4567/foo/bar/test_render - and we have things! Hooray for things!
The basic takeaway is that you create instance variables inside the action method, and those get bound to the view when you call render_template. There are more details to be had, including a few warnings about what instance variables you should avoid, but that will get covered in more detail in the controller documentation.
There's also a basic "echo" page which demonstrates a HTTP POST request. It can be seen as the 'echo' get and post method inside the controller.
So what about models, I hear you ask. They don't really exist right now. But when they do exist, they'll look like this:
Models go into the /models folder, either inside the server (root folder that you ran Kul in originally) or inside of the application. Application-specific models should go in the app folder, whereas common models across a server (user model might be a good choice, for example) would be put at the server level. They're also reloaded whenever they change.
If you check out the clicker.html sample page in the root of the basic_example, you'll be able to see that we're referring to .css.scss stylesheets with just a .css extension. The framework will automatically compile SASS stylesheets to css for you. It does the same for coffeescript - it will take a request for .js and compile a .js.coffee file - just like rails does. You're welcome.
That should be enough to get you started. More detail exists in the other parts of the wiki. Enjoy!