class Axlsx::Relationship
A relationship defines a reference between package parts. @note Packages automatically manage relationships.
Constants
- Target
- TargetMode
- Type
Attributes
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]
The location of the relationship target @return [String]
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.
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]
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 cached instances.
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).
Also, calling this avoids memory leaks (cached instances lingering around forever).
# File lib/axlsx/rels/relationship.rb, line 23 def clear_cached_instances @instances = [] end
Keeps track of all instances of this class. @return [Array]
# File lib/axlsx/rels/relationship.rb, line 10 def instances @instances ||= [] end
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 78 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 = if (existing = self.class.instances.find{ |i| should_use_same_id_as?(i) }) existing.Id else self.class.next_free_id end self.class.instances << self end
Generate and return a unique id (eg. ‘rId123`) Used for setting {#Id}.
The generated id depends on the number of cached instances, so using {clear_cached_instances} will automatically reset the generated ids, too. @return [String]
# File lib/axlsx/rels/relationship.rb, line 32 def next_free_id "rId#{@instances.size + 1}" end
Public Instance Methods
@see Target
# File lib/axlsx/rels/relationship.rb, line 92 def Target=(v) Axlsx::validate_string v; @Target = v end
@see TargetMode
# File lib/axlsx/rels/relationship.rb, line 97 def TargetMode=(v) RestrictionValidator.validate 'Relationship.TargetMode', [:External, :Internal], v; @TargetMode = v; end
@see Type
# File lib/axlsx/rels/relationship.rb, line 94 def Type=(v) Axlsx::validate_relationship_type v; @Type = v end
Whether this relationship should use the same id as ‘other`.
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. @param other [Relationship]
# File lib/axlsx/rels/relationship.rb, line 120 def should_use_same_id_as?(other) result = self.source_obj == other.source_obj && self.Type == other.Type && self.TargetMode == other.TargetMode if self.TargetMode == :External result &&= self.Target == other.Target end result end
serialize relationship @param [String] str @return [String]
# File lib/axlsx/rels/relationship.rb, line 102 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