ramaze 0.3.9.1 → 2023.01.06

data/examples/app/blog/controller/posts.rb

@@ -0,0 +1,223 @@
+##
+# The Posts controller is used to display a list of all the posts that have been
+# added as well as providing a way of adding, removing and updating posts.
+#
+# @since  26-09-2011
+#
+class Posts < BaseController
+  map '/'
+
+  # Sets the content type and view name based on the extension in the URL. For
+  # example, a request to /posts/feed.rss would render the view feed.rss.xhtml
+  # and set the content type to application/rss+xml.
+  provide(:atom, :type => 'application/atom+xml') do |action, body|
+    # Disable the layout.
+    action.layout = false
+
+    # Let's make sure the body is actually rendered. Using "return" would cause
+    # a local jumper error.
+    body
+  end
+
+  # These methods require the user to be logged in. If this isn't the case the
+  # user will be redirected back to the previous page and a message is
+  # displayed.
+  before(:edit, :new, :save, :delete) do
+    # "unless logged_in?" is the same as "if !logged_in?" but in my opinion is a
+    # bit nicer to the eyes.
+    unless logged_in?
+      flash[:error] = 'You need to be logged in to view that page'
+
+      # Posts.r() is a method that generates a route to a given method and a set
+      # of parameters. Calling #to_s on this object would produce a string
+      # containing a URL. For example, Posts.r(:edit, 10).to_s would result in
+      # "/edit/10".
+      redirect(Posts.r(:index))
+    end
+  end
+
+  ##
+  # Shows an overview of all the posts that have been added. These posts are
+  # paginated using the Paginate helper.
+  #
+  # @since  26-09-2011
+  #
+  def index
+    @posts = paginate(Post.eager(:comments, :user))
+    @title = 'Posts'
+  end
+
+  ##
+  # Returns a list of all posts as either an RSS feed or an Atom feed.
+  #
+  # @since  27-09-2011
+  #
+  def feed
+    @posts = Post.all
+
+    render_view(:feed)
+  end
+
+  ##
+  # Shows a single post along with all it's comments.
+  #
+  # @since  26-09-2011
+  # @param  [Fixnum] id The ID of the post to view.
+  #
+  def view(id)
+    @post = Post[id]
+
+    if @post.nil?
+      flash[:error] = 'The specified post is invalid'
+      redirect_referrer
+    end
+
+    @title       = @post.title
+    @created_at  = @post.created_at.strftime('%Y-%m-%d')
+    @new_comment = flash[:form_data] || Comment.new
+  end
+
+  ##
+  # Allows users to create a new post, given the user is logged in.
+  #
+  # @since  26-09-2011
+  #
+  def new
+    @post  = flash[:form_data] || Post.new
+    @title = 'New post'
+
+    render_view(:form)
+  end
+
+  ##
+  # Allows a user to edit an existing blog post.
+  #
+  # @since  26-09-2011
+  # @param  [Fixnum] id The ID of the blog post to edit.
+  #
+  def edit(id)
+    @post = flash[:form_data] || Post[id]
+
+    # Make sure the post is valid
+    if @post.nil?
+      flash[:error] = 'The specified post is invalid'
+      redirect_referrer
+    end
+
+    @title = "Edit #{@post.title}"
+
+    render_view(:form)
+  end
+
+  ##
+  # Adds a new comment to an existing post and redirects the user back to the
+  # post.
+  #
+  # @since  27-09-2011
+  #
+  def add_comment
+    data    = request.subset(:post_id, :username, :comment)
+    comment = Comment.new
+
+    # If the user is logged in the user_id field should be set instead of the
+    # username field.
+    if logged_in?
+      data.delete('username')
+      data['user_id'] = user.id
+    end
+
+    begin
+      comment.update(data)
+      flash[:success] = 'The comment has been added'
+    rescue => e
+      Ramaze::Log.error(e)
+
+      flash[:form_errors] = comment.errors
+      flash[:error]       = 'The comment could not be added'
+    end
+
+    redirect_referrer
+  end
+
+  ##
+  # Saves the changes made by Posts#edit() and Posts#new(). While these two
+  # methods could have their own methods for saving the data the entire process
+  # is almost identical and thus this would be somewhat useless.
+  #
+  # @since  26-09-2011
+  #
+  def save
+    # Fetch the POST data to use for a new Post object or for updating an
+    # existing one.
+    data            = request.subset(:title, :body)
+    id              = request.params['id']
+    data['user_id'] = user.id
+
+    # If an ID is given it's assumed the user wants to edit an existing post,
+    # otherwise a new one will be created.
+    if !id.nil? and !id.empty?
+      post = Post[id]
+
+      # Let's make sure the post is valid
+      if post.nil?
+        flash[:error] = 'The specified post is invalid'
+        redirect_referrer
+      end
+
+      success = 'The post has been updated'
+      error   = 'The post could not be updated'
+    # Create a new post
+    else
+      post    = Post.new
+      success = 'The post has been created'
+      error   = 'The post could not be created'
+    end
+
+    # Now that we have a Post object and the messages to display it's time to
+    # actually insert/update the data. This is wrapped in a begin/rescue block
+    # so that any errors can be handled nicely.
+    begin
+      # Post#update() can be used for both new objects and existing ones. In
+      # case the object doesn't exist in the database it will be automatically
+      # created.
+      post.update(data)
+
+      flash[:success] = success
+
+      # Redirect the user back to the correct page.
+      redirect(Posts.r(:edit, post.id))
+    rescue => e
+      Ramaze::Log.error(e)
+
+      # Store the submitted data and the errors. The errors are used by
+      # BlueForm, the form data is used so that the user doesn't have to
+      # re-enter all data every time something goes wrong.
+      flash[:form_data]   = post
+      flash[:form_errors] = post.errors
+      flash[:error]       = error
+
+      redirect_referrer
+    end
+  end
+
+  ##
+  # Removes a single post from the database.
+  #
+  # @since  26-09-2011
+  # @param  [Fixnum] id The ID of the post to remove.
+  #
+  def delete(id)
+    # The call is wrapped in a begin/rescue block so any errors can be handled
+    # properly. Without this the user would bump into a nasty stack trace and
+    # probably would have no clue as to what's going on.
+    begin
+      Post.filter(:id => id).destroy
+      flash[:success] = 'The specified post has been removed'
+    rescue => e
+      Ramaze::Log.error(e.message)
+      flash[:error] = 'The specified post could not be removed'
+    end
+
+    redirect(Posts.r(:index))
+  end
+end # Posts

data/examples/app/blog/controller/users.rb

@@ -0,0 +1,152 @@
+##
+# The Users controller is used for managing users and allowing existing users to
+# log in.
+#
+# @since  26-09-2011
+#
+class Users < BaseController
+  map '/users'
+
+  # The user has to be logged in in order to access this controller. The only
+  # exception is the login() method.
+  before_all do
+    if action.method.to_sym != :login and !logged_in?
+      flash[:error] = 'You need to be logged in to view that page'
+      redirect(Users.r(:login))
+    end
+  end
+
+  ##
+  # Shows an overview of all the users that have been added to the database.
+  #
+  # @since  27-09-2011
+  #
+  def index
+    @users = paginate(User)
+    @title = 'Users'
+  end
+
+  ##
+  # Allows users to add another user to the database.
+  #
+  # @since  27-09-2011
+  #
+  def new
+    @user  = flash[:form_data] || User.new
+    @title = 'New user'
+
+    render_view(:form)
+  end
+
+  ##
+  # Edits an existing user. If the specified user ID is invalid the user is
+  # redirected back to the previous page.
+  #
+  # @since  27-09-2011
+  # @param  [Fixnum] id The ID of the user to edit.
+  #
+  def edit(id)
+    @user = flash[:form_data] || User[id]
+
+    if @user.nil?
+      flash[:error] = 'The specified user is invalid'
+      redirect_referrer
+    end
+
+    @title = "Edit #{@user.username}"
+
+    render_view(:form)
+  end
+
+  ##
+  # Saves the changes made by Users#new() and Users#edit(). Just like
+  # Posts#save() this method is used for both methods since the actions required
+  # for adding/updating the data is pretty much identical.
+  #
+  # @since  27-09-2011
+  #
+  def save
+    data = request.subset(:username, :password)
+    id   = request.params['id']
+
+    if !id.nil? and !id.empty?
+      user = User[id]
+
+      if user.nil?
+        flash[:error] = 'The specified user is invalid'
+        redirect_referrer
+      end
+
+      success = 'The user has been updated'
+      error   = 'The user could not be updated'
+    else
+      user    = User.new
+      success = 'The user has been added'
+      error   = 'The user could not be added'
+    end
+
+    begin
+      user.update(data)
+
+      flash[:success] = success
+      redirect(Users.r(:edit, user.id))
+    rescue => e
+      Ramaze::Log.error(e)
+
+      flash[:error]       = error
+      flash[:form_errors] = user.errors
+      flash[:form_data]   = user
+
+      redirect_referrer
+    end
+  end
+
+  ##
+  # Deletes a single user and redirects the user back to the overview.
+  #
+  # @since  27-09-2011
+  # @param  [Fixnum] id The ID of the user to delete.
+  #
+  def delete(id)
+    begin
+      User.filter(:id => id).destroy
+      flash[:success] = 'The specified user has been removed'
+    rescue => e
+      Ramaze::Log.error(e)
+      flash[:error] = 'The specified user could not be removed'
+    end
+
+    redirect_referrer
+  end
+
+  ##
+  # Allows a user to log in. Once logged in the user is able to manage existing
+  # users and edit posts.
+  #
+  # @since  27-09-2011
+  #
+  def login
+    if request.post?
+      if user_login(request.subset('username', 'password'))
+        flash[:success] = 'You have been logged in'
+        redirect(Posts.r(:index))
+      else
+        flash[:error] = 'You could not be logged in'
+      end
+    end
+
+    @title = 'Login'
+  end
+
+  ##
+  # Logs the user out and destroys the session.
+  #
+  # @since  27-09-2011
+  #
+  def logout
+    user_logout
+    session.clear
+    flash[:success] = 'You have been logged out'
+    redirect(Users.r(:login))
+  end
+end # Users

data/examples/app/blog/layout/default.xhtml

@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+
+        <title>#{@title}</title>
+
+        #{css('reset')}
+        #{css('grid')}
+        #{css('layout')}
+        #{css('text')}
+    </head>
+    <body>
+        <div class="container">
+            <div id="container" class="row">
+                <!-- Top part, contains the navigation menu -->
+                <div id="top" class="grid_12">
+                    <header class="grid_6">
+                        <h1>#{@title}</h1>
+                    </header>
+
+                    <nav class="grid_6 last">
+                        <ul class="clearfix">
+                            <li>#{Posts.a('Posts', :index)}</li>
+
+                            <?r if logged_in? ?>
+
+                            <li>#{Users.a('Users', :index)}</li>
+                            <li>#{Users.a('Logout', :logout)}</li>
+
+                            <?r else ?>
+
+                            <li>#{Users.a('Login', :login)}</li>
+
+                            <?r end ?>
+                        </ul>
+                    </nav>
+                </div>
+
+                <?r [:success, :error].each do |type| ?>
+                <?r if flash[type] ?>
+                <div class="message grid_12 #{type}">
+                    <p>#{flash[type]}</p>
+                </div>
+                <?r end ?>
+                <?r end ?>
+
+                <div id="content" class="grid_12">
+                    #{@content}
+                </div>
+            </div>
+
+            <footer id="footer">
+                <p>
+                    Ramaze is free software and is licensed under the Ruby
+                    license.
+                </p>
+            </footer>
+        </div>
+    </body>
+</html>

data/examples/app/blog/migrations/01_create_schema.rb

@@ -0,0 +1,50 @@
+# For more information on Sequel migrations see the following page:
+# http://sequel.rubyforge.org/rdoc/files/doc/migration_rdoc.html
+Sequel.migration do
+  # The up() method and block is used to update a database to the current
+  # migration.
+  up do
+    create_table(:users) do
+      primary_key :id
+
+      String :username, :null => false
+      String :password, :null => false
+    end
+
+    create_table(:posts) do
+      primary_key :id
+
+      String :title, :null => false
+      String :body , :null => false, :text => true
+
+      Time :created_at
+      Time :updated_at
+
+      foreign_key :user_id, :users, :on_update => :cascade,
+        :on_delete => :cascade, :key => :id
+    end
+
+    create_table(:comments) do
+      primary_key :id
+
+      String :username, :null => true
+      String :comment , :null => false, :text => true
+
+      Time :created_at
+
+      foreign_key :post_id, :posts, :on_update => :cascade,
+        :on_delete => :cascade, :key => :id
+
+      foreign_key :user_id, :users, :on_update => :cascade,
+        :on_delete => :cascade, :key => :id
+    end
+  end
+
+  # The down() method and block is used to revert the changes introduced by the
+  # up() block.
+  down do
+    drop_table(:comments)
+    drop_table(:posts)
+    drop_table(:users)
+  end
+end

data/examples/app/blog/model/comment.rb

@@ -0,0 +1,42 @@
+##
+# The Comment model is used for creating and managing comments.
+#
+# @since  26-09-2011
+#
+class Comment < Sequel::Model
+  plugin :timestamps, :create => :created_at, :update => :updated_at
+
+  # A comment can belong to only one post and one user
+  many_to_one :post
+  many_to_one :user
+
+  ##
+  # Validates a comment before saving it to the database.
+  #
+  # @since  26-09-2011
+  #
+  def validate
+    validates_presence(:comment)
+
+    # Comments can either have user ID or a custom name. The user ID is only set
+    # when the user is logged in.
+    unless self.user_id
+      validates_presence(:username)
+    end
+  end
+
+  ##
+  # Gets the name of the author from either an associated user or the "name"
+  # field.
+  #
+  # @since  26-09-2011
+  # @return [String]
+  #
+  def username
+    if user and user.username
+      return user.username
+    else
+      return super
+    end
+  end
+end # Comment

data/examples/app/blog/model/init.rb

@@ -0,0 +1,44 @@
+# Configure Sequel. This example uses a SQLite3 database with it's encoding set
+# to UTF-8. The :test option is used to confirm that the database connection is
+# valid before it's actually being used. In this case the connection returned by
+# Sequel.connect is stored in a constant called "DB" but you're free to store it
+# wherever you want.
+DB = Sequel.connect(
+  :adapter  => 'sqlite',
+  :database => __DIR__('../database.db'),
+  :test     => true,
+  :encoding => 'utf8'
+)
+
+# The validation_helpers plugin is required if you want to use the #validate()
+# method in your model in combination with easy to use methods such as
+# validates_presence().
+Sequel::Model.plugin(:validation_helpers)
+
+# The migration extension is needed in order to run migrations.
+Sequel.extension(:migration)
+
+# The pagination extension is needed by Ramaze::Helper::Paginate.
+Sequel.extension(:pagination)
+
+# Migrate the database
+Sequel::Migrator.run(DB, __DIR__('../migrations'))
+
+# Time to load all the models now that Sequel is set up.
+require __DIR__('comment')
+require __DIR__('post')
+require __DIR__('user')
+
+# Insert the default user if this hasn't already been done so.
+unless User[:username => 'admin']
+  User.create(:username => 'admin', :password => 'admin')
+end
+
+# Insert a default post if no posts have been added.
+if Post.all.empty?
+  Post.create(
+    :title   => 'Example Post',
+    :body    => 'This is a post that uses Markdown!',
+    :user_id => User[:username => 'admin'].id
+  )
+end

data/examples/app/blog/model/post.rb

@@ -0,0 +1,33 @@
+##
+# The Post class is a model that's used for managing posts. The corresponding
+# table is called "posts". For more information on how Sequel works see the
+# following page: http://sequel.rubyforge.org/documentation.html
+#
+# @since  26-09-2011
+#
+class Post < Sequel::Model
+  # The timestamps plugin is used to automatically fill two database columns
+  # with the dates and times on which an object was created and when it was
+  # modified.
+  plugin :timestamps, :create => :created_at, :update => :updated_at
+
+  # Multiple posts can only belong to a single user.
+  many_to_one :user
+  one_to_many :comments
+
+  ##
+  # Post#validate() is called whenever an instance of this class is saved or
+  # updated. For more information on what you can do with this method see the
+  # following page:
+  # http://sequel.rubyforge.org/rdoc/files/doc/validations_rdoc.html
+  #
+  # If you're used to working with ActiveRecord it's important to remember that
+  # these validation methods can't be used in a model's class declaration, they
+  # have to be placed inside the #validate() method.
+  #
+  # @since  26-09-2011
+  #
+  def validate
+    validates_presence([:title, :body])
+  end
+end # Post

data/examples/app/blog/model/user.rb

@@ -0,0 +1,100 @@
+##
+# The User model is user for retrieving and authenticating users. This
+# application uses bcrypt to hash the passwords. For more information on bcrypt
+# see the following pages:
+#
+# * http://codahale.com/how-to-safely-store-a-password/
+# * http://yorickpeterse.com/articles/use-bcrypt-fool/
+# * https://github.com/codahale/bcrypt-ruby
+#
+# @since  26-09-2011
+#
+class User < Sequel::Model
+  # A user can have any number of posts and comments.
+  one_to_many :posts
+  one_to_many :comments
+
+  ##
+  # User.authenticate() is used to authenticate a user. Each request the User
+  # helper calls this method to see if the currently logged in user is a valid
+  # user. Once called this methods queries the database and returns a valid User
+  # object in case the specified details were correct or something that
+  # evaluates to false if this wasn't the case.
+  #
+  # @since  26-09-2011
+  # @param  [Hash] creds A hash containing the username and password of the
+  #  currently logged in user.
+  # @return [Users|FalseClass]
+  #
+  def self.authenticate(creds)
+    username, password = creds['username'], creds['password']
+
+    if creds['username'].nil? or creds['username'].empty?
+      return false
+    end
+
+    # Let's see if there is a user for the given username.
+    user = self[:username => username]
+
+    # Validate the user. Note that while it may seem that the password is
+    # compared as plain text this is not the case. The bcrypt class
+    # automatically converts the given password to a bcrypt hash. If these
+    # hashes are the same the specified password is correct.
+    if !user.nil? and user.password == password
+      return user
+    else
+      return false
+    end
+  end
+
+  ##
+  # In order to properly use bcrypt we have to override the password=() and
+  # password() methods to return a correct bcrypt hash/object rather than
+  # whatever was stored in the database as a String instance.
+  #
+  # @since  26-09-2011
+  # @param  [String] password The new password of a user.
+  #
+  def password=(password)
+    # Passing an empty password to the BCrypt class triggers errors.
+    if password.nil? or password.empty?
+      return
+    end
+
+    # Generates a new bcrypt password using a cost of 10. In my opinion a cost
+    # higher than 10 makes a web based application too slow.
+    password = BCrypt::Password.create(password, :cost => 10)
+
+    super(password)
+  end
+
+  ##
+  # Because the password=() is overwritten with a custom one we also have to
+  # define a matching getter. Without this you'd get an instance of String
+  # containing the bcrypt hash and thus wouldn't be able to properly compare it
+  # to other passwords.
+  #
+  # @since  26-09-2011
+  # @return [BCrypt::Password|NilClass]
+  #
+  def password
+    password = super
+
+    if !password.nil?
+      return BCrypt::Password.new(password)
+    else
+      return nil
+    end
+  end
+
+  ##
+  # Validates an instance of this model. See Post#validate() for some extra
+  # details on how this works.
+  #
+  # @since  26-09-2011
+  #
+  def validate
+    validates_presence(:username)
+    validates_presence(:password) if new?
+  end
+end # User