README.md

# Excompose

A library for composing XLSX files based off templates, with full support of template styling.

## Installation

Add `ex_compose` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:ex_compose, "~> 1.0.0"}
  ]
end
```

## Usage

### Setup

#### Application Config
```elixir
# config.exs
config :ex_compose,
	tmp_dir: "tmp", # should be relative to project root
	time_zone: {8, "Asia/Singapore"}
```
`tmp_dir`: the relative path to a folder from your project root. That folder will be the working directory for `ex_compose`.
e.g. if your project is at `/Users/MOI/workspace/my_app`, and `tmp_dir` is set to `temp`, ex_compose will work in the folder `/Users/MOI/workspace/my_app/tmp_dir`.

`time_zone`: `ex_compose` for logging and operating purposes. Input `{tz_offset, iana_time_zone}`, where `tz_offset` is an integer or float for the number of hours of offset for your server's time zone, and `iana_time_zone` is the country time zone code. This will be used to timestamp the working files.

### Write XLSX Files

Say you have an simple empty report template with the cells for `name`, `city` and `total_income` to be filled up.

In your template xlsx file, in the desired cells, add in the values `{{name}}`, `{{city}}` and `{{total_income}}` respectively. Custom tags are supported, check out the next section later.

Then run:

```elixir
# relative path to the template .xlsx file from your project root
template_file = "priv/static/docs/report_template.xlsx"

# desired .xlsx file (relative path from project root)
destination_file = "priv/static/monthly_reports/2019-02-report.xlsx"

# all optional
options = %{
	delimiter: {"[[", "]]"}, # instead of "{{" "}}"
	tmp_dir_header: "MonthlyReport"
}

# run this from anywhere in your project to get the project root
IO.inspect(File.cwd!, label: "the project root")

{:ok, result_file} = ExCompose.write_xlsx(%{"name" => "John Doe", "city" => "Brisbane", "total_income" => "120000", options}, :gsub, template_file, destination_file)
# or
{:ok, result_file} = ExCompose.write_xlsx(%{"name" => "John Doe", "city" => "Brisbane", "total_income" => "120000", options}, :gsub, template_file, destination_file, options)

```

## FAQ

- `:gsub`?
More writing options next time.