Class: SelectPdf::PdfMergeClient

Inherits:
ApiClient show all
Defined in:
lib/selectpdf.rb

Overview

Pdf Merge with SelectPdf Online API.

Code sample:

require 'selectpdf'

$stdout.sync = true

print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"

test_url = 'https://selectpdf.com/demo/files/selectpdf.pdf'
test_pdf = 'Input.pdf'
local_file = 'Result.pdf'
api_key = 'Your API key here'

begin
  client = SelectPdf::PdfMergeClient.new(api_key)

  # set parameters - see full list at https://selectpdf.com/pdf-merge-api/

  # specify the pdf files that will be merged (order will be preserved in the final pdf)
  client.add_file(test_pdf) # add PDF from local file
  client.add_url_file(test_url) # add PDF from public url
  # client.add_file(test_pdf, 'pdf_password') # add PDF (that requires a password) from local file
  # client.add_url_file(test_url, 'pdf_password') # add PDF (that requires a password) from public url

  print "Starting pdf merge ...\n"

  # merge pdfs to local file
  client.save_to_file(local_file)

  # merge pdfs to memory
  # pdf = client.save

  print "Finished! Number of pages: #{client.number_of_pages}.\n"

  # get API usage
  usage_client = SelectPdf::UsageClient.new(api_key)
  usage = usage_client.get_usage(FALSE)
  print("Usage: #{usage}\n")
  print('Conversions remained this month: ', usage['available'], "\n")
rescue SelectPdf::ApiException => e
  print("An error occurred: #{e}")
end

Instance Attribute Summary

Attributes inherited from ApiClient

#api_async_endpoint, #api_endpoint, #api_web_elements_endpoint, #async_calls_max_pings, #async_calls_ping_interval, #number_of_pages

Instance Method Summary collapse

Constructor Details

#initialize(api_key) ⇒ PdfMergeClient

Construct the Pdf Merge Client.

Parameters:

  • api_key

    API Key.


1796
1797
1798
1799
1800
1801
1802
# File 'lib/selectpdf.rb', line 1796

def initialize(api_key)
  super()
  @api_endpoint = 'https://selectpdf.com/api2/pdfmerge/'
  @parameters['key'] = api_key

  @file_idx = 0
end

Instance Method Details

#add_file(input_pdf, user_password = nil) ⇒ Object

Add local PDF document to the list of input files.

Parameters:

  • input_pdf

    Path to a local PDF file.

  • user_password (defaults to: nil)

    User password for the PDF document (optional).


1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
# File 'lib/selectpdf.rb', line 1808

def add_file(input_pdf, user_password = nil)
  @file_idx += 1

  @files["file_#{@file_idx}"] = input_pdf
  @parameters.delete("url_#{@file_idx}")

  if user_password.nil? || user_password.empty?
    @parameters.delete("password_#{@file_idx}")
  else
    @parameters["password_#{@file_idx}"] = user_password
  end
end

#add_url_file(input_url, user_password = nil) ⇒ Object

Add remote PDF document to the list of input files.

Parameters:

  • input_url

    Url of a remote PDF file.

  • user_password (defaults to: nil)

    User password for the PDF document (optional).


1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
# File 'lib/selectpdf.rb', line 1825

def add_url_file(input_url, user_password = nil)
  @file_idx += 1

  @parameters["url_#{@file_idx}"] = input_url
  @files.delete("file_#{@file_idx}")

  if user_password.nil? || user_password.empty?
    @parameters.delete("password_#{@file_idx}")
  else
    @parameters["password_#{@file_idx}"] = user_password
  end
end

#doc_add_creation_date=(doc_add_creation_date) ⇒ Object

Add the date and time when the PDF document was created to the PDF document information. The default value is False.

Parameters:

  • doc_add_creation_date

    Add creation date to the document metadata or not.


1966
1967
1968
# File 'lib/selectpdf.rb', line 1966

def doc_add_creation_date=(doc_add_creation_date)
  @parameters['doc_add_creation_date'] = doc_add_creation_date
end

#doc_author=(doc_author) ⇒ Object

Set the name of the PDF document author.

Parameters:

  • doc_author

    Document author.


1959
1960
1961
# File 'lib/selectpdf.rb', line 1959

def doc_author=(doc_author)
  @parameters['doc_author'] = doc_author
end

#doc_keywords=(doc_keywords) ⇒ Object

Set the PDF document keywords.

Parameters:

  • doc_keywords

    Document keywords.


1952
1953
1954
# File 'lib/selectpdf.rb', line 1952

def doc_keywords=(doc_keywords)
  @parameters['doc_keywords'] = doc_keywords
end

#doc_subject=(doc_subject) ⇒ Object

Set the subject of the PDF document.

Parameters:

  • doc_subject

    Document subject.


1945
1946
1947
# File 'lib/selectpdf.rb', line 1945

def doc_subject=(doc_subject)
  @parameters['doc_subject'] = doc_subject
end

#doc_title=(doc_title) ⇒ Object

Set the PDF document title.

Parameters:

  • doc_title

    Document title.


1938
1939
1940
# File 'lib/selectpdf.rb', line 1938

def doc_title=(doc_title)
  @parameters['doc_title'] = doc_title
end

#owner_password=(owner_password) ⇒ Object

Set PDF owner password.

Parameters:

  • owner_password

    PDF owner password.


2047
2048
2049
# File 'lib/selectpdf.rb', line 2047

def owner_password=(owner_password)
  @parameters['owner_password'] = owner_password
end

#saveObject

Merge all specified input pdfs and return the resulted PDF.

Returns:

  • Byte array containing the resulted PDF.


1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
# File 'lib/selectpdf.rb', line 1841

def save
  @parameters['async'] = 'False'
  @parameters['files_no'] = @file_idx

  result = perform_post_as_multipart_formdata

  @file_idx = 0
  @files = {}

  result
end

#save_asyncObject

Merge all specified input pdfs and return the resulted PDF. An asynchronous call is used.

Returns:

  • Byte array containing the resulted PDF.

Raises:

  • (ApiException.new('Asynchronous call did not finish in expected timeframe.'))

1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
# File 'lib/selectpdf.rb', line 1877

def save_async
  @parameters['files_no'] = @file_idx

  job_id = start_async_job_multipart_form_data

  if job_id.nil? || job_id.empty?
    raise ApiException.new('An error occurred launching the asynchronous call.'), 'An error occurred launching the asynchronous call.'
  end

  no_pings = 0

  while no_pings < @async_calls_max_pings
    no_pings += 1

    # sleep for a few seconds before next ping
    sleep(@async_calls_ping_interval)

    async_job_client = AsyncJobClient.new(@parameters['key'], @job_id)
    async_job_client.api_endpoint = @api_async_endpoint

    result = async_job_client.result

    next if result.nil?

    @number_of_pages = async_job_client.number_of_pages
    @file_idx = 0
    @files = {}

    return result
  end

  @file_idx = 0
  @files = {}

  raise ApiException.new('Asynchronous call did not finish in expected timeframe.'), 'Asynchronous call did not finish in expected timeframe.'
end

#save_to_file(file_path) ⇒ Object

Merge all specified input pdfs and writes the resulted PDF to a local file.

Parameters:

  • file_path

    Local file including path if necessary.


1864
1865
1866
1867
1868
1869
1870
1871
1872
# File 'lib/selectpdf.rb', line 1864

def save_to_file(file_path)
  result = save
  File.open(file_path, 'wb') do |file|
    file.write(result)
  end
rescue ApiException
  FileUtils.rm(file_path) if File.exist?(file_path)
  raise
end

#save_to_file_async(file_path) ⇒ Object

Merge all specified input pdfs and writes the resulted PDF to a local file. An asynchronous call is used.

Parameters:

  • file_path

    Local file including path if necessary.


1925
1926
1927
1928
1929
1930
1931
1932
1933
# File 'lib/selectpdf.rb', line 1925

def save_to_file_async(file_path)
  result = save_async
  File.open(file_path, 'wb') do |file|
    file.write(result)
  end
rescue ApiException
  FileUtils.rm(file_path) if File.exist?(file_path)
  raise
end

#save_to_stream(stream) ⇒ Object

Merge all specified input pdfs and writes the resulted PDF to a specified stream.

Parameters:

  • stream

    The output stream where the resulted PDF will be written.


1856
1857
1858
1859
# File 'lib/selectpdf.rb', line 1856

def save_to_stream(stream)
  result = save
  stream.write(result)
end

#save_to_stream_async(stream) ⇒ Object

Merge all specified input pdfs and writes the resulted PDF to a specified stream. An asynchronous call is used.

Parameters:

  • stream

    The output stream where the resulted PDF will be written.


1917
1918
1919
1920
# File 'lib/selectpdf.rb', line 1917

def save_to_stream_async(stream)
  result = save_async
  stream.write(result)
end

#set_custom_parameter(parameter_name, parameter_value) ⇒ Object

Set a custom parameter. Do not use this method unless advised by SelectPdf.

Parameters:

  • parameter_name

    Parameter name.

  • parameter_value

    Parameter value.


2063
2064
2065
# File 'lib/selectpdf.rb', line 2063

def set_custom_parameter(parameter_name, parameter_value)
  @parameters[parameter_name] = parameter_value
end

#timeout=(timeout) ⇒ Object

Set the maximum amount of time (in seconds) for this job. The default value is 30 seconds. Use a larger value (up to 120 seconds allowed) for large documents.

Parameters:

  • timeout

    Timeout in seconds.


2055
2056
2057
# File 'lib/selectpdf.rb', line 2055

def timeout=(timeout)
  @parameters['timeout'] = timeout
end

#user_password=(user_password) ⇒ Object

Set PDF user password.

Parameters:

  • user_password

    PDF user password.


2040
2041
2042
# File 'lib/selectpdf.rb', line 2040

def user_password=(user_password)
  @parameters['user_password'] = user_password
end

#viewer_center_window=(viewer_center_window) ⇒ Object

Set a flag specifying whether to position the document's window in the center of the screen. The default value is False.

Parameters:

  • viewer_center_window

    Center window or not.


1998
1999
2000
# File 'lib/selectpdf.rb', line 1998

def viewer_center_window=(viewer_center_window)
  @parameters['viewer_center_window'] = viewer_center_window
end

#viewer_display_doc_title=(viewer_display_doc_title) ⇒ Object

Set a flag specifying whether the window's title bar should display the document title taken from document information. The default value is False.

Parameters:

  • viewer_display_doc_title

    Display title or not.


2005
2006
2007
# File 'lib/selectpdf.rb', line 2005

def viewer_display_doc_title=(viewer_display_doc_title)
  @parameters['viewer_display_doc_title'] = viewer_display_doc_title
end

#viewer_fit_window=(viewer_fit_window) ⇒ Object

Set a flag specifying whether to resize the document's window to fit the size of the first displayed page. The default value is False.

Parameters:

  • viewer_fit_window

    Fit window or not.


2012
2013
2014
# File 'lib/selectpdf.rb', line 2012

def viewer_fit_window=(viewer_fit_window)
  @parameters['viewer_fit_window'] = viewer_fit_window
end

#viewer_hide_menu_bar=(viewer_hide_menu_bar) ⇒ Object

Set a flag specifying whether to hide the pdf viewer application's menu bar when the document is active. The default value is False.

Parameters:

  • viewer_hide_menu_bar

    Hide menu bar or not.


2019
2020
2021
# File 'lib/selectpdf.rb', line 2019

def viewer_hide_menu_bar=(viewer_hide_menu_bar)
  @parameters['viewer_hide_menu_bar'] = viewer_hide_menu_bar
end

#viewer_hide_toolbar=(viewer_hide_toolbar) ⇒ Object

Set a flag specifying whether to hide the pdf viewer application's tool bars when the document is active. The default value is False.

Parameters:

  • viewer_hide_toolbar

    Hide tool bars or not.


2026
2027
2028
# File 'lib/selectpdf.rb', line 2026

def viewer_hide_toolbar=(viewer_hide_toolbar)
  @parameters['viewer_hide_toolbar'] = viewer_hide_toolbar
end

#viewer_hide_window_ui=(viewer_hide_window_ui) ⇒ Object

Set a flag specifying whether to hide user interface elements in the document's window (such as scroll bars and navigation controls), leaving only the document's contents displayed.

Parameters:

  • viewer_hide_window_ui

    Hide window UI or not.


2033
2034
2035
# File 'lib/selectpdf.rb', line 2033

def viewer_hide_window_ui=(viewer_hide_window_ui)
  @parameters['viewer_hide_window_ui'] = viewer_hide_window_ui
end

#viewer_page_layout=(viewer_page_layout) ⇒ Object

Set the page layout to be used when the document is opened in a PDF viewer. The default value is SelectPdf::PageLayout::ONE_COLUMN.

Use constants from SelectPdf::PageLayout class.

Parameters:

  • viewer_page_layout

    Page layout. Possible values: 0 (Single Page), 1 (One Column), 2 (Two Column Left), 3 (Two Column Right).


1974
1975
1976
1977
1978
1979
1980
# File 'lib/selectpdf.rb', line 1974

def viewer_page_layout=(viewer_page_layout)
  unless [0, 1, 2, 3].include?(viewer_page_layout)
    raise ApiException.new('Allowed values for Page Layout: 0 (Single Page), 1 (One Column), 2 (Two Column Left), 3 (Two Column Right).'), 'Allowed values for Page Layout: 0 (Single Page), 1 (One Column), 2 (Two Column Left), 3 (Two Column Right).'
  end

  @parameters['viewer_page_layout'] = viewer_page_layout
end

#viewer_page_mode=(viewer_page_mode) ⇒ Object

Set the document page mode when the pdf document is opened in a PDF viewer. The default value is SelectPdf::PageMode::USE_NONE.

Use constants from SelectPdf::PageMode class.

Parameters:

  • viewer_page_mode

    Page mode. Possible values: 0 (Use None), 1 (Use Outlines), 2 (Use Thumbs), 3 (Full Screen), 4 (Use OC), 5 (Use Attachments).


1986
1987
1988
1989
1990
1991
1992
1993
# File 'lib/selectpdf.rb', line 1986

def viewer_page_mode=(viewer_page_mode)
  unless [0, 1, 2, 3, 4, 5].include?(viewer_page_mode)
    raise ApiException.new('Allowed values for Page Mode: 0 (Use None), 1 (Use Outlines), 2 (Use Thumbs), 3 (Full Screen), 4 (Use OC), 5 (Use Attachments).'),
          'Allowed values for Page Mode: 0 (Use None), 1 (Use Outlines), 2 (Use Thumbs), 3 (Full Screen), 4 (Use OC), 5 (Use Attachments).'
  end

  @parameters['viewer_page_mode'] = viewer_page_mode
end