Class: Axlsx::Worksheet

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

Overview

The Worksheet class represents a worksheet in the workbook.

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Worksheet) initialize(wb, options = {})

Note:

the recommended way to manage worksheets is Workbook#add_worksheet

Creates a new worksheet.

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • name (String) —

    The name of this worksheet.

  • page_margins (Hash) —

    A hash containing page margins for this worksheet. @see PageMargins

  • print_options (Hash) —

    A hash containing print options for this worksheet. @see PrintOptions

  • show_gridlines (Boolean) —

    indicates if gridlines should be shown for this sheet.

See Also:



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 145

def initialize(wb, options={})
  self.workbook = wb
  @workbook.worksheets << self
  @page_marging = @page_setup = @print_options = nil
  @drawing = @page_margins = @auto_filter = nil
  @merged_cells = []
  @auto_fit_data = []
  @conditional_formattings = []
  @comments = Comments.new(self)
  @selected = false
  @show_gridlines = true
  self.name = "Sheet" + (index+1).to_s
  @page_margins = PageMargins.new options[:page_margins] if options[:page_margins]
  @page_setup = PageSetup.new options[:page_setup] if options[:page_setup]
  @print_options = PrintOptions.new options[:print_options] if options[:print_options]
  @rows = SimpleTypedList.new Row
  @column_info = SimpleTypedList.new Col
  # @cols = SimpleTypedList.new Cell
  @tables = SimpleTypedList.new Table

  options.each do |o|
    self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
  end
end

Instance Attribute Details

- (Object) auto_filter

An range that excel will apply an autfilter to "A1:B3" This will turn filtering on for the cells in the range. The first row is considered the header, while subsequent rows are considerd to be data.

Returns:

  • Array



41
42
43
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 41

def auto_filter
  @auto_filter
end

- (Array) auto_fit_data (readonly)

Note:

a single auto fit data item is a hash with :longest => [String] and :sz=> [Integer] members.

An array of content based calculated column widths.

Returns:

  • (Array) —

    of Hash



30
31
32
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 30

def auto_fit_data
  @auto_fit_data
end

- (SimpleTypedList) column_info (readonly)

Column info for the sheet

Returns:



61
62
63
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 61

def column_info
  @column_info
end

- (Object) comments (readonly)

Returns the value of attribute comments



19
20
21
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 19

def comments
  @comments
end

- (Object) fit_to_page

Indicates if the worksheet should print in a single page

Returns:

  • Boolean



56
57
58
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 56

def fit_to_page
  @fit_to_page
end

- (Object) merged_cells (readonly)

An array of merged cell ranges e.d "A1:B3" Content and formatting is read from the first cell.

Returns:

  • Array



35
36
37
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 35

def merged_cells
  @merged_cells
end

- (String) name

The name of the worksheet

Returns:

  • (String) 


9
10
11
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 9

def name
  @name
end

- (SimpleTypedList) rows (readonly)

Note:

The recommended way to manage rows is Worksheet#add_row

The rows in this worksheet

Returns:

See Also:



25
26
27
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 25

def rows
  @rows
end

- (Object) selected

Indicates if the worksheet is selected in the workbook It is possible to have more than one worksheet selected, however it might cause issues in some older versions of excel when using copy and paste.

Returns:

  • Boolean



52
53
54
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 52

def selected
  @selected
end

- (Object) show_gridlines

Indicates if the worksheet should show gridlines or not

Returns:

  • Boolean



45
46
47
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 45

def show_gridlines
  @show_gridlines
end

- (Array) tables (readonly)

The tables in this worksheet

Returns:

  • (Array) —

    of Table



17
18
19
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 17

def tables
  @tables
end

- (Workbook) workbook

The workbook that owns this worksheet

Returns:



13
14
15
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 13

def workbook
  @workbook
end

Class Method Details

+ (String) thin_chars

definition of characters which are less than the maximum width of 0-9 in the default font for use in String#count. This is used for autowidth calculations

Returns:

  • (String) 


134
135
136
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 134

def self.thin_chars
  @thin_chars ||= "^.acefijklrstxyzFIJL()-"
end

Instance Method Details

- (Cell, Array) [](cell_def)

Returns the cell or cells defined using excel style A1:B3 references.

Parameters:

  • cell_def (String|Integer) —

    the string defining the cell or range of cells, or the rownumber

Returns:



514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 514

def [] (cell_def)
  return rows[cell_def] if cell_def.is_a?(Integer)

  parts = cell_def.split(':')
  first = name_to_cell parts[0]
  if parts.size == 1
    first
  else
    cells = []
    last = name_to_cell(parts[1])
    rows[(first.row.index..last.row.index)].each do |r|
      r.cells[(first.index..last.index)].each do |c|
        cells << c
      end
    end
    cells
  end
end

- (Object) abs_auto_filter

The absolute auto filter range

See Also:

  • auto_filter


267
268
269
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 267

def abs_auto_filter
  Axlsx.cell_range(@auto_filter.split(':').collect { |name| name_to_cell(name)}) if @auto_filter
end

- (Object) add_chart(chart_type, options = {}) {|chart| ... }

Note:

each chart type also specifies additional options

Adds a chart to this worksheets drawing. This is the recommended way to create charts for your worksheet. This method wraps the complexity of dealing with ooxml drawing, anchors, markers graphic frames chart objects and all the other dirty details.

Parameters:

  • chart_type (Class)
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • start_at (Array)
  • end_at (Array)
  • title (Cell, String)
  • show_legend (Boolean)
  • style (Integer)

Yields:

  • (chart)

See Also:



432
433
434
435
436
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 432

def add_chart(chart_type, options={})
  chart = drawing.add_chart(chart_type, options)
  yield chart if block_given?
  chart
end

- (Object) add_comment(options = {})

Shortcut to comments#add_comment



448
449
450
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 448

def add_comment(options={})
  @comments.add_comment(options)
end

- (Object) add_conditional_formatting(cells, rules)

Add conditional formatting to this worksheet.

Examples:

This would format column A whenever it is FALSE.

# for a longer example, see examples/example_conditional_formatting.rb (link below)
worksheet.add_conditional_formatting( "A1:A1048576", { :type => :cellIs, :operator => :equal, :formula => "FALSE", :dxfId => 1, :priority => 1 }

Parameters:

  • cells (String) —

    The range to apply the formatting to

  • rules (Array|Hash) —

    An array of hashes (or just one) to create Conditional formatting rules from.

See Also:



186
187
188
189
190
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 186

def add_conditional_formatting(cells, rules)
  cf = ConditionalFormatting.new( :sqref => cells )
  cf.add_rules rules
  @conditional_formattings << cf
end

- (Object) add_image(options = {}) {|image| ... }

Adds a media item to the worksheets drawing

Parameters:

  • media_type (Class)
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • [] (Object) —

    unknown

Yields:

  • (image) 


455
456
457
458
459
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 455

def add_image(options={})
  image = drawing.add_image(options)
  yield image if block_given?
  image
end

- (Row) add_row(values = [], options = {}) {|@rows.last| ... } Also known as: <<

Adds a row to the worksheet and updates auto fit data.

Examples:

  • put a vanilla row in your spreadsheet

ws.add_row [1, 'fish on my pl', '8']

  • specify a fixed width for a column in your spreadsheet

# The first column will ignore the content of this cell when calculating column autowidth.
# The second column will include this text in calculating the columns autowidth
# The third cell will set a fixed with of 80 for the column.
# If you need to un-fix a column width, use :auto. That will recalculate the column width based on all content in the column

ws.add_row ['I wish', 'for a fish', 'on my fish wish dish'], :widths=>[:ignore, :auto, 80]

  • specify a fixed height for a row

ws.add_row ['I wish', 'for a fish', 'on my fish wish dish'], :height => 40

  • create and use a style for all cells in the row

blue = ws.styles.add_style :color => "#00FF00"
ws.add_row [1, 2, 3], :style=>blue

  • only style some cells

blue = ws.styles.add_style :color => "#00FF00"
red = ws.styles.add_style :color => "#FF0000"
big = ws.styles.add_style :sz => 40
ws.add_row ["red fish", "blue fish", "one fish", "two fish"], :style=>[red, blue, nil, big] # the last nil is optional

  • force the second cell to be a float value

ws.add_row [3, 4, 5], :types => [nil, :float]

  • use << alias

ws << [3, 4, 5], :types => [nil, :float]

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • values (Array)
  • types (Array, Symbol)
  • style (Array, Integer)
  • widths (Array) —

    each member of the widths array will affect how auto_fit behavies.

  • height (Float) —

    the row's height (in points)

Yields:

  • (@rows.last)

Returns:

See Also:



350
351
352
353
354
355
356
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 350

def add_row(values=[], options={})
  Row.new(self, values, options)
  update_column_info @rows.last.cells, options.delete(:widths) ||[], options.delete(:style) || []
  # update_auto_fit_data @rows.last.cells, options.delete(:widths) || []
  yield @rows.last if block_given?
  @rows.last
end

- (Object) add_table(ref, options = {}) {|table| ... }

needs documentation

Yields:

  • (table) 


439
440
441
442
443
444
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 439

def add_table(ref, options={})
  table = Table.new(ref, self, options)
  @tables << table
  yield table if block_given?
  table
end

- (Array) cells

convinience method to access all cells in this worksheet

Returns:

  • (Array) —

    cells



172
173
174
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 172

def cells
  rows.flatten
end

- (Object) col_style(index, style, options = {})

Note:

You can also specify the style for specific columns in the call to add_row by using an array for the :styles option

Set the style for cells in a specific column

Parameters:

  • index (Integer) —

    the index of the column

  • the (Integer) —

    cellXfs index

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • row_offset (Integer) —

    only cells after this column will be updated.

See Also:



390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 390

def col_style(index, style, options={})
  offset = options.delete(:row_offset) || 0
  @rows[(offset..-1)].each do |r|
    cells = r.cells[index]
    next unless cells
    if cells.is_a?(Array)
      cells.each { |c| c.style = style }
    else
      cells.style = style
    end
  end
end

- (Object) cols

returns the sheet data as columnw



378
379
380
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 378

def cols
  @rows.transpose
end

- (Object) column_widths(*args)

Note:

For updating only a single column it is probably easier to just set the width of the ws.column_info.width directly

This is a helper method that Lets you specify a fixed width for multiple columns in a worksheet in one go. Axlsx is sparse, so if you have not set data for a column, you cannot set the width. Setting a fixed column width to nil will revert the behaviour back to calculating the width for you.

Examples:

This would set the first and third column widhts but leave the second column in autofit state.

ws.column_widths 7.2, nil, 3

Parameters:

  • values (Integer|Float|Fixnum|nil) 


410
411
412
413
414
415
416
417
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 410

def column_widths(*args)
  args.each_with_index do |value, index|
    next if value == nil
    Axlsx::validate_unsigned_numeric(value) unless value == nil
    @column_info[index] ||= Col.new index+1, index+1
    @column_info[index].width = value
  end
end

- (String) dimension

The demensions of a worksheet. This is not actually a required element by the spec, but at least a few other document readers expect this for conversion

Returns:

  • (String) —

    the A1:B2 style reference for the first and last row column intersection in the workbook



214
215
216
217
218
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 214

def dimension
  dim_start = rows.first.cells.first == nil ? 'A1' : rows.first.cells.first.r
  dim_end = rows.last.cells.last == nil ? 'AA:200' : rows.last.cells.last.r
  "#{dim_start}:#{dim_end}"
end

- (Drawing) drawing

Note:

the recommended way to work with drawings and charts is Worksheet#add_chart

The drawing associated with this worksheet.

Returns:

See Also:



307
308
309
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 307

def drawing
  @drawing || @drawing = Axlsx::Drawing.new(self)
end

- (Integer) index

The index of this worksheet in the owning Workbook's worksheets list.

Returns:

  • (Integer) 


299
300
301
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 299

def index
  @workbook.worksheets.index(self)
end

- (Object) merge_cells(cells)

Creates merge information for this worksheet. Cells can be merged by calling the merge_cells method on a worksheet.

Examples:

This would merge the three cells C1..E1 #

worksheet.merge_cells "C1:E1"
# you can also provide an array of cells to be merged
worksheet.merge_cells worksheet.rows.first.cells[(2..4)]
#alternatively you can do it from a single cell
worksheet["C1"].merge worksheet["E1"]

Parameters:

  • (Array, string) 


201
202
203
204
205
206
207
208
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 201

def merge_cells(cells)
  @merged_cells << if cells.is_a?(String)
                     cells
                   elsif cells.is_a?(Array)
                     cells = cells.sort { |x, y| x.r <=> y.r }
                     "#{cells.first.r}:#{cells.last.r}"
                   end
end

- (Cell) name_to_cell(name)

returns the column and row index for a named based cell

Parameters:

  • name (String) —

    The cell or cell range to return. “A1” will return the first cell of the first row.

Returns:



248
249
250
251
252
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 248

def name_to_cell(name)
  col_index, row_index = *Axlsx::name_to_indices(name)
  r = rows[row_index]
  r.cells[col_index] if r
end

- (PageMargins) page_margins {|@page_margins| ... }

Page margins for printing the worksheet.

Examples:

wb = Axlsx::Package.new.workbook
# using options when creating the worksheet.
ws = wb.add_worksheet :page_margins => {:left => 1.9, :header => 0.1}

# use the set method of the page_margins object
ws.page_margins.set(:bottom => 3, :footer => 0.7)

# set page margins in a block
ws.page_margins do |margins|
  margins.right = 6
  margins.top = 0.2
end

Yields:

  • (@page_margins)

Returns:

See Also:



79
80
81
82
83
84
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 79

def page_margins
  @page_margins ||= PageMargins.new
  yield @page_margins if block_given?
  @page_margins

end

- (PageSetup) page_setup {|@page_setup| ... }

Page setup settings for printing the worksheet.

Examples:

wb = Axlsx::Package.new.workbook

# using options when creating the worksheet.
ws = wb.add_worksheet :page_setup => {:fit_to_width => 1, :orientation => :landscape}

# use the set method of the page_setup object
ws.page_setup.set(:paper_width => "297mm", :paper_height => "210mm")

# setup page in a block
ws.page_setup do |page|
  page.scale = 80
  page.orientation = :portrait
end

Yields:

  • (@page_setup)

Returns:

See Also:



103
104
105
106
107
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 103

def page_setup
  @page_setup ||= PageSetup.new
  yield @page_setup if block_given?
  @page_setup
end

- (String) pn

The part name of this worksheet

Returns:

  • (String) 


281
282
283
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 281

def pn
  "#{WORKSHEET_PN % (index+1)}"
end

- (PrintOptions) print_options {|@print_options| ... }

Options for printing the worksheet.

Examples:

wb = Axlsx::Package.new.workbook
# using options when creating the worksheet.
ws = wb.add_worksheet :print_options => {:gridLines => true, :horizontalCentered => true}

# use the set method of the page_margins object
ws.print_options.set(:headings => true)

# set page margins in a block
ws.print_options do |options|
  options.horizontalCentered = true
  options.verticalCentered = true
end

Yields:

  • (@print_options)

Returns:

See Also:



125
126
127
128
129
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 125

def print_options
  @print_options ||= PrintOptions.new
  yield @print_options if block_given?
  @print_options
end

- (Relationships) relationships

The worksheet relationships. This is managed automatically by the worksheet

Returns:



497
498
499
500
501
502
503
504
505
506
507
508
509
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 497

def relationships
  r = Relationships.new
  @tables.each do |table|
    r << Relationship.new(TABLE_R, "../#{table.pn}")
  end

  r << Relationship.new(VML_DRAWING_R, "../#{@comments.vml_drawing.pn}") if @comments.size > 0
  r << Relationship.new(COMMENT_R, "../#{@comments.pn}") if @comments.size > 0
  r << Relationship.new(COMMENT_R_NULL, "NULL") if @comments.size > 0

  r << Relationship.new(DRAWING_R, "../#{@drawing.pn}") if @drawing
  r
end

- (String) rels_pn

The relationship part name of this worksheet

Returns:

  • (String) 


287
288
289
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 287

def rels_pn
  "#{WORKSHEET_RELS_PN % (index+1)}"
end

- (String) rId

The relationship Id of thiw worksheet

Returns:

  • (String) 


293
294
295
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 293

def rId
  "rId#{index+1}"
end

- (Object) row_style(index, style, options = {})

Note:

You can also specify the style in the add_row call

Set the style for cells in a specific row

Parameters:

  • index (Integer) —

    or range of indexes in the table

  • the (Integer) —

    cellXfs index

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • col_offset (Integer) —

    only cells after this column will be updated.

See Also:



367
368
369
370
371
372
373
374
375
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 367

def row_style(index, style, options={})
  offset = options.delete(:col_offset) || 0
  rs = @rows[index]
  if rs.is_a?(Array)
    rs.each { |r| r.cells[(offset..-1)].each { |c| c.style = style } }
  else
    rs.cells[(offset..-1)].each { |c| c.style = style }
  end
end

- (String) to_xml_string

Serializes the object

Parameters:

  • str (String)

Returns:

  • (String) 


464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
 
# File 'lib/axlsx/workbook/worksheet/worksheet.rb', line 464

def to_xml_string
  str = '<?xml version="1.0" encoding="UTF-8"?>'
  str.concat "<worksheet xmlns=\"%s\" xmlns:r=\"%s\">" % [XML_NS, XML_NS_R]
  str.concat "<sheetPr><pageSetUpPr fitToPage=\"%s\"></pageSetUpPr></sheetPr>" % fit_to_page if fit_to_page
  str.concat "<dimension ref=\"%s\"></dimension>" % dimension unless rows.size == 0
  str.concat "<sheetViews><sheetView tabSelected='%s' workbookViewId='0' showGridLines='%s'><selection activeCell=\"A1\" sqref=\"A1\"/></sheetView></sheetViews>" % [@selected, show_gridlines]

  if @column_info.size > 0
    str << "<cols>"
    @column_info.each { |col| col.to_xml_string(str) }
    str.concat '</cols>'
  end
  str.concat '<sheetData>'
  @rows.each_with_index { |row, index| row.to_xml_string(index, str) }
  str.concat '</sheetData>'
  str.concat "<autoFilter ref='%s'></autoFilter>" % @auto_filter if @auto_filter
  str.concat "<mergeCells count='%s'>%s</mergeCells>" % [@merged_cells.size, @merged_cells.reduce('') { |memo, obj| memo += "<mergeCell ref='%s'></mergeCell>" % obj } ] unless @merged_cells.empty?
  print_options.to_xml_string(str) if @print_options
  page_margins.to_xml_string(str) if @page_margins
  page_setup.to_xml_string(str) if @page_setup
  str.concat "<drawing r:id='rId1'></drawing>" if @drawing
  unless @tables.empty?
    str.concat "<tableParts count='%s'>%s</tableParts>" % [@tables.size, @tables.reduce('') { |memo, obj| memo += "<tablePart r:id='%s'/>" % obj.rId }]
  end
  @conditional_formattings.each do |cf|
    str.concat cf.to_xml_string
  end
  str << '<legacyDrawing r:id="rId1"/>' if @comments.size > 0
  str + '</worksheet>'
end