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/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/formula_translator.rb,
lib/liquid_xlsx/merge_cells_transformer.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 Classes: CellReference, DrawingBuilder, Error, FormulaTranslator, Image, InvalidXlsxError, MergeCellsTransformer, MissingVariableError, OutputWriteError, Package, RenderError, RenderState, Renderer, SharedStrings, Template, TemplateParser, TemplateSyntaxError, UnsupportedTemplateError, Workbook, Worksheet

Constant Summary collapse

VERSION = 
"0.2.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.



32
33
34
35
36
37
 
# File 'lib/liquid_xlsx.rb', line 32

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.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/liquid_xlsx.rb', line 71

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