Class: Banzai::ReferenceParser::BaseParser

Inherits:
Object
  • Object
show all
Defined in:
lib/banzai/reference_parser/base_parser.rb

Overview

Base class for reference parsing classes.

Each parser should also specify its reference type by calling `self.reference_type = …` in the body of the class. The value of this method should be a symbol such as `:issue` or `:merge_request`. For example:

class IssueParser < BaseParser
  self.reference_type = :issue
end

The reference type is used to determine what nodes to pass to the `referenced_by` method.

Parser classes should either implement the instance method `references_relation` or overwrite `referenced_by`. The `references_relation` method is supposed to return an ActiveRecord::Relation used as a base relation for retrieving the objects referenced in a set of HTML nodes.

Each class can implement two additional methods:

  • `nodes_user_can_reference`: returns an Array of nodes the given user can refer to.

  • `nodes_visible_to_user`: returns an Array of nodes that are visible to the given user.

You only need to overwrite these methods if you want to tweak who can see which references. For example, the IssueParser class defines its own `nodes_visible_to_user` method so it can ensure users can only see issues they have access to.

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(context) ⇒ BaseParser

context - An instance of `Banzai::RenderContext`.


51
52
53
# File 'lib/banzai/reference_parser/base_parser.rb', line 51

def initialize(context)
  @context = context
end

Class Attribute Details

.reference_optionsObject

Returns the value of attribute reference_options.


38
39
40
# File 'lib/banzai/reference_parser/base_parser.rb', line 38

def reference_options
  @reference_options
end

.reference_typeObject

Returns the value of attribute reference_type.


38
39
40
# File 'lib/banzai/reference_parser/base_parser.rb', line 38

def reference_type
  @reference_type
end

Class Method Details

.data_attributeObject

Returns the attribute name containing the value for every object to be parsed by the current parser.

For example, for a parser class that returns “Animal” objects this attribute would be “data-animal”.


46
47
48
# File 'lib/banzai/reference_parser/base_parser.rb', line 46

def self.data_attribute
  @data_attribute ||= "data-#{reference_type.to_s.dasherize}"
end

Instance Method Details

#can?(user, permission, subject = :global) ⇒ Boolean

Returns:

  • (Boolean)

230
231
232
# File 'lib/banzai/reference_parser/base_parser.rb', line 230

def can?(user, permission, subject = :global)
  Ability.allowed?(user, permission, subject)
end

#collection_cache_key(collection) ⇒ Object

Returns the cache key to use for a collection.


193
194
195
# File 'lib/banzai/reference_parser/base_parser.rb', line 193

def collection_cache_key(collection)
  collection.respond_to?(:model) ? collection.model : collection
end

#collection_objects_for_ids(collection, ids) ⇒ Object

Queries the collection for the objects with the given IDs.

If the RequestStore module is enabled this method will only query any objects that have not yet been queried. For objects that have already been queried the object is returned from the cache.


172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
# File 'lib/banzai/reference_parser/base_parser.rb', line 172

def collection_objects_for_ids(collection, ids)
  if Gitlab::SafeRequestStore.active?
    ids = ids.map(&:to_i).uniq

    cache = collection_cache[collection_cache_key(collection)]
    to_query = ids - cache.keys

    unless to_query.empty?
      collection.where(id: to_query).each { |row| cache[row.id] = row }
    end

    ids.each_with_object([]) do |id, array|
      row = cache[id]
      array << row if row
    end
  else
    collection.where(id: ids)
  end
end

#find_projects_for_hash_keys(hash) ⇒ Object


234
235
236
# File 'lib/banzai/reference_parser/base_parser.rb', line 234

def find_projects_for_hash_keys(hash)
  collection_objects_for_ids(Project, hash.keys)
end

#gather_attributes_per_project(nodes, attribute) ⇒ Object

Returns a Hash containing attribute values per project ID.

The returned Hash uses the following format:

{ project id => [value1, value2, ...] }

nodes - An Array of HTML nodes to process. attribute - The name of the attribute (as a String) for which to gather

values.

Returns a Hash.


109
110
111
112
113
114
115
116
117
118
119
120
# File 'lib/banzai/reference_parser/base_parser.rb', line 109

def gather_attributes_per_project(nodes, attribute)
  per_project = Hash.new { |hash, key| hash[key] = Set.new }

  nodes.each do |node|
    project_id = node.attr('data-project').to_i
    id = node.attr(attribute)

    per_project[project_id] << id if id
  end

  per_project
end

#gather_references(nodes, ids_only: false) ⇒ Object

Gathers the references for the given HTML nodes. Returns visible references and a list of nodes which are not visible to the user


212
213
214
215
216
217
# File 'lib/banzai/reference_parser/base_parser.rb', line 212

def gather_references(nodes, ids_only: false)
  nodes = nodes_user_can_reference(current_user, nodes)
  visible = nodes_visible_to_user(current_user, nodes)

  { visible: referenced_by(visible, ids_only: ids_only), nodes: nodes, visible_nodes: visible }
end

#grouped_objects_for_nodes(nodes, collection, attribute) ⇒ Object

Returns a Hash containing objects for an attribute grouped per the nodes that reference them.

The returned Hash uses the following format:

{ node => row }

nodes - An Array of HTML nodes to process.

collection - The model or ActiveRecord relation to use for retrieving

rows from the database.

attribute - The name of the attribute containing the primary key values

for every row.

Returns a Hash.


138
139
140
141
142
143
144
145
146
147
148
149
150
151
# File 'lib/banzai/reference_parser/base_parser.rb', line 138

def grouped_objects_for_nodes(nodes, collection, attribute)
  return {} if nodes.empty?

  ids = unique_attribute_values(nodes, attribute)
  collection_objects = collection_objects_for_ids(collection, ids)
  objects_by_id = collection_objects.index_by(&:id)

  nodes.each_with_object({}) do |node, hash|
    if node.has_attribute?(attribute)
      obj = objects_by_id[node.attr(attribute).to_i]
      hash[node] = obj if obj
    end
  end
end

#nodes_user_can_reference(user, nodes) ⇒ Object

Returns all the nodes containing references that the user can refer to.


60
61
62
# File 'lib/banzai/reference_parser/base_parser.rb', line 60

def nodes_user_can_reference(user, nodes)
  nodes
end

#nodes_visible_to_user(user, nodes) ⇒ Object

Returns all the nodes that are visible to the given user.


65
66
67
68
69
70
71
72
73
74
75
76
# File 'lib/banzai/reference_parser/base_parser.rb', line 65

def nodes_visible_to_user(user, nodes)
  projects = lazy { projects_for_nodes(nodes) }
  project_attr = 'data-project'

  nodes.select do |node|
    if node.has_attribute?(project_attr)
      can_read_reference?(user, projects[node], node)
    else
      true
    end
  end
end

#process(documents, ids_only: false) ⇒ Object

Processes the list of HTML documents and returns an Array containing all the references.


199
200
201
202
203
204
205
206
207
208
# File 'lib/banzai/reference_parser/base_parser.rb', line 199

def process(documents, ids_only: false)
  type = self.class.reference_type
  reference_options = self.class.reference_options

  nodes = documents.flat_map do |document|
    Querying.css(document, "a[data-reference-type='#{type}'].gfm", reference_options).to_a
  end

  gather_references(nodes, ids_only: ids_only)
end

#project_for_node(node) ⇒ Object


55
56
57
# File 'lib/banzai/reference_parser/base_parser.rb', line 55

def project_for_node(node)
  context.project_for_node(node)
end

#projects_for_nodes(nodes) ⇒ Object

Returns a Hash containing the projects for a given list of HTML nodes.

The returned Hash uses the following format:

{ node => project }

225
226
227
228
# File 'lib/banzai/reference_parser/base_parser.rb', line 225

def projects_for_nodes(nodes)
  @projects_for_nodes ||=
    grouped_objects_for_nodes(nodes, Project.includes(:project_feature), 'data-project')
end

#referenced_by(nodes, options = {}) ⇒ Object

Returns an Array of objects referenced by any of the given HTML nodes.


79
80
81
82
83
84
85
86
87
88
89
# File 'lib/banzai/reference_parser/base_parser.rb', line 79

def referenced_by(nodes, options = {})
  ids = unique_attribute_values(nodes, self.class.data_attribute)

  return ids if options.fetch(:ids_only, false)

  if ids.empty?
    references_relation.none
  else
    references_relation.where(id: ids)
  end
end

#references_relationObject

Returns the ActiveRecord::Relation to use for querying references in the DB.

Raises:

  • (NotImplementedError)

93
94
95
96
# File 'lib/banzai/reference_parser/base_parser.rb', line 93

def references_relation
  raise NotImplementedError,
    "#{self.class} does not implement #{__method__}"
end

#unique_attribute_values(nodes, attribute) ⇒ Object

Returns an Array containing all unique values of an attribute of the given nodes.


155
156
157
158
159
160
161
162
163
164
165
# File 'lib/banzai/reference_parser/base_parser.rb', line 155

def unique_attribute_values(nodes, attribute)
  values = Set.new

  nodes.each do |node|
    if node.has_attribute?(attribute)
      values << node.attr(attribute)
    end
  end

  values.to_a
end