Class: HTMLPipeline::Filter

Inherits:
Object
  • Object
show all
Defined in:
lib/html_pipeline/filter.rb

Overview

Base class for user content HTML filters. Each filter takes an HTML string, performs modifications on it, and/or writes information to a result hash. Filters must return a String with HTML markup.

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

ConvertFilter, NodeFilter, TextFilter

Defined Under Namespace

Classes: InvalidDocumentException

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(context: {}, result: {}) ⇒ Filter

Returns a new instance of Filter.



21
22
23
24
25
 
# File 'lib/html_pipeline/filter.rb', line 21

def initialize(context: {}, result: {})
  @context = context
  @result = result
  validate
end

Instance Attribute Details

#context ⇒ Object

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.



30
31
32
 
# File 'lib/html_pipeline/filter.rb', line 30

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.



35
36
37
 
# File 'lib/html_pipeline/filter.rb', line 35

def result
  @result
end

Class Method Details

.call(input, context: {}) ⇒ Object

Perform a filter on doc with the given context.

Returns a String comprised of HTML markup.

Raises:

  • (NoMethodError) 


49
50
51
 
# File 'lib/html_pipeline/filter.rb', line 49

def call(input, context: {})
  raise NoMethodError
end

Instance Method Details

#base_url ⇒ Object

The site’s base URL provided in the context hash, or ‘/’ when no base URL was specified.



58
59
60
 
# File 'lib/html_pipeline/filter.rb', line 58

def base_url
  context[:base_url] || "/"
end

#call ⇒ Object

The main filter entry point. The doc attribute is guaranteed to be a string when invoked. Subclasses should modify this text in place or extract information and add it to the context hash.

Raises:

  • (NoMethodError) 


41
42
43
 
# File 'lib/html_pipeline/filter.rb', line 41

def call
  raise NoMethodError
end

#has_ancestor?(element, ancestor) ⇒ 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.

Returns:

  • (Boolean) 


69
70
71
72
 
# File 'lib/html_pipeline/filter.rb', line 69

def has_ancestor?(element, ancestor)
  ancestors = element.ancestors
  ancestors.include?(ancestor)
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.

Raises:

  • (ArgumentError) 


80
81
82
83
84
85
86
87
 
# File 'lib/html_pipeline/filter.rb', line 80

def needs(*keys)
  missing = keys.reject { |key| context.include?(key) }

  return if missing.none?

  raise ArgumentError,
    "Missing context keys for #{self.class.name}: #{missing.map(&:inspect).join(", ")}"
end

#validate ⇒ Object

Make sure the context has everything we need. Noop: Subclasses can override.



54
 
# File 'lib/html_pipeline/filter.rb', line 54

def validate; end