Ruby wrapper to read and write Excel through the cloudxls API.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
.gitignore
Gemfile
LICENSE
README.md
Rakefile
cloudxls.gemspec

README.md

Installation

gem install cloudxls

Or in your Gemfile

gem 'cloudxls', '~> 2.0.2'

Documentation

Additional documentation: https://docs.cloudxls.com or check the sample rails integration.

Quick Start Guide

Set-up API-Keys

Register on https://www.cloudxls.com to get an API key.

Either set the ENV variable CLOUDXLS_API_KEY or manually using Cloudxls.api_key#=

Cloudxls.api_key = "YOUR-API-KEY"

Set-up for cloudxls on-premise installations

Additional configuration settings for the client when running cloudxls on-premises:

Cloudxls.api_key = ""
Cloudxls.api_base = "localhost"
Cloudxls.port = 8080
Cloudxls.use_ssl = false

Sandbox

If you use a sandbox API key (starting with 'test_') the client sends requests to the sandbox test API.

Read-API

Send an xls or xlsx file using the Cloudxls#read method. #as_json will start the request and #to_h parses the json into a ruby hash.

data = Cloudxls.read(file: File.new("/path/to/my-excel.xls")).as_json.to_h

Output

[
  {
    "name" : "Sheet1",
    "rows" : [
      ["hello", "world"],
      ["lorem", "ipsum"]
    ]
  }
]

From a remote url

data = Cloudxls.read(file_url: "http://example.org/data.xls").as_json.to_h

Save json to a file

Cloudxls.read(file: File.new("my-excel.xls"))
  .save_as("output.json")

Or access the response_stream directly

io = File.new("output.json", "w")
Cloudxls.read(file: File.new("/path/to/my-excel.xls")).as_csv.each do |chunk|
  io.write chunk
end
io.close

Write-API

Write a xls file with a single sheet.

csv_string = "hello,world\nfoo,bar"

Cloudxls.write(csv: csv_string)
  .as_xls
  .save_as("/tmp/hello-world.xls")

Write xlsx:

Cloudxls.write(csv: csv_string)
  .as_xlsx
  .save_as("/tmp/hello-world.xlsx")

With options:

req = Cloudxls.write(
  csv: csv_string,
  offset: "B2",
  sheet_name: "Data"
)
xls_response = req.as_xls
xls_response.save_as("/tmp/hello-world.xls")

Multiple sheets:

Cloudxls.write(csv: csv_string)
  .add_data(csv: "more,data")
  .add_data(csv: "more,data", sheet_name: "foobar")
  .as_xls
  .save_as("/tmp/hello-world.xls")

Append data to a excel file (xls or xlsx)

Cloudxls.write(csv: csv_string)
  .append_to(File.new("/path/to/my-file.xls"))
  .as_xls
  .save_as("/tmp/hello-world.xls")

Useage in Rails

The most efficient way is to directly stream the cloudxls response to the client. Assign the result of a #write or #read call to the response_body.

def index
  csv_data = "hello,world"

  headers["Content-Type"] = Mime::Type.lookup_by_extension(params[:format])
  headers["Content-disposition"] = "attachment; filename=data.#{params[:format]}"

  respond_to do |format|

    format.csv  { self.response_body = csv_data }
    format.xls  { self.response_body = Cloudxls.write(csv: csv_data).as_xls }
    format.xlsx { self.response_body = Cloudxls.write(csv: csv_data).as_xlsx }
  end
end