Creating a Component

Components are the lifeblood of Ditty. You use them to add more functionality to your project. They're structured in such a way that you can add and remove, and dynamically enable them, as needed. The core Ditty functionality is also written as a [component].

Example

We'll be creating a component named Billing as an example.

You can either add the component code to your project, or write components as separate gems. The file structure for a component is as follows:

• lib/ditty/components/billing.rb - This is the component definition file
• lib/billing/models/* - All your components models go into this folder
• lib/billing/views/* - All your components views go into this folder
• lib/billing/controllers/* - All your components controllers go into this folder

The component definition file needs to, at a minimum, look like this:

module Ditty
  class Billing
  end
end

Ditty::Components.register_component(:billing, Ditty::Billing)

Not a lot too it :) The important parts to notice is that you create class named after your component in the Ditty namespace, and then register the component using that class. This component doesn't do a lot, so let's add a couple of features:

module Ditty
  class Billing
    class << self
      def migrations
        File.expand_path('../../../../migrate', __FILE__)
      end

      def view_folder
        File.expand_path('../../../../views', __FILE__)
      end

      def routes
        controllers = File.expand_path('../../../billing/controllers', __FILE__)
        Dir.glob("#{controllers}/*.rb").each { |f| require f }
        {
          '/invoices' => ::Billing::Invoices
        }
      end

      def navigation
        [
          { order: 50, link: '/invoices', text: 'Billing', target: ::Billing::Invoice, icon: 'sticky-note' },
        ]
      end
    end
  end
end

Ditty::Components.register_component(:billing, Ditty::Billing)

Let's cover each method one by one:

Migrations

def migrations

This registers the component's migration folder. Any Sequel migrations in this folder will be added to the project.

Views

def view_folder

This registers the component's views folder. Place all the views related to your component in it.

Routes

def routes

This defines all the routes the component will expose through its various controllers. They will be passed directly to Rack::URLMap.new. The method should return a hash, with the path of the route as the key, and the controller for the path as the value.

Navigation

def navigation

This defines the front end for your routes. All links defined in this method will appear in the sidebar of the project. The method should return an array of hashes. Each hash should contain the following keys:

• order: An integer that indicates where the nav item should appear in the side bar. The lower the number, the higher the item will appear.
• link: The destination of the link. This can be internal or external. This is used in the href of the generated link.
• text: The text shown to the user in the sidebar.
• icon: The font awesome icon to be shown along with the text.
• target: Optional - The model or controller this link targets. It's used in the policy check to determine if the link should be shown or not.