Class: Axlsx::Package

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

Overview

Package is responsible for managing all the bits and peices that Open Office XML requires to make a valid xlsx document including valdation and serialization.

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Package) initialize(options = {}) {|_self| ... }

Initializes your package

Examples:

Package.new :author => ‘you!’, :workbook => Workbook.new 


    
  


Parameters:


    
  
    
  • 
      
        options
      
      
        (Hash)
      
      
        (defaults to: {})
      
      
        —
        
    
A hash that you can use to specify the author and workbook for this
package.

    

    
      
    
    • 
  



  
    
    
    
Options Hash (options):

    
    
      
        
  • 
          :author
          (String)
          
            
          
          — 
    
The author of the document

    

    
        
    • 
      
    

  


Yields:


    
  
    
  • 
      
      
        (_self)
      
      
      
    
    • 
  



Yield Parameters:





  

    
      


28
29
30
31
32

    		
    
      
# File 'lib/axlsx/package.rb', line 28

def initialize(options={})
  @core, @app = Core.new, App.new
  @core.creator = options[:author] || @core.creator
  yield self if block_given?
end


    		
  





  



  

    
Instance Attribute Details

    
      
      
      
      

  

  
    - (Workbook) workbook 
  

  


  

    
  

    Note: 
    

As there are multiple ways to instantiate a workbook for the package, here
are a few examples:



  # assign directly during package instanciation
  wb = Package.new(:workbook => Workbook.new).workbook

  # get a fresh workbook automatically from the package
  wb = Pacakge.new().workbook
  #     # set the workbook after creating the package
  wb = Package.new().workbook = Workbook.new




  




The workbook this package will serialize or validate.




  





  

Returns:


    
  
    
  • 
      
      
        (Workbook)
      
      
      
        —
        
    
If no workbook instance has been assigned with this package a new Workbook
instance is returned.

    

    
      
    
    • 
  



Raises:


    
  
    
  • 
      
      
        
      
      
      
        
        
    
ArgumentError if workbook parameter is not a Workbook instance.

    

    
      
    
    • 
  





  

    
      


21
22
23

    		
    
      
# File 'lib/axlsx/package.rb', line 21

def workbook
  @workbook || @workbook = Workbook.new
end


    		
  





    
  



  

    
Instance Method Details

    
    
      

  

  
    - (ContentType) base_content_types 
  

  


  

    

Creates the minimum content types for generating a valid xlsx document.




  





  

Returns:





  

    
      


182
183
184
185
186
187
188
189
190
191
192

    		
    
      
# File 'lib/axlsx/package.rb', line 182

def base_content_types
  c_types = ContentType.new()
  c_types <<  Default.new(:ContentType => RELS_CT, :Extension => RELS_EX)
  c_types <<  Default.new(:Extension => XML_EX, :ContentType => XML_CT)
  c_types << Override.new(:PartName => "/#{APP_PN}", :ContentType => APP_CT)
  c_types << Override.new(:PartName => "/#{CORE_PN}", :ContentType => CORE_CT)
  c_types << Override.new(:PartName => "/xl/#{STYLES_PN}", :ContentType => STYLES_CT)
  c_types << Axlsx::Override.new(:PartName => "/#{WORKBOOK_PN}", :ContentType => WORKBOOK_CT)      
  c_types.lock
  c_types
end


    		
  





    
      

  

  
    - (ContentType) content_types 
  

  


  

    

Appends override objects for drawings, charts, and sheets as they exist in
your workbook to the default content types.




  





  

Returns:





  

    
      


151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177

    		
    
      
# File 'lib/axlsx/package.rb', line 151

def content_types
  c_types = base_content_types
  workbook.drawings.each do |drawing|
    c_types << Axlsx::Override.new(:PartName => "/xl/#{drawing.pn}", 
                                   :ContentType => DRAWING_CT)
  end
  workbook.charts.each do |chart|
    c_types << Axlsx::Override.new(:PartName => "/xl/#{chart.pn}", 
                                   :ContentType => CHART_CT)                    
  end
  workbook.worksheets.each do |sheet|
    c_types << Axlsx::Override.new(:PartName => "/xl/#{sheet.pn}", 
                                     :ContentType => WORKSHEET_CT)
  end
  exts = workbook.images.map { |image| image.extname }
  exts.uniq.each do |ext|
    ct = if  ['jpeg', 'jpg'].include?(ext)
           JPEG_CT
         elsif ext == 'gif'
           GIF_CT
         elsif ext == 'png'
           PNG_CT
         end
    c_types << Axlsx::Default.new(:ContentType => ct, :Extension => ext )
  end
  c_types
end


    		
  





    
      

  

  
    - (Array) parts 
  

  


  

    

The parts of a package




  





  

Returns:


    
  
    
  • 
      
      
        (Array)
      
      
      
        —
        
    
An array of hashes that define the entry, document and schema for each part
of the package.

    

    
      
    
    • 
  





  

    
      


101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

    		
    
      
# File 'lib/axlsx/package.rb', line 101

def parts
  @parts = [
   {:entry => RELS_PN, :doc => relationships.to_xml, :schema => RELS_XSD},
   {:entry => CORE_PN, :doc => @core.to_xml, :schema => CORE_XSD},
   {:entry => APP_PN, :doc => @app.to_xml, :schema => APP_XSD},
   {:entry => WORKBOOK_RELS_PN, :doc => workbook.relationships.to_xml, :schema => RELS_XSD},
   {:entry => WORKBOOK_PN, :doc => workbook.to_xml, :schema => SML_XSD},
   {:entry => CONTENT_TYPES_PN, :doc => content_types.to_xml, :schema => CONTENT_TYPES_XSD},
   {:entry => "xl/#{STYLES_PN}", :doc => workbook.styles.to_xml, :schema => SML_XSD}
  ]
  workbook.drawings.each do |drawing|
    @parts << {:entry => "xl/#{drawing.rels_pn}", :doc => drawing.relationships.to_xml, :schema => RELS_XSD}
    @parts << {:entry => "xl/#{drawing.pn}", :doc => drawing.to_xml, :schema => DRAWING_XSD}
  end
    
  workbook.charts.each do |chart|          
    @parts << {:entry => "xl/#{chart.pn}", :doc => chart.to_xml, :schema => DRAWING_XSD}
  end                  

  workbook.images.each do |image|
    @parts << {:entry => "xl/#{image.pn}", :path => image.image_src}
  end

  workbook.worksheets.each do |sheet|            
    @parts << {:entry => "xl/#{sheet.rels_pn}", :doc => sheet.relationships.to_xml, :schema => RELS_XSD}
    @parts << {:entry => "xl/#{sheet.pn}", :doc => sheet.to_xml, :schema => SML_XSD}        
  end
  @parts
end


    		
  





    
      

  

  
    - (Relationships) relationships 
  

  


  

    

Creates the relationships required for a valid xlsx document




  





  

Returns:





  

    
      


197
198
199
200
201
202
203
204

    		
    
      
# File 'lib/axlsx/package.rb', line 197

def relationships
  rels = Axlsx::Relationships.new
  rels << Relationship.new(WORKBOOK_R, WORKBOOK_PN)
  rels << Relationship.new(CORE_R, CORE_PN)
  rels << Relationship.new(APP_R, APP_PN)
  rels.lock
  rels
end


    		
  





    
      

  

  
    - (Boolean) serialize(output, confirm_valid = false) 
  

  


  

    
  

    Note: 
    

A tremendous amount of effort has gone into ensuring that you cannot create
invalid xlsx documents. confirm_valid should be used in the rare case that
you cannot open the serialized file.




  




Serialize your workbook to disk as an xlsx document.




  





  
  

    
Examples:

    
      

      
# This is how easy it is to create a valid xlsx file. Of course you might want to add a sheet or two, and maybe some data, styles and charts.
# Take a look at the README for an example of how to do it!
f = File.open('test.xlsx', 'w')
Package.new.serialize(f)

# You will find a file called test.xlsx


    
  


Parameters:


    
  
    
  • 
      
        output
      
      
        (File)
      
      
      
        —
        
    
The file you want to serialize your package to

    

    
      
    
    • 
  
    
  • 
      
        confirm_valid
      
      
        (Boolean)
      
      
        (defaults to: false)
      
      
        —
        
    
Validate the package prior to serialization.

    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    
False if confirm_valid and validation errors exist. True if the package was
serialized

    

    
      
    
    • 
  



  
See Also:

  



  

    
      


55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

    		
    
      
# File 'lib/axlsx/package.rb', line 55

def serialize(output, confirm_valid=false)
  return false unless !confirm_valid || self.validate.empty?
  p = parts
  Zip::ZipOutputStream.open(output) do |zip|
    p.each do |part| 
      zip.put_next_entry(part[:entry]); zip.puts(part[:doc]) unless part[:doc].nil?
    end
  end
  Zip::ZipFile.open(output) do |zip|
    p.each do |part|
      if part[:path]
        zip.add(part[:entry], part[:path], &proc{ true })
      end
    end                  
  end


  true
end


    		
  





    
      

  

  
    - (Array) validate 
  

  


  

    
  

    Note: 
    

This gem includes all schema from OfficeOpenXML-XMLSchema-Transitional.zip
and OpenPackagingConventions-XMLSchema.zip as per ECMA-376, Third edition.
opc schema require an internet connection to import remote schema from
dublin core for dc, dcterms and xml namespaces. Those remote schema are
included in this gem, and the original files have been altered to refer to
the local versions.




If by chance you are able to creat a package that does not validate it
indicates that the internal validation is not robust enough and needs to be
improved. Please report your errors to the gem author.




  




Validate all parts of the package against xsd schema.




  





  
  

    
Examples:

    
      

      
# The following will output any error messages found in serialization.
p = Axlsx::Package.new
# ... code to create sheets, charts, styles etc.
p.validate.each { |error| puts error.message }


    
  



Returns:


    
  
    
  • 
      
      
        (Array)
      
      
      
        —
        
    
An array of all validation errors found.

    

    
      
    
    • 
  



  
See Also:

  



  

    
      


90
91
92
93
94

    		
    
      
# File 'lib/axlsx/package.rb', line 90

def validate
  errors = []
  parts.each { |part| errors.concat validate_single_doc(part[:schema], part[:doc]) unless part[:schema].nil? }
  errors
end


    		
  





    
      

  

  
    - (Array) validate_single_doc(schema, doc) 
  

  


  

    

Performs xsd validation for a signle document




  





  
Parameters:


    
  
    
  • 
      
        schema
      
      
        (String)
      
      
      
        —
        
    
path to the xsd schema to be used in validation.

    

    
      
    
    • 
  
    
  • 
      
        doc
      
      
        (String)
      
      
      
        —
        
    
The xml text to be validated

    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array)
      
      
      
        —
        
    
An array of all validation errors encountered.

    

    
      
    
    • 
  





  

    
      


137
138
139
140
141
142
143
144
145
146

    		
    
      
# File 'lib/axlsx/package.rb', line 137

def validate_single_doc(schema, doc)
  schema = Nokogiri::XML::Schema(File.open(schema))
  doc = Nokogiri::XML(doc)

  errors = []
  schema.validate(doc).each do |error|
    errors << error
  end
  errors
end