class Axlsx::Relationship

A relationship defines a reference between package parts. @note Packages automatically manage relationships.

Constants

Target
TargetMode
Type

Attributes

Id[R]

The id of the relationship (eg. “rId123”). Most instances get their own unique id. However, some instances need to share the same id – see {#should_use_same_id_as?} for details. @return [String]

Target[R]

The location of the relationship target @return [String]

TargetMode[R]

The target mode of the relationship used for hyperlink type relationships to mark the relationship to an external resource TargetMode can be specified during initialization by passing in a :target_mode option Target mode must be :external for now.

Type[R]

The type of relationship @note Supported types are defined as constants in Axlsx: @see XML_NS_R @see TABLE_R @see PIVOT_TABLE_R @see WORKBOOK_R @see WORKSHEET_R @see APP_R @see RELS_R @see CORE_R @see STYLES_R @see CHART_R @see DRAWING_R @return [String]

source_obj[R]

The source object the relations belongs to (e.g. a hyperlink, drawing, …). Needed when looking up the relationship for a specific object (see {Relationships#for}).

Public Class Methods

clear_ids_cache() click to toggle source

Clear cached ids.

This should be called after serializing a package (see {Package#serialize} and {Package#to_stream}) to free the memory allocated for cache.

Also, calling this avoids memory leaks (cached ids lingering around forever).

# File lib/axlsx/rels/relationship.rb, line 31
def clear_ids_cache
  Thread.current[:axlsx_relationship_ids_cache] = nil
end
ids_cache() click to toggle source

Keeps track of relationship ids in use. @return [Array]

# File lib/axlsx/rels/relationship.rb, line 10
def ids_cache
  Thread.current[:axlsx_relationship_ids_cache] ||= {}
end
initialize_ids_cache() click to toggle source

Initialize cached ids.

This should be called before serializing a package (see {Package#serialize} and {Package#to_stream}) to make sure that serialization is idempotent (i.e. Relationship instances are generated with the same IDs everytime the package is serialized).

# File lib/axlsx/rels/relationship.rb, line 20
def initialize_ids_cache
  Thread.current[:axlsx_relationship_ids_cache] = {}
end
new(source_obj, type, target, options={}) click to toggle source

Initializes a new relationship. @param [Object] source_obj see {#source_obj} @param [String] type The type of the relationship @param [String] target The target for the relationship @option [Symbol] :target_mode only accepts :external.

# File lib/axlsx/rels/relationship.rb, line 86
def initialize(source_obj, type, target, options={})
  @source_obj = source_obj
  self.Target=target
  self.Type=type
  self.TargetMode = options[:target_mode] if options[:target_mode]
  @Id = (self.class.ids_cache[ids_cache_key] ||= self.class.next_free_id)
end
next_free_id() click to toggle source

Generate and return a unique id (eg. `rId123`) Used for setting {#Id}.

The generated id depends on the number of previously cached ids, so using {clear_ids_cache} will automatically reset the generated ids, too. @return [String]

# File lib/axlsx/rels/relationship.rb, line 40
def next_free_id
  "rId#{ids_cache.size + 1}"
end

Public Instance Methods

Target=(v) click to toggle source

@see Target

# File lib/axlsx/rels/relationship.rb, line 95
def Target=(v) Axlsx::validate_string v; @Target = v end
TargetMode=(v) click to toggle source

@see TargetMode

# File lib/axlsx/rels/relationship.rb, line 100
def TargetMode=(v) RestrictionValidator.validate 'Relationship.TargetMode', [:External, :Internal], v; @TargetMode = v; end
Type=(v) click to toggle source

@see Type

# File lib/axlsx/rels/relationship.rb, line 97
def Type=(v) Axlsx::validate_relationship_type v; @Type = v end
ids_cache_key() click to toggle source

A key that determines whether this relationship should use already generated id.

Instances designating the same relationship need to use the same id. We can not simply compare the {#Target} attribute, though: `foo/bar.xml`, `../foo/bar.xml`, `../../foo/bar.xml` etc. are all different but probably mean the same file (this is especially an issue for relationships in the context of pivot tables). So lets just ignore this attribute for now (except when {#TargetMode} is set to `:External` – then {#Target} will be an absolute URL and thus can safely be compared).

@todo Implement comparison of {#Target} based on normalized path names. @return [Array]

# File lib/axlsx/rels/relationship.rb, line 123
def ids_cache_key
  key = [source_obj, self.Type, self.TargetMode]
  key << self.Target if self.TargetMode == :External
  key
end
to_xml_string(str = '') click to toggle source

serialize relationship @param [String] str @return [String]

# File lib/axlsx/rels/relationship.rb, line 105
def to_xml_string(str = '')
  h = self.instance_values.reject{|k, _| k == "source_obj"}
  str << '<Relationship '
  str << (h.map { |key, value| '' << key.to_s << '="' << Axlsx::coder.encode(value.to_s) << '"'}.join(' '))
  str << '/>'
end