Class: Generator::Generator

Inherits:
Renderer show all
Defined in:
lib/generator/generator.rb

Overview

If you already familiar with Ruby on Rails: Generators are pretty much like Controllers in Rails. That’s like in Rails:

  • They use the existing data-model (The Dom in our case)

  • They start the rendering process in a view, by calling render.

  • If you want to make use of data in a view, you can store it in an instance-variable, like ‘@nodes`

  • Helpers are included in the generator, so you can utilize their messages in views

The major difference between controllers in Rails and generators in DocJs is, that DocJs triggers all generators one after another and there is no real interaction between the views and the generator.

In other words, after collecting all necessary informations about the JavaScript-Files and Markdown-Documents DocJs uses the Generators to create the final output.

The following image should help you to get a general overview, how the components of DocJs interact:

![Render Flow](../img/md_render_flow.png)

One may notice, that Renderer and Generator are not that separable, as shown in this image. In fact the concrete Generator (like ApiIndexGenerator) inherits from Generator, which in turn inherits from Renderer. So we’ve got an inheritence-chain like:

Generator::ApiIndexGenerator < Generator::Generator < Renderer

Helpers

You can create your own helper functions, bundled in a custom helper-module. They automatically will be mixed in all Generators, as long as they match the following conditions:

  • Your module has to be a Submodule of Helper

  • Your code has to be included somewhere (i.e. ‘require ’my_helper’‘ in application.rb)

For example your helper could look like:

# TEMPLATE_PATH/helpers/my_helper.rb
module Helper::MyHelper       
  def my_greeter
    "Hello Woooorld"
  end       
end

# TEMPLATE_PATH/application.rb
require_relative 'helpers/my_helper'

Then you could use them in your Generator or in your Views

# TEMPLATE_PATH/views/template.html.erb
<h1><%= my_greeter %></h1>

Examples:

a simple generator

module Generator
  class MyTestGenerator < Generator
    # For more information about those methods, see section Generator-Specification methods
    describe     'does awesome things'
    layout       'application'
    start_method :go
    templates    '/views/special_ones'

    protected

    def go       
      in_context Dom.root do
        @elements = []
        Dom.root.each_child do |child|
          @elements << child unless child.is_a? Dom::NoDoc
        end

        render 'my_view', :to_file => 'output_file.html'
      end    
    end
  end
end

Generator-Specification methods collapse

Context manipulation- and access-methods collapse

System-Methods collapse

Instance Method Summary collapse

Methods inherited from Renderer

#render

Constructor Details

#initialize ⇒ Generator

Returns a new instance of Generator.



83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/generator/generator.rb', line 83

def initialize
  # At this point we pass the configurations to our Parent `Renderer`
  super(Configs.templates + configs(:templates), configs(:layout))
  
  # include all Helpers
  Helper.constants
        .map { |c| Helper.const_get c }
        .each { |mod| extend mod if mod.is_a? Module }
        
  # Set Global Context to Dom's root node
  @_context = Dom.root
end

Class Method Details

.all ⇒ Array<Generator>

Returns all Generators, by finding all constants in the Generator-Module and filtering them for classes with parent Generator::Generator.

Returns:



200
201
202
203
204
205
206
 
# File 'lib/generator/generator.rb', line 200

def self.all
  # Otherwise we don't get the global Generator-Module
  gen_module = Object.const_get(:Generator)
  gen_module.constants
            .map { |c| gen_module.const_get c }
            .select { |klass| klass.class == Class and klass.superclass == self }
end

.describe(desc) ⇒ Object

This description is used in the cli-command ‘docjs generators` to list all generators and their descriptions

Parameters:

  • desc (String) —

    A short description of this generators task



102
103
104
 
# File 'lib/generator/generator.rb', line 102

def self.describe(desc)
  self.set_config(:description, desc.to_s)
end

.description ⇒ String

Is used by DocJs#generators to provide a list of all generators and their descriptions

Returns:

  • (String) —

    description, which has been previously entered using .describe



192
193
194
 
# File 'lib/generator/generator.rb', line 192

def self.description
   configs(:description)
end

.layout(layout_view) ⇒ Object

Specifies which layout should be used to render in (Default is nil)

Parameters:



109
110
111
112
113
114
115
 
# File 'lib/generator/generator.rb', line 109

def self.layout(layout_view)    
  unless layout_view.nil?
    self.set_config(:layout, 'layout/' + layout_view)
  else
    self.set_config(:layout, nil)
  end
end

.start_method(method) ⇒ Object

Which method should be invoked, if generator is executed (Default is :index)

Parameters:



120
121
122
 
# File 'lib/generator/generator.rb', line 120

def self.start_method(method)
  self.set_config(:start_method, method.to_sym)
end

.templates(path_to_views) ⇒ Object

Note:

the layout-path is always relative to your specified path (i.e. ‘layout ’application’‘ and `templates ’my_custom’‘ will result in a required layout file with a path like my_custom/layout/application.html.erb

The path to your views (Default is /views)

You can use this method, to specify a special template path, for example if you want to use a subdirectory of your views, without always having to provide the full path in all render-calls

Parameters:

  • path_to_views (String) —

    Relative path from your scaffolded template-directory, but with a leading /, like /views/classes



135
136
137
 
# File 'lib/generator/generator.rb', line 135

def self.templates(path_to_views)
  self.set_config(:templates, path_to_views)
end

.use(helper_module) ⇒ Object

Note:

not neccesarily needed, because all Helpers are included by default

Can be used to include a helper in a Generator



142
143
144
 
# File 'lib/generator/generator.rb', line 142

def self.use(helper_module)
 include helper_module
end

Instance Method Details

#context ⇒ Dom::Node

Retreives the current Dom-resolution-context, which can be specified by using #in_context

Returns:

  • (Dom::Node) —

    the context, to which all relative nodes should be resolved



163
164
165
 
# File 'lib/generator/generator.rb', line 163

def context
  @_context
end

#in_context(new_context) { ... } ⇒ Object

Modyfies the Dom-resolution-context #context to new_context, while in ‘&block`. After leaving the block, the context will be switched back.

Parameters:

  • new_context (Dom::Node) —

    The new context

Yields:

  • block The block, in which the context is valid



153
154
155
156
157
158
 
# File 'lib/generator/generator.rb', line 153

def in_context(new_context, &block)
  old_context = @_context
  @_context = new_context
  yield
  @_context = old_context
end

#perform ⇒ Object

Calls always the specified :start_method on this Generator. (Default for :start_method is ‘index’)



180
181
182
183
184
185
186
187
 
# File 'lib/generator/generator.rb', line 180

def perform
  
  unless self.respond_to? configs(:start_method)
    raise Exception, "#{self.class} needs to implement specified start-method '#{configs(:start_method)}'"
  end
  
  self.send configs(:start_method)
end

#resolve(nodename) ⇒ Dom::Node?

Resolves a nodename in the specified context, by using Dom::Node#resolve on it.

Parameters:

Returns:

See Also:



172
173
174
 
# File 'lib/generator/generator.rb', line 172

def resolve(nodename)
  @_context.resolve nodename
end