Biblioteca Ruby de Código Aberto para Gerar Arquivos Word DOCX
Uma Poderosa API Ruby Gratuita que Permite aos Desenvolvedores Criar Documentos Word DOCX com Facilidade. Permite Projetar Documentos's Layout, Apply Styles, and Use Mail Merge Fields as Placeholders for Dynamic Content.
O que é a Biblioteca Sablon?
No mundo do desenvolvimento de software, gerar documentos dinâmicos como relatórios, faturas ou cartas é uma necessidade comum. Embora muitas bibliotecas possam criar documentos do zero, elas frequentemente envolvem uma curva de aprendizado íngreme e codificação tediosa para obter a formatação adequada. É aqui que o Sablon, uma poderosa biblioteca Ruby de código aberto, entra em ação. O Sablon revoluciona a geração de documentos ao aproveitar a familiaridade do Microsoft Word e o poder do Ruby, permitindo que você crie documentos complexos e belamente formatados com esforço mínimo. Ele suporta recursos como criação de Word Docx, inserção de conteúdo via campos MailMerge, suporte avançado de formatação, adição de anotações em templates, conversão configurável de HTML & CSS e muito mais.
Em sua essência, o Sablon é um processador de templates de documento para arquivos .docx. Ele utiliza a funcionalidade incorporada de Mail Merge do Word, permitindo que você crie templates em um ambiente familiar. Você pode projetar o layout do documento, aplicar estilos e usar campos de Mail Merge como marcadores de posição para conteúdo dinâmico. O Sablon então pega esse template e um contexto de dados (um hash Ruby) para produzir um documento Word final, populado com dados. Essa abordagem separa a camada de apresentação (o template Word) da camada de dados (seu código Ruby), tornando o processo de geração de documentos limpo e fácil de manter. Sua sintaxe é intuitiva para quem conhece Ruby e linguagens de template. É amigável ao designer, o conteúdo e o design ficam completamente separados. Os designers podem trabalhar diretamente no Word sem tocar no código.
Começando com Sablon
A forma recomendada de instalar o Sablon é usando RubyGems. Por favor, use o comando a seguir para uma instalação tranquila.
Inserção de Conteúdo com Campos Word via Ruby
A função mais básica é inserir conteúdo dinâmico. A biblioteca Ruby de código aberto Sablon usa a sintaxe de campo incorporada do Word para definir placeholders. No seu template Word, você insere um código de campo onde deseja o conteúdo dinâmico. O Sablon substituirá esse campo pelo seu valor. O exemplo a seguir demonstra como desenvolvedores podem inserir dinamicamente um trecho de conteúdo para cumprimentar um usuário.
Como Inserir Dinamicamente Conteúdo de Texto em Arquivo Word Docs via Ruby?
require 'sablon'
template = Sablon.template(File.expand_path('~/template.docx'))
context = {
name: "Sarah Connor"
}
template.render_to_file(File.expand_path('~/output.docx'), context)
Template:
Hello, «name»! Welcome to our platform.
Output:
Hello, Sarah Connor! Welcome to our platform.
Conversão de HTML para WordML
Uma das principais características do Sablon é sua capacidade de converter HTML em WordProcessingML (o formato XML usado pelos arquivos .docx). Isso é extremamente útil quando você precisa inserir conteúdo de texto rico, como parágrafos formatados, listas ou tabelas, a partir de um banco de dados ou editor de texto rico. O Sablon converterá a string HTML em uma seção devidamente formatada no documento Word, preservando cabeçalhos, texto em negrito e itálico, e a formatação de listas. Aqui está um exemplo simples que demonstra como carregar um template existente e converter o conteúdo HTML em um arquivo Word Docx dentro de aplicações Ruby.
Como Converter Conteúdo HTML em Arquivo Word Docx via Biblioteca Ruby?
require "sablon"
template = Sablon.template(File.expand_path("template.docx"))
html_content = "Este é um Subtítulo
Este é um parágrafo com negrito e itálico.
- Primeiro item
- Segundo item
"
context = {
article_content: Sablon.content(:html, html_content)
}
template.render_to_file(File.expand_path("output.docx"), context)
Conditional Rendering
Inserção Dinâmica de Imagem via Ruby
A biblioteca Sablon de código aberto inclui um recurso útil para inserir dinamicamente imagens em documentos Word Docx usando a biblioteca Ruby. Com apenas algumas linhas de código, os desenvolvedores podem inserir dinamicamente imagens em seus documentos. Você pode especificar um arquivo de imagem, e o Sablon o incorporará no documento. O exemplo a seguir demonstra como alcançar a inserção dinâmica de imagens em documentos Word.
Como Inserir Dinamicamente Imagem em Word Docx via Biblioteca Ruby?
// You would have a placeholder image in your template with a special filename like «=company_logo».
context = {
company_logo: Sablon.content(:image, "path/to/your/logo.png")
}
Renderização Condicional via Ruby
A biblioteca Sablon suporta blocos condicionais, permitindo que os usuários exibam ou ocultem partes de seu documento Word com base na presença ou valor de uma variável. Isso é perfeito para personalizar documentos conforme condições específicas. Por exemplo, o exemplo a seguir mostra como os usuários podem definir comandos para ocultar ou mostrar informações específicas dentro de um documento Word. Se show_extra_info for verdadeiro, o conteúdo entre as tags if e endIf será incluído no documento final. Se for falso ou nil, o conteúdo será removido.
Como Exibir ou Ocultar Partes de Documentos Word Docx usando Ruby?
context = {
show_extra_info: true # or false
}
