Class: Axlsx::Relationship

Inherits:
Object
  • Object
show all
Defined in:
lib/axlsx/rels/relationship.rb

Overview

Note:

Packages automatically manage relationships.

A relationship defines a reference between package parts.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source_obj, type, target, options = {}) ⇒ Relationship

Initializes a new relationship.

Parameters:

  • source_obj (Object) —

    see #source_obj

  • type (String) —

    The type of the relationship

  • target (String) —

    The target for the relationship

  • [Symbol] (Hash) —

    a customizable set of options



84
85
86
87
88
89
90
 
# File 'lib/axlsx/rels/relationship.rb', line 84

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

Instance Attribute Details

#Id ⇒ String (readonly)

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.

Returns:

  • (String) 


47
48
49
 
# File 'lib/axlsx/rels/relationship.rb', line 47

def Id
  @Id
end

#source_obj ⇒ Object (readonly)

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



77
78
79
 
# File 'lib/axlsx/rels/relationship.rb', line 77

def source_obj
  @source_obj
end

#Target ⇒ String

The location of the relationship target

Returns:

  • (String) 


51
52
53
 
# File 'lib/axlsx/rels/relationship.rb', line 51

def Target
  @Target
end

#TargetMode ⇒ Object

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.



73
74
75
 
# File 'lib/axlsx/rels/relationship.rb', line 73

def TargetMode
  @TargetMode
end

#Type ⇒ String

Note:

Supported types are defined as constants in Axlsx:

The type of relationship

Returns:

  • (String)

See Also:



67
68
69
 
# File 'lib/axlsx/rels/relationship.rb', line 67

def Type
  @Type
end

Class Method Details

.clear_ids_cache ⇒ Object

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).



29
30
31
 
# File 'lib/axlsx/rels/relationship.rb', line 29

def clear_ids_cache
  Thread.current[:axlsx_relationship_ids_cache] = nil
end

.ids_cache ⇒ Array

Keeps track of relationship ids in use.

Returns:

  • (Array) 


8
9
10
 
# File 'lib/axlsx/rels/relationship.rb', line 8

def ids_cache
  Thread.current[:axlsx_relationship_ids_cache] ||= {}
end

.initialize_ids_cache ⇒ Object

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).



18
19
20
 
# File 'lib/axlsx/rels/relationship.rb', line 18

def initialize_ids_cache
  Thread.current[:axlsx_relationship_ids_cache] = {}
end

.next_free_id ⇒ String

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.

Returns:

  • (String) 


38
39
40
 
# File 'lib/axlsx/rels/relationship.rb', line 38

def next_free_id
  "rId#{ids_cache.size + 1}"
end

Instance Method Details

#ids_cache_key ⇒ Array

TODO:

Implement comparison of #Target based on normalized path names.

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).

Returns:

  • (Array) 


121
122
123
124
125
 
# File 'lib/axlsx/rels/relationship.rb', line 121

def ids_cache_key
  key = [source_obj, self.Type, self.TargetMode]
  key << self.Target if self.TargetMode == :External
  key
end

#to_xml_string(str = '') ⇒ String

serialize relationship

Parameters:

  • str (String) (defaults to: '')

Returns:

  • (String) 


103
104
105
106
107
108
 
# File 'lib/axlsx/rels/relationship.rb', line 103

def to_xml_string(str = '')
  h = Axlsx.instance_values_for(self).reject { |k, _| k == "source_obj" }
  str << '<Relationship '
  str << (h.map { |key, value| '' << key.to_s << '="' << Axlsx::coder.encode(value.to_s) << '"' }.join(' '))
  str << '/>'
end