add documentation for the configuration options + simplify the way the server is used (no more options)

did committed Feb 18, 2015

commit f3a564c245c6b6c7d717286ca736a9fa55bd7389

Showing 16 changed files with 191 additions and 235 deletions

bin/steam.rb +5 -6

@@	@@ -13,7 +13,10 @@ require_relative '../lib/locomotive/steam/server'
	path = ARGV[0] \|\| ENV['SITE_PATH'] \|\| File.join(File.expand_path(File.dirname(__FILE__)), '../spec/fixtures/default')

	Locomotive::Steam.configure do \|config\|
-	config.mode = :test
+	config.mode = :test
+	config.site_path = path
+	config.serve_assets = true
+	config.minify_assets = false
	end

	Locomotive::Common.reset
@@	@@ -21,11 +24,7 @@ Locomotive::Common.configure do \|config\|
	config.notifier = Locomotive::Common::Logger.setup(File.join(path, 'log/steam.log'))
	end

-	server = Locomotive::Steam::Server.new({
-	path: path,
-	serve_assets: true,
-	minify_assets: false
-	})
+	server = Locomotive::Steam::Server.new

	# Note: alt thin settings (Threaded)
	server = Thin::Server.new('localhost', '8080', server.to_app)

locomotive/steam.rb b/lib/locomotive/steam.rb +8 -8

@@	@@ -5,14 +5,14 @@ require 'active_support/concern'
	require 'active_support/deprecation'
	require 'active_support/core_ext'

-	require_relative 'steam/core_ext'
-	require_relative 'steam/configuration'
-	require_relative 'steam/monkey_patches'
-	require_relative 'steam/decorators'
-	require_relative 'steam/liquid'
+	require_relative 'steam/core_ext'
+	require_relative 'steam/configuration'
+	require_relative_all 'steam/monkey_patches'
+	require_relative_all 'steam/decorators'
+	require_relative 'steam/liquid'

-	require_relative 'steam/repositories'
-	require_relative 'steam/services'
+	require_relative 'steam/repositories'
+	require_relative 'steam/services'

	module Locomotive
	module Steam
@@	@@ -37,7 +37,7 @@ module Locomotive
	require_relative 'steam/initializers'
	end

-	# FIXME: not sure it will be ever needed
+	# FIXME: not sure it will ever be needed
	# class << self
	# def method_missing(name, *args, &block)
	# Locomotive::Steam.configuration.public_send(name)

locomotive/steam/configuration.rb b/lib/locomotive/steam/configuration.rb +80 -10

@@	@@ -1,31 +1,101 @@
+	require_relative 'middlewares/proxy_stack'
+
	module Locomotive
	module Steam

	class Configuration

+	# Mainly used in the liquid templates (variable name: {{ mode }})
+	# to distinguish the page rendered in Wagon (:test) or in the Engine.
+	#
+	# default: :production
+	#
	attr_accessor :mode
+	def mode; @mode \|\| :production; end
+
+	# Steam is also able to serve a local Wagon site. The following property
+	# should point to the root path of the site.
+	#
+	# default: nil
+	#
+	attr_accessor :site_path

-	attr_accessor :repositories_builder_klass
+	# Manage the list of middlewares used by the rack stack.
+	#
+	# Examples:
+	# Locomotive::Steam.configure do \|config\|
+	# ...
+	# config.middleware.remove Rack::Lint
+	# ...
+	# config.middleware.insert_after Middleware::Locale, MySlugMiddleware, answer: 42
+	# ...
+	# end
+	#
+	attr_accessor :middleware
+	def middleware; @middleware \|\|= Middlewares::ProxyStack.new; end

+	# Add the checksum of a theme asset at the end of its path to allow public caching.
+	#
+	# default: false (disabled)
+	#
	attr_accessor :theme_assets_checksum
+	def theme_assets_checksum; @theme_assets_checksum.nil? ? false : @theme_assets_checksum; end
+
+	# Enable serving of images, stylesheets, and JavaScripts from an asset server.
+	# Useful if a CDN is used to serve assets.
+	#
+	# default: nil
+	#
	attr_accessor :asset_host

+	# Tell if Steam has to also serve static (images) or dynamic (SASS, Coffeescript) assets.
+	#
+	# default: true
+	#
	attr_accessor :serve_assets
+	def serve_assets; @serve_assets.nil? ? true : @serve_assets; end
+
+	# Path to the assets (if Steam serves the assets).
+	# If the site_path property is not nil, the assets_path
+	# will point to the "public" sub folder of the site.
+	#
+	# default: nil
+	#
	attr_accessor :assets_path
-	attr_accessor :image_resizer_secret
+	def assets_path
+	return @assets_path if @assets_path
+	site_path ? File.join(site_path, 'public') : nil
+	end

-	attr_accessor :csrf_protection
+	# If java is installed and if this option is enabled,
+	# then YUI::JavaScriptCompressor and YUI::CssCompressor are used to minify the css and the javascript.
+	#
+	# default: false
+	#
+	attr_accessor :minify_assets
+	def minify_assets; @minify_assets.nil? ? false : @minify_assets; end

-	def initialize
-	self.mode = :production
-	self.theme_assets_checksum = false
+	# Dragonfly needs it to generate the protective SHA.
+	#
+	# default: 'please change it'
+	#
+	attr_accessor :image_resizer_secret
+	def image_resizer_secret; @image_resizer_secret.nil? ? 'please change it' : @image_resizer_secret; end

-	self.serve_assets = false
+	# Enable the Cross-site request forgery protection for POST requests.
+	#
+	# default: true
+	#
+	attr_accessor :csrf_protection
+	def csrf_protection; @csrf_protection.nil? ? true : @csrf_protection; end

-	self.image_resizer_secret = 'please change it'
+	# Options for the store of Moneta (Session)
+	#
+	# default: { store: Moneta.new(:Memory, expires: true) }
+	#
+	attr_accessor :moneta
+	def moneta; @moneta.nil? ? { store: Moneta.new(:Memory, expires: true) } : @moneta; end

-	self.csrf_protection = true
-	end
	end

	end

locomotive/steam/core_ext/kernel.rb b/lib/locomotive/steam/core_ext/kernel.rb +1 -1

@@	@@ -4,7 +4,7 @@ module Kernel
	main_path = File.dirname(caller.first.sub(/:\d+$/, ''))
	main_path = File.join(main_path, sub) if sub

-	paths.each do \|path\|
+	[*paths].each do \|path\|
	Dir[File.join(main_path, path, '*.rb')].each { \|file\| require file }
	end
	end

locomotive/steam/decorators.rb b/lib/locomotive/steam/decorators.rb +0 -2

@@	@@ -1,2 +0,0 @@
-	require_relative 'decorators/i18n_decorator'
-	require_relative 'decorators/template_decorator'

locomotive/steam/initializers.rb b/lib/locomotive/steam/initializers.rb +0 -4

@@	@@ -1,7 +1,3 @@
	require_relative 'initializers/sprockets.rb'
	require_relative 'initializers/i18n.rb'
	require_relative 'initializers/dragonfly.rb'
-
-	# Locomotive::Common.configure do \|config\|
-	# config.notifier = Locomotive::Common::Logger.setup
-	# end

locomotive/steam/middlewares/default_env.rb b/lib/locomotive/steam/middlewares/default_env.rb +2 -2

@@	@@ -1,7 +1,7 @@
	module Locomotive::Steam
	module Middlewares

-	class DefaultEnv < Struct.new(:app, :options)
+	class DefaultEnv < Struct.new(:app)

	def call(env)
	request = Rack::Request.new(env)
@@	@@ -16,7 +16,7 @@ module Locomotive::Steam
	private

	def build_services(request)
-	Locomotive::Steam::Services.build_instance(request, options)
+	Locomotive::Steam::Services.build_instance(request)
	end

	end

locomotive/steam/middlewares/dynamic_assets.rb b/lib/locomotive/steam/middlewares/dynamic_assets.rb +2 -1

@@	@@ -1,5 +1,4 @@
	require 'coffee_script'
-	require 'yui/compressor'

	module Locomotive::Steam
	module Middlewares
@@	@@ -35,6 +34,8 @@ module Locomotive::Steam
	def install_yui_compressor(sprockets, options)
	return unless options[:minify]

+	require 'yui/compressor'
+
	if is_java_installed?
	# minify javascripts and stylesheets
	sprockets.js_compressor = YUI::JavaScriptCompressor.new

locomotive/steam/middlewares/renderer.rb b/lib/locomotive/steam/middlewares/renderer.rb +3 -150

@@	@@ -62,7 +62,9 @@ module Locomotive::Steam
	'current_page' => params[:page],
	'params' => params.stringify_keys,
	'now' => Time.zone.now,
-	'today' => Date.today
+	'today' => Date.today,
+	'mode' => Locomotive::Steam.configuration.mode,
+	'wagon' => Locomotive::Steam.configuration.mode == :test
	}
	end

@@	@@ -96,155 +98,6 @@ module Locomotive::Steam
	}
	end

-
-	# response = nil
-
-	# # time = Benchmark.realtime do
-	# # puts "[Rendered] TODO"
-	# # self.set_accessors(env)
-	# response = [200, { 'Content-Type' => 'text/html' }, ['TODO']]
-	# # end
-
-	# # puts "[Benchmark][Renderer] Time elapsed #{time*1000} milliseconds"
-	# response
-
-	# if page
-	# if page.redirect?
-	# redirect_to(page.redirect_url, page.redirect_type)
-	# else
-	# type = page.response_type \|\| 'text/html'
-	# html = render_page
-
-	# log 'Rendered liquid page template'
-
-	# [200, { 'Content-Type' => type }, [html]]
-	# end
-	# else
-	# [404, { 'Content-Type' => 'text/html' }, [render_404]]
-	# end
-	# end
-
-	# def self.call(env)
-	# raise 'TODO'
-	# end
-
-	# protected
-
-	# def render_page
-	# context = self.locomotive_context
-	# # begin
-	# # binding.pry
-	# render(page, context)
-	# # rescue Exception => e
-
-	# # raise RendererException.new(e, self.page.title, self.page.template, context)
-	# # end
-	# end
-
-	# def render(page, context)
-	# parse(page, context).render(context)
-	# end
-
-	# protected
-
-	# def parse(page, context)
-
-	# options = {
-	# page: page,
-	# mapper: context.registers[:mapper],
-	# error_mode: :strict,
-	# count_lines: true
-	# }
-
-	# begin
-	# ::Liquid::Template.parse(page.source(I18n.locale), options)
-	# rescue ::Liquid::SyntaxError
-	# # do it again on the raw source instead so that the error line matches
-	# # the source file.
-	# ::Liquid::Template.parse(self.template.raw_source, options)
-	# end
-	# end
-
-
-	# def render_404
-	# if self.page = Locomotive::Models[:pages]['404']
-	# self.render_page
-	# else
-	# 'Page not found'
-	# end
-	# end
-
-	# # Build the Liquid context used to render the Locomotive page. It
-	# # stores both assigns and registers.
-	# #
-	# # @param [ Hash ] other_assigns Assigns coming for instance from the controler (optional)
-	# #
-	# # @return [ Object ] A new instance of the Liquid::Context class.
-	# #
-	# def locomotive_context(other_assigns = {})
-	# assigns = self.locomotive_default_assigns
-
-	# # assigns from other middlewares
-	# assigns.merge!(self.liquid_assigns)
-
-	# assigns.merge!(other_assigns)
-
-	# # templatized page
-	# if self.page && self.content_entry
-	# ['content_entry', 'entry', self.page.content_type.slug.singularize].each do \|key\|
-	# assigns[key] = self.content_entry
-	# end
-	# end
-
-	# # Tip: switch from false to true to enable the re-thrown exception flag
-	# ::Liquid::Context.new({}, assigns, self.locomotive_default_registers, true)
-	# end
-
-	# # Return the default Liquid assigns used inside the Locomotive Liquid context
-	# #
-	# # @return [ Hash ] The default liquid assigns object
-	# #
-	# def locomotive_default_assigns
-	# {
-	# 'site' => self.site.to_liquid,
-	# 'page' => self.page,
-	# 'models' => Locomotive::Steam::Liquid::Drops::ContentTypes.new,
-	# 'contents' => Locomotive::Steam::Liquid::Drops::ContentTypes.new,
-	# 'current_page' => self.params[:page],
-	# 'params' => self.params.stringify_keys,
-	# 'path' => self.request.path,
-	# 'fullpath' => self.request.fullpath,
-	# 'url' => self.request.url,
-	# 'ip_address' => self.request.ip,
-	# 'post?' => self.request.post?,
-	# 'host' => self.request.host_with_port,
-	# 'now' => Time.zone.now,
-	# 'today' => Date.today,
-	# 'locale' => I18n.locale.to_s,
-	# 'default_locale' => self.site.default_locale.to_s,
-	# 'locales' => self.site.locales.map(&:to_s),
-	# 'current_user' => {},
-	# 'session' => Locomotive::Steam::Liquid::Drops::SessionProxy.new,
-	# 'steam' => true,
-	# 'editing' => false
-	# }
-	# end
-
-	# # Return the default Liquid registers used inside the Locomotive Liquid context
-	# #
-	# # @return [ Hash ] The default liquid registers object
-	# #
-	# def locomotive_default_registers
-	# {
-	# request: self.request,
-	# site: self.site,
-	# page: self.page,
-	# services: self.services,
-	# inline_editor: false,
-	# logger: Locomotive::Common::Logger
-	# }
-	# end
-
	end

	end

locomotive/steam/monkey_patches.rb b/lib/locomotive/steam/monkey_patches.rb +0 -4

@@	@@ -1,4 +0,0 @@
-	# require_relative 'monkey_patches/httparty.rb'
-	# require_relative 'monkey_patches/dragonfly.rb'
-	require_relative 'monkey_patches/haml.rb'
-	require_relative 'monkey_patches/kaminari.rb'

locomotive/steam/repositories/filesystem.rb b/lib/locomotive/steam/repositories/filesystem.rb +9 -9

@@	@@ -9,40 +9,40 @@ module Locomotive
	module Repositories
	module Filesystem

-	def self.build_instance(site = nil, current_locale = nil, options = {})
-	Instance.new(site, current_locale, options)
+	def self.build_instance(site = nil, current_locale = nil, path = nil)
+	Instance.new(site, current_locale, path)
	end

-	class Instance < Struct.new(:current_site, :current_locale, :options)
+	class Instance < Struct.new(:current_site, :current_locale, :path)

	include Morphine

	register :site do
	Filesystem::Site.new(
-	YAMLLoaders::Site.new(options[:path], cache))
+	YAMLLoaders::Site.new(path, cache))
	end

	register :page do
	Filesystem::Page.new(
-	YAMLLoaders::Page.new(options[:path], current_site.try(:default_locale), cache),
+	YAMLLoaders::Page.new(path, current_site.try(:default_locale), cache),
	current_site, current_locale)
	end

	register :snippet do
	Filesystem::Snippet.new(
-	YAMLLoaders::Snippet.new(options[:path], current_site.try(:default_locale), cache),
+	YAMLLoaders::Snippet.new(path, current_site.try(:default_locale), cache),
	current_site, current_locale)
	end

	register :content_type do
	Filesystem::ContentType.new(
-	YAMLLoaders::ContentType.new(options[:path], cache),
+	YAMLLoaders::ContentType.new(path, cache),
	current_site, current_locale)
	end

	register :content_entry do
	Filesystem::ContentEntry.new(
-	YAMLLoaders::ContentEntry.new(options[:path], cache),
+	YAMLLoaders::ContentEntry.new(path, cache),
	current_site, current_locale, content_type)
	end

@@	@@ -52,7 +52,7 @@ module Locomotive

	register :translation do
	Filesystem::Translation.new(
-	YAMLLoaders::Translation.new(options[:path], cache))
+	YAMLLoaders::Translation.new(path, cache))
	end

	register :cache do

locomotive/steam/server.rb b/lib/locomotive/steam/server.rb +29 -22

@@	@@ -15,23 +15,24 @@ require_relative 'middlewares'
	module Locomotive::Steam
	class Server

-	attr_reader :options
+	# attr_reader :options

-	def initialize(options = {})
-	@options = prepare_options(options)
-	end
+	# def initialize(options = {})
+	# @options = prepare_options(options)
+	# end

	def to_app
	server = self

	Rack::Builder.new do
-	server.serve_assets(self) if server.options[:serve_assets]
+	server.serve_assets(self) if server.configuration.serve_assets
+
	use Middlewares::Favicon

	use Rack::Lint
-	use Rack::Session::Moneta, server.options[:moneta]
+	use Rack::Session::Moneta, server.configuration.moneta

-	use Middlewares::DefaultEnv, server.options
+	use Middlewares::DefaultEnv
	use Middlewares::Logging
	use Middlewares::Site
	use Middlewares::Timezone
@@	@@ -45,29 +46,35 @@ module Locomotive::Steam
	end
	end

-	def prepare_options(options)
-	{
-	serve_assets: false,
-	minify: false,
-	moneta: {
-	store: Moneta.new(:Memory, expires: true)
-	}
-	}.merge(options)
-	end
-
	def serve_assets(builder)
-	public_path = File.join(options[:path], 'public')
-
	builder.use ::Rack::Static, {
-	root: public_path,
+	root: configuration.assets_path,
	urls: ['/images', '/fonts', '/samples', '/media']
	}

	builder.use Middlewares::DynamicAssets, {
-	root: public_path,
-	minify: options[:minify_assets]
+	root: configuration.assets_path,
+	minify: configuration.minify_assets
	}
	end

+	def configuration
+	Locomotive::Steam.configuration
+	end
+
+	# def options
+
+	# end
+
+	# def prepare_options(options)
+	# {
+	# serve_assets: false,
+	# minify_assets: false,
+	# moneta: {
+	# store: Moneta.new(:Memory, expires: true)
+	# }
+	# }.merge(options)
+	# end
+
	end
	end

locomotive/steam/services.rb b/lib/locomotive/steam/services.rb +6 -9

@@	@@ -6,24 +6,21 @@ module Locomotive
	module Steam
	module Services

-	def self.build_instance(request = nil, options = {})
-	Instance.new(request, options)
+	def self.build_instance(request = nil)
+	Instance.new(request)
	end

-	class Instance < Struct.new(:request, :options)
+	class Instance < Struct.new(:request)

	include Morphine

	register :repositories do
-	if (klass = options[:repositories_builder_klass]).nil?
-	require_relative 'repositories/filesystem.rb'
-	klass = Steam::Repositories::Filesystem
-	end
-	klass.build_instance(nil, nil, options)
+	require_relative 'repositories/filesystem.rb'
+	Steam::Repositories::Filesystem.build_instance(nil, nil, configuration.site_path)
	end

	register :site_finder do
-	Steam::Services::SiteFinder.new(repositories.site, request, options)
+	Steam::Services::SiteFinder.new(repositories.site, request)
	end

	register :page_finder do

locomotive/steam/services/site_finder.rb b/lib/locomotive/steam/services/site_finder.rb +2 -2

@@	@@ -2,10 +2,10 @@ module Locomotive
	module Steam
	module Services

-	class SiteFinder < Struct.new(:repository, :request, :options)
+	class SiteFinder < Struct.new(:repository, :request)

	def find
-	repository.by_host(request.host, options)
+	repository.by_host(request.host)
	end

	end

spec/support/helpers.rb +8 -5

@@	@@ -22,12 +22,15 @@ module Spec
	output = ENV['STEAM_VERBOSE'] ? nil : File.join(default_fixture_site_path, 'log/steam.log')
	setup_common(output)

+	Locomotive::Steam.configure do \|config\|
+	config.mode = :test
+	config.site_path = default_fixture_site_path
+	config.serve_assets = true
+	config.minify_assets = true
+	end
+
	Locomotive::Common::Logger.info 'Server started...'
-	Locomotive::Steam::Server.new({
-	path: default_fixture_site_path,
-	serve_assets: true,
-	minify_assets: true
-	}).to_app
+	Locomotive::Steam::Server.new.to_app
	end

	def default_fixture_site_path

spec/unit/configuration_spec.rb +36 -0

@@	@@ -0,0 +1,36 @@
+	require 'spec_helper'
+
+	describe Locomotive::Steam::Configuration do
+
+	subject { Locomotive::Steam::Configuration.new }
+
+	describe 'default values' do
+
+	it { expect(subject.mode).to eq(:production) }
+	it { expect(subject.serve_assets).to eq(true) }
+	it { expect(subject.assets_path).to eq(nil) }
+
+	end
+
+	describe 'assign a different value' do
+
+	before { subject.mode = :test }
+	it { expect(subject.mode).to eq(:test) }
+
+	context 'the initial value was true' do
+
+	before { subject.serve_assets = false }
+	it { expect(subject.serve_assets).to eq(false) }
+
+	end
+
+	end
+
+	describe 'overriding a method' do
+
+	before { subject.site_path = '/42' }
+	it { expect(subject.assets_path).to eq('/42/public') }
+
+	end
+
+	end