Module: Texd

Extended by:
Texd
Included in:
Texd
Defined in:
lib/texd.rb,
lib/texd.rb,
lib/texd/cache.rb,
lib/texd/client.rb,
lib/texd/config.rb,
lib/texd/helpers.rb,
lib/texd/railtie.rb,
lib/texd/version.rb,
lib/texd/document.rb,
lib/texd/attachment.rb,
lib/texd/lookup_context.rb

Defined Under Namespace

Modules: Attachment, Helpers Classes: AttachmentList, Cache, Client, Configuration, Document, Error, LookupContext, Railtie

Constant Summary collapse

VERSION = 
"0.6.0"

Instance Method Summary collapse

Instance Method Details

#client ⇒ Texd::Client

Returns the currently configured HTTP client.

Returns:



50
51
52
53
54
55
56
57
 
# File 'lib/texd.rb', line 50

def client
  if (new_hash = config.hash) && new_hash != @config_hash
    @client      = Client.new(config)
    @config_hash = new_hash
  end

  @client
end

#config ⇒ Texd::Configuration

Returns the current config object.

Returns:



45
46
47
 
# File 'lib/texd.rb', line 45

def config
  @config ||= Configuration.new
end

#configure {|Texd::Configuration| ... } ⇒ Texd::Configuration

Reconfigures Texd. Should be called once in your initializer.

Examples:

config/initializers/texd.rb

Texd.configure do |config|
  config.endpoint     = ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/")
  config.error_format = ENV.fetch("TEXD_ERRORS", "full")
  config.tex_engine   = ENV["TEXD_ENGINE"]
  config.tex_image    = ENV["TEXD_IMAGE"]
  config.helpers      = []
  config.lookup_paths = [Rails.root.join("app/tex")]
end

Yields:

Returns:



39
40
41
42
 
# File 'lib/texd.rb', line 39

def configure
  yield config if block_given?
  config
end

#helpers(attachments, locals) ⇒ Module

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a helper module containing:

  1. the ‘texd_attach` and `texd_reference` helper,

  2. locals passed in, transformed to helper methods, and

  3. any other helper configured in Text.config.helpers.

Parameters:

Returns:

  • (Module) —

    a new helper module



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/texd.rb', line 69

def helpers(attachments, locals) # rubocop:disable Metrics/AbcSize
  locals ||= {}

  Module.new do
    include Texd::Helpers

    Texd.config.helpers.each do |mod|
      include mod
    end

    define_method :texd_attach do |path, rename: true, with_extension: true|
      attachments.attach(path, rename).name(with_extension)
    end

    define_method :texd_inline do |data, name, with_extension: true|
      attachments.inline(data, name).name(with_extension)
    end

    define_method :texd_reference do |path, rename: true, with_extension: true|
      attachments.reference(path, rename).name(with_extension)
    end

    alias_method :texd_references, :texd_reference

    locals.each do |name, value|
      define_method(name) { value }
    end
  end
end

#render(template:, locals: {}, layout: true) ⇒ String

Render compiles a template, uploads the files to the texd instance, and returns the PDF.

The arguments are directly forwarded to Texd::Document (and end up in ActionView::Renderer#render).

Examples:

Render app/views/document/document.tex.erb

begin
  pdf = Texd.render(template: "documents/document")
rescue Texd::Client::CompilationError => err
  # Compilation failed and we might have a log in err.logs (only
  # Texd.config.error_format is "full" or "condensed").
  # Otherwise some details might be available in err.details.
rescue Texd::Client::InputError => err
  # something failed during input file processing. For details see
  # err.details
rescue Texd::Client::QueueError => err
  # server is busy, try again later.
rescue Texd::Error => err
  # something went wrong before we even got to sent data to the server
end

Parameters:

  • template (String) —

    name of template file in ActionView’s lookup context.

  • locals (Hash, nil) (defaults to: {}) —

    will be made available as getter methods in the template.

  • layout (String, Boolean) (defaults to: true) —

    to be used. String value name template files in ‘app/views/layouts`, `true` (default) uses the application layout, and `false` renders without a layout.

Returns:

  • (String) —

    the PDF object

Raises:

  • (Texd::Client::ResponseError) —

    on input and queue errors. Also on compilation errors, if Texd.config.error_format is set to JSON.

  • (Texd::Error) —

    on other Texd related errors.



132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/texd.rb', line 132

def render(template:, locals: {}, layout: true)
  doc = Document.compile(template: template, locals: locals, layout: layout)

  client.render doc.to_upload_ios,
    input: doc.main_input_name
rescue Client::ReferenceError => err
  # retry once with resolved references
  client.render doc.to_upload_ios(missing_refs: err.references),
    input: doc.main_input_name
rescue Client::CompilationError => err
  config.error_handler.call(err, doc)
  nil
end