class Webgen::ContentProcessor
Namespace for all content processors.
About¶ ↑
Content processors are used to process the content of paths, normally of paths in Webgen
Page
Format. However, they can potentially process any type of content, even binary content.
Implementing a content processor¶ ↑
A content processor only needs to respond to one method called call
. This method is invoked with a Webgen::Context
object that provides the whole context (especially the content and the node chain) and the method needs to return this object. During processing a content processor normally changes the content of the context but it does not need to.
This allows one to implement a content processor as a class with a class method called call
. Or as a Proc object.
The content processor has to be registered so that webgen knows about it, see ContentProcessor.register
for more information.
Sample Content Processor¶ ↑
The following sample content processor checks for a meta information replace_key
and replaces strings of the form 'replace_key:path/to/node' with a link to the specified node if it is found.
Note how the content node, the reference node and the destination node are used so that the correct meta information is used, the node is correctly resolved and the correct relative link is calculated respectively!
class Replacer def self.call(context) if !context.content_node['replace_key'].to_s.empty? context.content.gsub!(/#{context.content_node['replace_key']}:([\w\/.]+)/ ) do |match| link_node = context.ref_node.resolve($1, context.content_node.lang) if link_node context.dest_node.link_to(link_node, context.content_node.lang) else match end end end context rescue Exception => e raise "Error while replacing special key: #{e.message}" end end website.ext.content_processor.register Replacer, :name => 'replacer'
Public Instance Methods
Call the content processor object identified by the given name with the given context.
# File lib/webgen/content_processor.rb 102 def call(name, context) 103 extension(name).call(context) 104 rescue Webgen::Error => e 105 e.path = context.dest_node if e.path.to_s.empty? 106 e.location = "content_processor.#{name}" unless e.location 107 raise 108 rescue Exception => e 109 raise Webgen::RenderError.new(e, "content_processor.#{name}", context.dest_node) 110 end
Return the mapping of pre-processed file extension names to post-processed file extension names for the given content processor or a combination of all mappings if name
is nil
.
An empty map is returned if the content processor is not registered.
# File lib/webgen/content_processor.rb 137 def extension_map(name = nil) 138 if name.nil? 139 @extension_map ||= registered_extensions.inject({}) {|hash, data| hash.update(data.last.extension_map)} 140 elsif registered?(name) 141 ext_data(name).extension_map 142 else 143 {} 144 end 145 end
Return whether the content processor is processing binary data.
# File lib/webgen/content_processor.rb 129 def is_binary?(name) 130 registered?(name) && ext_data(name).type == :binary 131 end
Return the content processor name and the mapped extension of a pre-processed file extension or nil
if the extension cannot be mapped.
# File lib/webgen/content_processor.rb 149 def map_extension(ext) 150 registered_extensions.each do |name, data| 151 mapped_ext = data.extension_map[ext] 152 return [name, mapped_ext] if mapped_ext 153 end 154 nil 155 end
Normalize the content processor pipeline.
The pipeline parameter can be a String in the format 'a,b,c' or 'a, b, c' or an array '[a, b, c]' with content processor names a, b and c.
Raises an error if an unknown content processor is found.
Returns an array with valid content processors.
# File lib/webgen/content_processor.rb 120 def normalize_pipeline(pipeline) 121 pipeline = (pipeline.kind_of?(String) ? pipeline.split(/,\s*/) : pipeline.to_a) 122 pipeline.each do |processor| 123 raise Webgen::Error.new("Unknown content processor '#{processor}'") if !registered?(processor) 124 end 125 pipeline 126 end
Register a content processor.
The parameter klass
can either be a String containing the name of a class/module (which has to respond to :call) or an object that responds to :call. If the class is located under this namespace, only the class name without the hierarchy part is needed, otherwise the full class/module name including parent module/class names is needed.
Instead of registering an object that responds to #call, you can also provide a block that has to take one parameter (the context object).
Options:¶ ↑
- :name
-
The name for the content processor. If not set, it defaults to the snake-case version of the class name (without the hierarchy part). It should only contain letters.
- :type
-
Defines which type of content the content processor can process. Can be set to either :text (the default) or :binary.
- :ext_map
-
Defines a mapping of pre-processed file extension names to post-processed file extension names (e.g. {'sass' => 'css'}).
Examples:¶ ↑
content_processor.register('Kramdown') # registers Webgen::ContentProcessor::Kramdown content_processor.register('::Kramdown') # registers Kramdown !!! content_processor.register('MyModule::Doit', type: :binary) content_processor.register('doit') do |context| context.content = 'Nothing left.' end
# File lib/webgen/content_processor.rb 95 def register(klass, options={}, &block) 96 name = do_register(klass, options, true, &block) 97 ext_data(name).type = options[:type] || :text 98 ext_data(name).extension_map = options[:ext_map] || {} 99 end