Module: LiquidXlsx

Defined in:
lib/liquid_xlsx.rb,
lib/liquid_xlsx/image.rb,
lib/liquid_xlsx/errors.rb,
lib/liquid_xlsx/filters.rb,
lib/liquid_xlsx/package.rb,
lib/liquid_xlsx/version.rb,
lib/liquid_xlsx/renderer.rb,
lib/liquid_xlsx/template.rb,
lib/liquid_xlsx/workbook.rb,
lib/liquid_xlsx/validator.rb,
lib/liquid_xlsx/worksheet.rb,
lib/liquid_xlsx/cell_reference.rb,
lib/liquid_xlsx/shared_strings.rb,
lib/liquid_xlsx/tags/image_tag.rb,
lib/liquid_xlsx/tags/sheet_tag.rb,
lib/liquid_xlsx/template_nodes.rb,
lib/liquid_xlsx/drawing_builder.rb,
lib/liquid_xlsx/template_parser.rb,
lib/liquid_xlsx/validation/issue.rb,
lib/liquid_xlsx/validation/usage.rb,
lib/liquid_xlsx/validation/result.rb,
lib/liquid_xlsx/formula_translator.rb,
lib/liquid_xlsx/merge_cells_transformer.rb,
lib/liquid_xlsx/validation/liquid_usage.rb,
lib/liquid_xlsx/validation/block_boundary.rb

Overview

LiquidXlsx is a Ruby gem for generating .xlsx files from Excel templates with Liquid syntax. Edit templates in Excel, write Liquid in cells, and render the final file preserving styles, formulas, and merged cells.

Defined Under Namespace

Modules: Filters, Nodes, Tags, Validation Classes: CellReference, DrawingBuilder, Error, FormulaTranslator, Image, InvalidXlsxError, MergeCellsTransformer, MissingVariableError, OutputWriteError, Package, RenderError, RenderState, Renderer, SharedStrings, Template, TemplateParser, TemplateSyntaxError, UnsupportedTemplateError, Validator, Workbook, Worksheet

Constant Summary collapse

VERSION = 
"0.3.0"

Class Method Summary collapse

Class Method Details

.liquid_environment ⇒ Object

Dedicated Liquid environment with the gem's custom tags. Using a scoped environment (instead of registering tags on Liquid::Environment.default) keeps the host application's Liquid configuration untouched.



38
39
40
41
42
43
 
# File 'lib/liquid_xlsx.rb', line 38

def liquid_environment
  @liquid_environment ||= Liquid::Environment.build do |env|
    env.register_tag("sheet", Tags::SheetTag)
    env.register_tag("image_tag", Tags::ImageTag)
  end
end

.render(template:, output:, data:, strict_variables: false, strict_filters: false, recalculate_formulas: false, remove_template_comments: false, dynamic_sheets: false, hide_control_sheets: true, hide_template_sheets: false, images: nil, liquid_resource_limits: nil, filters: nil) ⇒ Object

High-level API: render a template with data and save to output.

rubocop:disable Metrics/ParameterLists

Examples:

LiquidXlsx.render(
  template: "invoice_template.xlsx",
  output: "invoice.xlsx",
  data: {
    invoice: { number: "INV-001", paid: true },
    customer: { name: "ООО Ромашка" },
    items: [
      { title: "Разработка", qty: 10, price: 100 },
      { title: "Поддержка", qty: 5, price: 50 }
    ]
  }
)

Parameters:

  • template (String) —

    path to .xlsx template file

  • output (String) —

    path to output .xlsx file

  • data (Hash, Liquid::Drop, #to_liquid) —

    data to render. A Hash, a Liquid::Drop, or any object whose #to_liquid returns a Hash/Drop.

  • strict_variables (Boolean) (defaults to: false) —

    raise error on missing variables

  • strict_filters (Boolean) (defaults to: false) —

    raise error on unknown filters

  • dynamic_sheets (Boolean) (defaults to: false) —

    enable sheet % tag for dynamic sheet creation

  • hide_control_sheets (Boolean) (defaults to: true) —

    hide sheets that contained sheet % tags

  • hide_template_sheets (Boolean) (defaults to: false) —

    hide template sheets after cloning

  • images (Hash) (defaults to: nil) —

    image rendering options: { loader:, default_dpi: }

  • liquid_resource_limits (Hash, nil) (defaults to: nil) —

    optional Liquid resource limits: { render_length_limit:, render_score_limit:, assign_score_limit: }

  • filters (Module, Array<Module>, nil) (defaults to: nil) —

    extra Liquid filter modules made available to every cell of the workbook. Added to the render context only, so nothing is registered globally on Liquid::Environment.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/liquid_xlsx.rb', line 77

def render(template:, output:, data:,
           strict_variables: false, strict_filters: false,
           recalculate_formulas: false, remove_template_comments: false,
           dynamic_sheets: false, hide_control_sheets: true,
           hide_template_sheets: false, images: nil,
           liquid_resource_limits: nil, filters: nil)
  tpl = Template.new(template, {
                       strict_variables: strict_variables,
                       strict_filters: strict_filters,
                       recalculate_formulas: recalculate_formulas,
                       remove_template_comments: remove_template_comments,
                       dynamic_sheets: dynamic_sheets,
                       hide_control_sheets: hide_control_sheets,
                       hide_template_sheets: hide_template_sheets,
                       images: images || {},
                       liquid_resource_limits: liquid_resource_limits,
                       filters: filters
                     })
  # rubocop:enable Metrics/ParameterLists
  tpl.render_to_file(data, output)
end

.standard_filters ⇒ Object

Filters every Liquid template can use without the host registering anything.



128
129
130
 
# File 'lib/liquid_xlsx.rb', line 128

def standard_filters
  @standard_filters ||= ::Liquid::StandardFilters.public_instance_methods(false).map(&:to_s)
end

.validate(template:, dynamic_sheets: false, known_filters: nil) ⇒ Validation::Result

Check a template without rendering it and without any data.

Unlike a trial render, this parses every cell and every branch — including the ones a particular document would not take — collects all problems instead of stopping at the first, and executes nothing, so validating a template has no side effects on the application's records.

result = LiquidXlsx.validate(template: "invoice.xlsx",
                           known_filters: MyFilters.public_instance_methods(false))
result.valid?   # => false
result.issues   # => [#<Issue code: :liquid_syntax, sheet: "Sheet1", cell: "B12", ...>]
result.roots    # => ["invoice", "customer"]  — what the template expects as input

Parameters:

  • template (String) —

    path to the .xlsx template

  • dynamic_sheets (Boolean) (defaults to: false) —

    pass true if you render with dynamic_sheets: true; otherwise sheet % in the template is reported as an error, because that is what rendering it would do

  • known_filters (Array<String, Symbol>, nil) (defaults to: nil) —

    filter names available at render time (standard Liquid filters are included automatically); nil disables the unknown-filter check

Returns:



120
121
122
123
124
125
 
# File 'lib/liquid_xlsx.rb', line 120

def validate(template:, dynamic_sheets: false, known_filters: nil)
  Validator.new(template,
                dynamic_sheets: dynamic_sheets,
                known_filters: known_filters && (known_filters.map(&:to_s) + standard_filters))
           .call
end