Class: HTML::Pipeline::Filter
- Inherits:
-
Object
- Object
- HTML::Pipeline::Filter
- Defined in:
- lib/html/pipeline/filter.rb
Overview
Base class for user content HTML filters. Each filter takes an HTML string or Nokogiri::HTML::DocumentFragment, performs modifications and/or writes information to the result hash. Filters must return a DocumentFragment (typically the same instance provided to the call method) or a String with HTML markup.
Example filter that replaces all images with trollface:
class FuuuFilter < HTML::Pipeline::Filter
def call
doc.search('img').each do |img|
img['src'] = "http://paradoxdgn.com/junk/avatars/trollface.jpg"
end
end
end
The context Hash passes options to filters and should not be changed in place. A Result Hash allows filters to make extracted information available to the caller and is mutable.
Common context options:
:base_url - The site's base URL
:repository - A Repository providing context for the HTML being processed
Each filter may define additional options and output values. See the class docs for more info.
Direct Known Subclasses
CustomLinksFilter, RelativeLinksFilter, SVGTeX::PostFilter, SanitizationFilter, SyntaxHighlightFilter, TableOfContentsFilter, TextFilter
Defined Under Namespace
Classes: InvalidDocumentException
Instance Attribute Summary collapse
-
#context ⇒ Object
readonly
Public: Returns a simple Hash used to pass extra information into filters and also to allow filters to make extracted information available to the caller.
-
#result ⇒ Object
readonly
Public: Returns a Hash used to allow filters to pass back information to callers of the various Pipelines.
Class Method Summary collapse
-
.call(doc, context = nil, result = nil) ⇒ Object
Perform a filter on doc with the given context.
-
.to_document(input, context = nil) ⇒ Object
Like call but guarantees that a DocumentFragment is returned, even when the last filter returns a String.
-
.to_html(input, context = nil) ⇒ Object
Like call but guarantees that a string of HTML markup is returned.
Instance Method Summary collapse
-
#base_url ⇒ Object
The site’s base URL provided in the context hash, or ‘/’ when no base URL was specified.
-
#call ⇒ Object
The main filter entry point.
-
#current_user ⇒ Object
The User object provided in the context hash, or nil when no user was specified.
-
#doc ⇒ Object
The Nokogiri::HTML::DocumentFragment to be manipulated.
-
#has_ancestor?(node, tags) ⇒ Boolean
Helper method for filter subclasses used to determine if any of a node’s ancestors have one of the tag names specified.
-
#html ⇒ Object
The String representation of the document.
-
#initialize(doc, context = nil, result = nil) ⇒ Filter
constructor
A new instance of Filter.
-
#needs(*keys) ⇒ Object
Validator for required context.
-
#parse_html(html) ⇒ Object
Ensure the passed argument is a DocumentFragment.
-
#repository ⇒ Object
The Repository object provided in the context hash, or nil when no :repository was specified.
-
#validate ⇒ Object
Make sure the context has everything we need.
Constructor Details
#initialize(doc, context = nil, result = nil) ⇒ Filter
Returns a new instance of Filter.
32 33 34 35 36 37 38 39 40 41 42 43 |
# File 'lib/html/pipeline/filter.rb', line 32 def initialize(doc, context = nil, result = nil) if doc.kind_of?(String) @html = doc.to_str @doc = nil else @doc = doc @html = nil end @context = context || {} @result = result || {} validate end |
Instance Attribute Details
#context ⇒ Object (readonly)
Public: Returns a simple Hash used to pass extra information into filters and also to allow filters to make extracted information available to the caller.
48 49 50 |
# File 'lib/html/pipeline/filter.rb', line 48 def context @context end |
#result ⇒ Object (readonly)
Public: Returns a Hash used to allow filters to pass back information to callers of the various Pipelines. This can be used for #mentioned_users, for example.
53 54 55 |
# File 'lib/html/pipeline/filter.rb', line 53 def result @result end |
Class Method Details
.call(doc, context = nil, result = nil) ⇒ Object
Perform a filter on doc with the given context.
Returns a HTML::Pipeline::DocumentFragment or a String containing HTML markup.
129 130 131 |
# File 'lib/html/pipeline/filter.rb', line 129 def self.call(doc, context = nil, result = nil) new(doc, context, result).call end |
.to_document(input, context = nil) ⇒ Object
Like call but guarantees that a DocumentFragment is returned, even when the last filter returns a String.
135 136 137 138 |
# File 'lib/html/pipeline/filter.rb', line 135 def self.to_document(input, context = nil) html = call(input, context) HTML::Pipeline::parse(html) end |
.to_html(input, context = nil) ⇒ Object
Like call but guarantees that a string of HTML markup is returned.
141 142 143 144 145 146 147 148 |
# File 'lib/html/pipeline/filter.rb', line 141 def self.to_html(input, context = nil) output = call(input, context) if output.respond_to?(:to_html) output.to_html else output.to_s end end |
Instance Method Details
#base_url ⇒ Object
The site’s base URL provided in the context hash, or ‘/’ when no base URL was specified.
99 100 101 |
# File 'lib/html/pipeline/filter.rb', line 99 def base_url context[:base_url] || '/' end |
#call ⇒ Object
The main filter entry point. The doc attribute is guaranteed to be a Nokogiri::HTML::DocumentFragment when invoked. Subclasses should modify this document in place or extract information and add it to the context hash.
74 75 76 |
# File 'lib/html/pipeline/filter.rb', line 74 def call raise NotImplementedError end |
#current_user ⇒ Object
The User object provided in the context hash, or nil when no user was specified
93 94 95 |
# File 'lib/html/pipeline/filter.rb', line 93 def current_user context[:current_user] end |
#doc ⇒ Object
The Nokogiri::HTML::DocumentFragment to be manipulated. If the filter was provided a String, parse into a DocumentFragment the first time this method is called.
58 59 60 |
# File 'lib/html/pipeline/filter.rb', line 58 def doc @doc ||= parse_html(html) end |
#has_ancestor?(node, tags) ⇒ Boolean
Helper method for filter subclasses used to determine if any of a node’s ancestors have one of the tag names specified.
node - The Node object to check. tags - An array of tag name strings to check. These should be downcase.
Returns true when the node has a matching ancestor.
117 118 119 120 121 122 123 |
# File 'lib/html/pipeline/filter.rb', line 117 def has_ancestor?(node, ) while node = node.parent if .include?(node.name.downcase) break true end end end |
#html ⇒ Object
The String representation of the document. If a DocumentFragment was provided to the Filter, it is serialized into a String when this method is called.
65 66 67 68 |
# File 'lib/html/pipeline/filter.rb', line 65 def html raise InvalidDocumentException if @html.nil? && @doc.nil? @html || doc.to_html end |
#needs(*keys) ⇒ Object
Validator for required context. This will check that anything passed in contexts exists in @contexts
If any errors are found an ArgumentError will be raised with a message listing all the missing contexts and the filters that require them.
156 157 158 159 160 161 162 163 |
# File 'lib/html/pipeline/filter.rb', line 156 def needs(*keys) missing = keys.reject { |key| context.include? key } if missing.any? raise ArgumentError, "Missing context keys for #{self.class.name}: #{missing.map(&:inspect).join ', '}" end end |
#parse_html(html) ⇒ Object
Ensure the passed argument is a DocumentFragment. When a string is provided, it is parsed and returned; otherwise, the DocumentFragment is returned unmodified.
106 107 108 |
# File 'lib/html/pipeline/filter.rb', line 106 def parse_html(html) HTML::Pipeline.parse(html) end |
#repository ⇒ Object
The Repository object provided in the context hash, or nil when no :repository was specified.
It’s assumed that the repository context has already been checked for permissions
87 88 89 |
# File 'lib/html/pipeline/filter.rb', line 87 def repository context[:repository] end |
#validate ⇒ Object
Make sure the context has everything we need. Noop: Subclasses can override.
79 80 |
# File 'lib/html/pipeline/filter.rb', line 79 def validate end |