webgen 0.5.7 → 0.5.8

data/lib/webgen/website.rb

@@ -1,5 +1,11 @@
 # -*- encoding: utf-8 -*-
 
+##
+# Welcome to the API documentation of wegen!
+#
+# Have a look at the base <a href=Webgen.html>webgen module</a> which provides a good starting point!
+
+
 # Standard lib requires
 require 'logger'
 require 'set'
@@ -18,16 +24,21 @@ require 'webgen/tree'
 
 # Files for autoloading
 require 'webgen/common'
+require 'webgen/context'
 require 'webgen/source'
 require 'webgen/output'
 require 'webgen/sourcehandler'
 require 'webgen/contentprocessor'
+require 'webgen/tag'
 
 # Load other needed files
 require 'webgen/path'
 require 'webgen/node'
 require 'webgen/page'
 
+# Load deprecated classes/methods/...
+require 'webgen/deprecated'
+
 
 # The Webgen namespace houses all classes/modules used by webgen.
 #
@@ -37,7 +48,7 @@ require 'webgen/page'
 # files. Despite this fact, the implementation also provides adequate support for using webgen as a
 # library and *full* *support* for extending it.
 #
-# = Extending webgen
+# == Extending webgen
 #
 # webgen can be extended very easily. Any file called <tt>init.rb</tt> put into the <tt>ext/</tt>
 # directory of the website or into one of its sub-directories is automatically loaded on
@@ -72,7 +83,7 @@ require 'webgen/page'
 #                     an easy way for users to include dynamic content such as automatically
 #                     generated menus.
 #
-# = Blackboard services
+# == Blackboard services
 #
 # The Blackboard class provides an easy communication facility between objects. It implements the
 # Observer pattern on the one side and allows the definition of services on the other side. One
@@ -93,7 +104,7 @@ require 'webgen/page'
 # <tt>:create_sitemap</tt>:: Common::Sitemap#create_sitemap
 # <tt>:create_directories</tt>:: SourceHandler::Directory#create_directories
 # <tt>:create_nodes</tt>:: SourceHandler::Main#create_nodes
-# <tt>:source_paths</tt>:: SourceHandler::Main#source_paths
+# <tt>:source_paths</tt>:: SourceHandler::Main#find_all_source_paths
 #
 # Following is the list of all messages that can be listened to:
 #
@@ -119,7 +130,7 @@ require 'webgen/page'
 # <tt>:before_node_deleted</tt>::
 #   See Tree#delete_node
 #
-# = Other places to look at
+# == Other places to look at
 #
 # Here is a list of modules/classes that are primarily used throughout webgen or provide useful
 # methods for developing extensions:
@@ -141,6 +152,25 @@ module Webgen
 
 
   # Represents a webgen website and is used to render it.
+  #
+  # Normally, webgen is used from the command line via the +webgen+ command or from Rakefiles via
+  # Webgen::WebgenTask. However, you can also easily use webgen as a library and this class provides
+  # the interface for this usage!
+  #
+  # Since a webgen website is, basically, just a directory, the only parameter needed for creating a
+  # new Website object is the website directory. After that you can work with the website:
+  #
+  # * If you want to render the website, you just need to call Website#render which initializes the
+  #   website and does all the rendering. When the method call returns, everything has been rendered.
+  #
+  # * If you want to remove the generated output, you just need to invoke Website#clean and it will
+  #   be done.
+  #
+  # * Finally, if you want to retrieve data from the website, you first have to call Website#init to
+  #   initialize the website. After that you can use the various accessors to retrieve the needed
+  #   data. *Note*: This is generally only useful if the website has been rendered because otherwise
+  #   there is no data to retrieve.
+  #
   class Website
 
     # Raised when the configuration file of the website is invalid.
@@ -169,16 +199,17 @@ module Webgen
     # The website directory.
     attr_reader :directory
 
-    # Create a new webgen website for the website in the directory +dir+. You can provide a
-    # block (has to take the configuration object as parameter) for adjusting the configuration
-    # values during the initialization.
-    def initialize(dir, logger=Webgen::Logger.new($stdout, false), &block)
+    # Create a new webgen website for the website in the directory +dir+. If +dir+ is +nil+, the
+    # environment variable +WEBGEN_WEBSITE+ or, if it is not set either, the current working
+    # directory is used. You can provide a block (has to take the configuration object as parameter)
+    # for adjusting the configuration values during the initialization.
+    def initialize(dir = nil, logger=Webgen::Logger.new($stdout, false), &block)
       @blackboard = nil
       @cache = nil
       @config = nil
       @logger = logger
       @config_block = block
-      @directory = dir
+      @directory = (dir.nil? ? (ENV['WEBGEN_WEBSITE'].to_s.empty? ? Dir.pwd : ENV['WEBGEN_WEBSITE']) : dir)
     end
 
     # Define a service +service_name+ provided by the instance of +klass+. The parameter +method+
@@ -254,11 +285,11 @@ module Webgen
     # The provided block is executed within a proper environment sothat any object can access the
     # Website object.
     def execute_in_env
-      set_back = Thread.current[:webgen_website].nil?
+      set_back = Thread.current[:webgen_website]
       Thread.current[:webgen_website] = self
       yield
     ensure
-      Thread.current[:webgen_website] = nil if set_back
+      Thread.current[:webgen_website] = set_back
     end
 
     #######

data/lib/webgen/websiteaccess.rb

@@ -2,7 +2,7 @@
 
 module Webgen
 
-  # Mixed into modules/classes that need access to the current website object.
+  # Should be mixed into modules/classes that need access to the current website object.
   module WebsiteAccess
 
     # The methods of this module are available on classes that include WebsiteAccess.

data/lib/webgen/websitemanager.rb

@@ -6,107 +6,102 @@ require 'webgen/website'
 
 module Webgen
 
-  # This class is used for managing webgen websites. It provides access to website templates and
-  # styles defined as resources and makes it easy to apply them to a webgen website.
+  # This class is used for managing webgen websites. It provides access to website bundles defined
+  # as resources and makes it easy to apply them to a webgen website.
   #
-  # = General information
+  # == General information
   #
   # Currently, the following actions are supported:
   #
-  # * creating a website based on a website template (#create_website)
-  # * applying a template to an existing website (#apply_template)
-  # * applying a style to an existing website (#apply_style)
+  # * creating a website based on a website bundle (#create_website)
+  # * applying a bundle to an existing website (#apply_bundle)
   #
-  # A website template defines some initial pages which should be filled with real data. For
-  # example, the @project@ template defines several pages which are useful for software projects
-  # including a features and about page.
+  # Bundles are partial webgen websites that contain certain functionality. For example, most of the
+  # bundles shipped with webgen are style bundles that define the basic page layout or how image
+  # galleries should look like. So style bundles are basically used to change the appearance of
+  # parts (or the whole) website. This makes them a powerful tool as this plugin makes it easy to
+  # change to another style bundle later!
   #
-  # A style defines, for example, the basic page layout (in the case of website styles) or how image
-  # galleries should look like (in the case of gallery styles). So styles are basically used to
-  # change the appearance of parts (or the whole) website. This makes them a powerful tool as this
-  # plugin makes it easy to change a style later!
+  # However, not all bundles have to be style bundles. For example, you could as easily create a
+  # bundle for a plugin or for a complete website (e.g. a blog template).
   #
-  # = website template and style resource naming convention
+  # == website bundle resource naming convention
   #
-  # Styles and website templates are defined using resources. Each such resource has to be a
-  # directory containing an optional README file in YAML format in which key-value pairs provide
-  # additional information about the style or website template. All other files/directories in the
-  # directory are copied to the root of the destination webgen website when the style or website
-  # template is used.
+  # The shipped bundles are defined using resources. Each such resource has to be a directory
+  # containing an optional README file in YAML format in which key-value pairs provide additional
+  # information about the bundle (e.g. copyright information, description, ...). All other
+  # files/directories in the directory are copied to the root of the destination webgen website when
+  # the bundle is used.
   #
-  # This class uses a special naming convention to recognize website templates and styles:
+  # This class uses a special naming convention to recognize website bundles:
   #
-  # * A resource named <tt>webgen-website-template-TEMPLATE_NAME</tt> is considered to be a website
-  #   template called TEMPLATE_NAME and can be later accessed using this name.
+  # * A resource named <tt>webgen-website-bundle-CATEGORY-NAME</tt> is considered to be a bundle in
+  #   the category CATEGORY called NAME (where CATEGORY is optional). There are no fixed categories,
+  #   one can use anything here! The shipped style bundles are located in the 'style' category. You
+  #   need to use the the full name, i.e. CATEGORY-NAME, for accessing a bundle later.
   #
-  # * A resource named <tt>webgen-website-style-CATEGORY-STYLE_NAME</tt> is considered to be a style
-  #   in the category CATEGORY called STYLE_NAME. There are no fixed categories, one can use
-  #   anything here!  Again, the style can later be accessed by providing the category and style
-  #   name.
-  #
-  # Website template names have to be unique and style names have to be unique in respect to their
-  # categories!
-  #
-  # Note: All styles without a category or which are in the category 'website' are website styles.
+  # Website bundle names have to be unique!
   class WebsiteManager
 
-    # A hash with the available website templates (mapping name to infos).
-    attr_reader :templates
-
-    # A hash with the available website styles (mapping name to infos).
-    attr_reader :styles
+    # A hash with the available website bundles (mapping name to infos).
+    attr_reader :bundles
 
     # The used Website object.
     attr_reader :website
 
-    # Create a new WebsiteManager for the website +dir+.
+    # Create a new WebsiteManager.
+    #
+    # If +dir+ is a String, then the website manager is created for the website in the directory
+    # +dir+.
+    #
+    # If +dir+ is a Website object, the website manager is created for the website represented by
+    # +dir+. If the website object is initialized if it isn't already.
     def initialize(dir)
-      @website = Webgen::Website.new(dir)
-      @website.init
-      @styles = {}
-      @templates = {}
+      if dir.kind_of?(Webgen::Website)
+        @website = dir
+        @website.init if @website.config.nil?
+      else
+        @website = Webgen::Website.new(dir)
+        @website.init
+      end
+      @bundles = {}
 
       @website.execute_in_env do
-        [['webgen-website-style-', @styles], ['webgen-website-template-', @templates]].each do |prefix, var|
-          @website.config['resources'].select {|name, data| name =~ /^#{prefix}/}.each do |name, data|
-            paths = Webgen::Source::Resource.new(name).paths
-            readme = paths.select {|path| path == '/README' }.first
-            paths.delete(readme) if readme
-            infos = OpenStruct.new(readme.nil? ? {} : YAML::load(readme.io.data))
-            infos.paths = paths
-            var[name.sub(prefix, '')] = infos
-          end
+        prefix = "webgen-website-bundle-"
+        @website.config['resources'].select {|name, data| name =~ /^#{prefix}/}.each do |name, data|
+          add_source(Webgen::Source::Resource.new(name), name.sub(prefix, ''))
         end
       end
     end
 
-    # Create the basic website skeleton (without any template or style applied).
+    # Treat the +source+ as a website bundle and make it available to the WebsiteManager under
+    # +name+.
+    def add_source(source, name)
+      paths = source.paths.dup
+      readme = paths.select {|path| path == '/README' }.first
+      paths.delete(readme) if readme
+      infos = OpenStruct.new(readme.nil? ? {} : YAML::load(readme.io.data))
+      infos.paths = paths
+      @bundles[name] = infos
+    end
+
+    # Create the basic website skeleton (without any bundle applied).
     def create_website
       raise "Directory <#{@website.directory}> does already exist!" if File.exists?(@website.directory)
       @website.execute_in_env { write_paths(Webgen::Source::Resource.new('webgen-website-skeleton').paths) }
     end
 
-    # Apply the given +template+ to the website by copying the template files.
-    def apply_template(name)
-      write_paths_to_website(@templates[name], 'template')
-    end
-
-    # Apply the given website style +name+ to the website by copying the styles files.
-    def apply_style(name)
-      write_paths_to_website(@styles[name], 'style')
+    # Apply the given +bundle+ to the website by copying the files.
+    def apply_bundle(bundle)
+      raise ArgumentError.new("Invalid bundle name") if !@bundles.has_key?(bundle)
+      raise "Directory <#{@website.directory}> does not exist!" unless File.exists?(@website.directory)
+      write_paths(@bundles[bundle].paths)
     end
 
     #######
     private
     #######
 
-    # Do some sanity checks and write the +paths+ from +infos+ to the website directory.
-    def write_paths_to_website(infos, infos_type)
-      raise ArgumentError.new("Invalid #{infos_type} name") if infos.nil?
-      raise "Directory <#{@website.directory}> does not exist!" unless File.exists?(@website.directory)
-      write_paths(infos.paths)
-    end
-
     # Write the paths to the website directory.
     def write_paths(paths)
       paths.each do |path|

data/man/man1/webgen.1

@@ -36,6 +36,10 @@ Show generic help.
 Show the version of the program and exit.
 .SH COMMANDS
 .TP
+\fBapply\fR
+Applies a website bundle to an existing website. The \fIbundle\fR argument may either be the name of
+a bundle shipped with webgen or an URL to a (gzipped) tar archive bundle.
+.TP
 \fBcreate\fR
 Creates the basic directories and files for webgen.  This includes the source and
 output directories as well as an empty extensions directory.  Also, a basic template plus a CSS and

data/misc/default.css

@@ -382,3 +382,16 @@ blockquote.blog-entry-details {
 .blog-entry-date, .blog-entry-author {
   font-weight: bold;
 }
+
+
+/* website style preview classes */
+div.website-styles {
+  margin: 0px 10px;
+}
+
+div.website-styles object {
+  border: 1px solid black;
+  width: 100%;
+  height: 300px;
+  overflow: hidden;
+}

data/misc/default.template

@@ -28,7 +28,7 @@
 
       <div id="sidebar" >
 
-        <% if !node.children.empty? %>
+        <% if !context.node.children.empty? %>
         <h1>Contents</h1>
         <% end %>
 

data/misc/htmldoc.metainfo

@@ -22,4 +22,5 @@ extensions.*.html:
   in_menu: true
   sort_info: 50
 
-
+images/:
+  index_path: ~

data/misc/style.page

@@ -0,0 +1,33 @@
+---
+title: Style Example
+---
+## General Information
+
+This sample website showcases the website style *<%= context.content_node.parent.cn %>*. Most
+website styles include dynamic parts by default, for example, automatically generated menus and
+breadcrumb trails. All such dynamic parts are active in this showcase like they would be on a normal
+website.
+
+## How to use this style
+
+This website style can be used when creating a new website by using the following command:
+
+    webgen create -b default -b <%= context.content_node.parent.cn %> SITE_DIR
+
+Or it can be applied later on to an already existing website by using the following command:
+
+    webgen apply <%= context.content_node.parent.cn %>
+
+## Style Information
+
+<dl>
+<%
+require 'webgen/websitemanager'
+infos = Webgen::WebsiteManager.new(context.website).bundles[context.content_node.parent.cn]
+infos.instance_eval {@table}.sort {|(ak,av), (bk,bv)| ak.to_s <=> bk.to_s}.each do |name, value|
+next if name.to_s == 'paths'
+%>
+<dt><%= name.to_s.capitalize %></dt>
+<dd><%= ::ERB::Util::h(value) %></dd>
+<% end %>
+</dl>

data/test/test_cli.rb

@@ -7,15 +7,9 @@ class TestCLICommandParser < Test::Unit::TestCase
 
   def test_initialize
     cli = Webgen::CLI::CommandParser.new
-    assert_equal('render', cli.main_command.default_command)
     assert_equal(:normal, cli.verbosity)
     assert_equal(Logger::WARN, cli.log_level)
-    assert_equal(Dir.pwd, cli.directory)
+    assert_equal(nil, cli.directory)
   end
 
-  def test_website_from_env
-    ENV['WEBGEN_WEBSITE'] = '/webgen/test/site'
-    cli = Webgen::CLI::CommandParser.new
-    assert_equal('/webgen/test/site', cli.directory)
-  end
 end

data/test/test_common_sitemap.rb

@@ -48,11 +48,11 @@ class TestCommonSitemap < Test::Unit::TestCase
 
     @nodes[:file11_en].unflag(:dirty)
     @website.blackboard.dispatch_msg(:node_changed?, @nodes[:file11_en])
-    assert(!@nodes[:file11_en].flagged(:dirty))
+    assert(!@nodes[:file11_en].flagged?(:dirty))
 
     @nodes[:file11_en].flag(:dirty_meta_info)
     @website.blackboard.dispatch_msg(:node_changed?, @nodes[:file11_en])
-    assert(@nodes[:file11_en].flagged(:dirty))
+    assert(@nodes[:file11_en].flagged?(:dirty))
   end
 
 end

data/test/test_contentprocessor_blocks.rb

@@ -16,12 +16,16 @@ class TestContentProcessorBlocks < Test::Unit::TestCase
     template.node_info[:page] = Webgen::Page.from_data("--- name:content pipeline:blocks\nbefore<webgen:block name='content' />after")
     processors = { 'blocks' => obj }
 
-    context = Webgen::ContentProcessor::Context.new(:chain => [node], :processors => processors)
+    context = Webgen::Context.new(:chain => [node], :processors => processors)
     context.content = '<webgen:block name="content" /><webgen:block name="content" chain="template;test" />'
     obj.call(context)
     assert_equal('databeforedataafter', context.content)
     assert_equal(Set.new([node.absolute_lcn, template.absolute_lcn]), node.node_info[:used_nodes])
 
+    context.content = '<webgen:block name="content" node="next" /><webgen:block name="content" chain="template;test" />'
+    obj.call(context)
+    assert_equal('databeforedataafter', context.content)
+
     context.content = '<webgen:block name="nothing"/>'
     assert_raise(RuntimeError) { obj.call(context) }
 
@@ -50,6 +54,15 @@ class TestContentProcessorBlocks < Test::Unit::TestCase
     context.content = '<webgen:block name="invalid" node="first" notfound="ignore" /><webgen:block name="content" />'
     obj.call(context)
     assert_equal('beforedataafter', context.content)
+
+    context[:chain] = [node, template]
+    context.content = '<webgen:block name="other" node="current" />'
+    obj.call(context)
+    assert_equal('other', context.content)
+
+    context.content = '<webgen:block name="other" node="current" chain="template"/>'
+    obj.call(context)
+    assert_equal('other', context.content)
   end
 
 end