324 lines
6.3 KiB
Markdown
324 lines
6.3 KiB
Markdown
# Notare
|
|
|
|
A Ruby gem for creating docx files with a simple DSL
|
|
|
|
## Installation
|
|
|
|
Add this line to your application's Gemfile:
|
|
|
|
```ruby
|
|
gem 'notare'
|
|
```
|
|
|
|
And then execute:
|
|
|
|
$ bundle install
|
|
|
|
Or install it yourself as:
|
|
|
|
$ gem install notare
|
|
|
|
## Usage
|
|
|
|
### Basic Example
|
|
|
|
```ruby
|
|
require 'notare'
|
|
|
|
Notare::Document.create("output.docx") do |doc|
|
|
doc.p "Hello World"
|
|
end
|
|
```
|
|
|
|
### Paragraphs
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
# Simple paragraph
|
|
doc.p "This is a paragraph."
|
|
|
|
# Paragraph with multiple text runs
|
|
doc.p do
|
|
doc.text "First part. "
|
|
doc.text "Second part."
|
|
end
|
|
end
|
|
```
|
|
|
|
### Text Formatting
|
|
|
|
Formatting uses nested blocks. Nesting combines formatting styles.
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
doc.p do
|
|
doc.text "Normal text "
|
|
doc.b { doc.text "bold" }
|
|
doc.text " and "
|
|
doc.i { doc.text "italic" }
|
|
doc.text " and "
|
|
doc.u { doc.text "underlined" }
|
|
end
|
|
|
|
# Nested formatting (bold + italic)
|
|
doc.p do
|
|
doc.b do
|
|
doc.i { doc.text "bold and italic" }
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
### Headings
|
|
|
|
Use `h1` through `h6` for document headings:
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
doc.h1 "Document Title"
|
|
doc.h2 "Chapter 1"
|
|
doc.h3 "Section 1.1"
|
|
doc.h4 "Subsection"
|
|
doc.h5 "Minor heading"
|
|
doc.h6 "Smallest heading"
|
|
|
|
# Headings with formatted content
|
|
doc.h2 do
|
|
doc.text "Chapter with "
|
|
doc.i { doc.text "emphasis" }
|
|
end
|
|
end
|
|
```
|
|
|
|
### Styles
|
|
|
|
Notare includes built-in styles and supports custom style definitions.
|
|
|
|
#### Built-in Styles
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
doc.p "This is a title", style: :title
|
|
doc.p "A subtitle", style: :subtitle
|
|
doc.p "A quotation", style: :quote
|
|
doc.p "puts 'code'", style: :code
|
|
end
|
|
```
|
|
|
|
#### Custom Styles
|
|
|
|
Define your own styles with text and paragraph properties:
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
# Define custom styles
|
|
doc.define_style :warning,
|
|
bold: true,
|
|
color: "FF0000",
|
|
size: 14
|
|
|
|
doc.define_style :note,
|
|
italic: true,
|
|
color: "0066CC",
|
|
font: "Georgia"
|
|
|
|
doc.define_style :centered,
|
|
align: :center,
|
|
size: 12
|
|
|
|
# Apply to paragraphs
|
|
doc.p "Warning message!", style: :warning
|
|
doc.p "Centered text", style: :centered
|
|
|
|
# Apply to text runs
|
|
doc.p do
|
|
doc.text "Normal text, "
|
|
doc.text "important!", style: :warning
|
|
doc.text ", and "
|
|
doc.text "a note", style: :note
|
|
end
|
|
end
|
|
```
|
|
|
|
#### Style Properties
|
|
|
|
**Text properties:**
|
|
- `bold: true/false`
|
|
- `italic: true/false`
|
|
- `underline: true/false`
|
|
- `color: "FF0000"` (hex RGB)
|
|
- `size: 14` (points)
|
|
- `font: "Arial"` (font family)
|
|
|
|
**Paragraph properties:**
|
|
- `align: :left / :center / :right / :justify`
|
|
- `indent: 720` (twips, 1 inch = 1440 twips)
|
|
- `spacing_before: 240` (twips)
|
|
- `spacing_after: 240` (twips)
|
|
|
|
### Lists
|
|
|
|
#### Bullet Lists
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
doc.ul do
|
|
doc.li "First item"
|
|
doc.li "Second item"
|
|
doc.li { doc.b { doc.text "Bold item" } }
|
|
end
|
|
end
|
|
```
|
|
|
|
#### Numbered Lists
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
doc.ol do
|
|
doc.li "First"
|
|
doc.li "Second"
|
|
doc.li "Third"
|
|
end
|
|
end
|
|
```
|
|
|
|
### Tables
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
doc.table do
|
|
doc.tr do
|
|
doc.td "Header 1"
|
|
doc.td "Header 2"
|
|
end
|
|
doc.tr do
|
|
doc.td "Cell 1"
|
|
doc.td { doc.b { doc.text "Bold cell" } }
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
### Images
|
|
|
|
Images can be added to paragraphs, table cells, and list items. Supports PNG and JPEG formats.
|
|
|
|
```ruby
|
|
Notare::Document.create("output.docx") do |doc|
|
|
# Simple image (uses native dimensions)
|
|
doc.p do
|
|
doc.image "photo.png"
|
|
end
|
|
|
|
# Image with explicit dimensions (inches, cm, or pixels)
|
|
doc.p do
|
|
doc.image "logo.png", width: "2in", height: "1in"
|
|
end
|
|
|
|
# Specify only width (height auto-calculated to maintain aspect ratio)
|
|
doc.p do
|
|
doc.image "banner.jpg", width: "5cm"
|
|
end
|
|
|
|
# Image with text in the same paragraph
|
|
doc.p do
|
|
doc.text "Company Logo: "
|
|
doc.image "logo.png", width: "0.5in", height: "0.5in"
|
|
end
|
|
|
|
# Image in a table cell
|
|
doc.table do
|
|
doc.tr do
|
|
doc.td "Product"
|
|
doc.td do
|
|
doc.image "product.jpg", width: "1in", height: "1in"
|
|
end
|
|
end
|
|
end
|
|
|
|
# Image in a list item
|
|
doc.ul do
|
|
doc.li do
|
|
doc.image "icon.png", width: "16px", height: "16px"
|
|
doc.text " List item with icon"
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
### Complete Example
|
|
|
|
```ruby
|
|
Notare::Document.create("report.docx") do |doc|
|
|
doc.p "Monthly Report"
|
|
|
|
doc.p do
|
|
doc.text "This report contains "
|
|
doc.b { doc.text "important" }
|
|
doc.text " information."
|
|
end
|
|
|
|
doc.p "Key Points:"
|
|
|
|
doc.ul do
|
|
doc.li "Revenue increased by 15%"
|
|
doc.li "Customer satisfaction improved"
|
|
doc.li { doc.i { doc.text "See appendix for details" } }
|
|
end
|
|
|
|
doc.p "Summary Table:"
|
|
|
|
doc.table do
|
|
doc.tr do
|
|
doc.td "Metric"
|
|
doc.td "Value"
|
|
end
|
|
doc.tr do
|
|
doc.td "Revenue"
|
|
doc.td "$1.2M"
|
|
end
|
|
doc.tr do
|
|
doc.td "Growth"
|
|
doc.td { doc.b { doc.text "15%" } }
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
## API Reference
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `p(text, style:)` | Create a paragraph with text and optional style |
|
|
| `p(style:) { }` | Create a paragraph with block content and optional style |
|
|
| `text(value, style:)` | Add text with optional style to the current context |
|
|
| `h1(text)` - `h6(text)` | Create headings (level 1-6) |
|
|
| `b { }` | Bold formatting |
|
|
| `i { }` | Italic formatting |
|
|
| `u { }` | Underline formatting |
|
|
| `define_style(name, **props)` | Define a custom style |
|
|
| `ul { }` | Bullet list |
|
|
| `ol { }` | Numbered list |
|
|
| `li(text)` | List item with text |
|
|
| `li { }` | List item with block content |
|
|
| `table { }` | Table |
|
|
| `tr { }` | Table row |
|
|
| `td(text)` | Table cell with text |
|
|
| `td { }` | Table cell with block content |
|
|
| `image(path, width:, height:)` | Insert image (PNG/JPEG). Dimensions: `"2in"`, `"5cm"`, `"100px"`, or integer pixels |
|
|
|
|
## Development
|
|
|
|
After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.
|
|
|
|
```bash
|
|
bundle install
|
|
bundle exec rake test # Run tests
|
|
bundle exec rake rubocop # Run linter
|
|
bundle exec rake # Run both
|
|
```
|
|
|
|
## License
|
|
|
|
The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
|