Commit 7b9eb749 authored by S Anand's avatar S Anand

Expand docs

parent 42325485
Pipeline #30784 failed with stage
in 13 seconds
......@@ -112,9 +112,8 @@ change:
By default, changes are applied to all slides. To restrict changes to a specific
slide, use:
1. `slide-number` slide number (with the first slide as slide 1).
1. `slide-number` slide number or list (with the first slide as slide 1).
1. `slide-title` is a regular expression that matches the slide title.
1. `slide-range`: slide number range as a list of 2 slides
```yaml
source: input.pptx
......@@ -127,8 +126,6 @@ rule-2:
rule-3:
slide-title: Hello # rule-3 applies to slides with the title "Hello" (regex)
...
rule-4:
slide-range: [3, 6] # rule-4 applies to slides 3, 4, 5, 6 (inclusive)
...
```
......@@ -136,7 +133,7 @@ To create multiple slides from data, add `data:` to the change. For example:
```yaml
source: input.pptx
target: out-slides.pptx
target: output.pptx
data:
sales: {xlsx: sales.xlsx}
change-title:
......@@ -146,13 +143,16 @@ change-title:
text: "Region {{ region }} has sales of ${{ sales }}"
```
The `data:` here is the name of the dataset defined in the root `data:` section.
This `data:` is an [expression](#expressions) using the root `data:` variables.
It can be used with
- `slide-number` to repeat individual slides
- `slide-number` to repeat 1 or more slides. For example `slide-number: [1,2]`
will copy slides 1 & 2 as many times as there are rows of data
- `slide-title` to repeat individual slides or multiple single slides
- `slide-range` to repeat groups of slides. For example `slide-range: [1,2]` will
copy slides 1 & 2 as many times as there are rows of data
Slide numbers always refers to the source slide number, not the target slide
number. Even if a slide is duplicated in the target, source slide numbers do not
change.
### Shapes
......@@ -187,7 +187,7 @@ this `config-group.yaml` replaces those:
```yaml
source: input.pptx
target: out-group.pptx
target: output.pptx
change-image:
Group 1: # Take the shape named "Group 1"
Caption: # Find the shape named "Caption" inside it
......@@ -205,19 +205,22 @@ shape's style and content, or add new content (like charts).
The following CSS-like commands change the shape's display attributes:
- `font-size`: sets the font size
- `font-family`: sets the font family
- `color`: sets the text / foreground color
- `fill`: sets the shape's background color
- `opacity`: sets the shape's opacity level
- `stroke`: sets the shape outline color
- `stroke-width`: sets the shape outline width
- `width`: sets the shape width
- `height`: sets the shape height
- `left`: sets the shape X position
- `top`: sets the shape Y position
- `opacity`: sets the shape's opacity level as a decimal from 0 - 1
- `color`: sets the text / foreground color as CSS colors
- `fill`: sets the shape's background color as CSS colors
- `stroke`: sets the shape outline color as CSS colors
- `stroke-width`: sets the shape outline width in points
- `width`: sets the shape width in points
- `height`: sets the shape height in points
- `left`: sets the shape X position in points
- `top`: sets the shape Y position in points
- `font-size`: sets the font size in points
- `font-family`: sets the font family as a font name
Values support [templates](#templates).
CSS colors can be specified in the same way they can in CSS.
1 point is 1/72 inches.
Values support [expressions](#expressions).
### Text
......@@ -258,6 +261,58 @@ To change the picture on an image, use:
`image:` values support [template](#templates), and can be a URL or file path.
### Table
Modifies existing tables. It accepts these keys:
- `data:` optional data [expression](#expressions) to render as the table. The
table expands on shrinks to accommodate the rows and columns in the data.
- `gradient:` is an optional dict of column-wise gradients. Keys are column
names. Values are dicts with keys:
- `gradient:` optional gradient name (Blues, RdYlGn, etc. TODO: Provide full
list). Defaults to RdYlGn
- `min:` optional minimum. Defaults to the column's min value
- `max:` optional maximum. Defaults to the column's max value
- `mid:` optional middle for diverging scales. Defaults to (max + min) / 2
```yaml
data: {url: sales.xslx, sheet: Sheet1}
Table 1:
table:
data: sales # use sales dataset
gradient: # apply gradients on these columns
Sales: {gradient: Blues} # Sales column is colored in blues
Margin: {gradient: RdYlGn, mid: 0} # Margin column is in RdYlGn, with 0 as yellow
```
### Chart
Modifies existing chart. TODO
### Replicate
To create multiple shapes using data, use `replicate:` and `data:`. For example:
```yaml
data:
sales: {xlsx: sales.xlsx}
multiple-objects:
Picture 1: # Take the Picture 1 shape
data: sales # Duplicate it for each row in sales
replicate: horizontal # Lay the images out horizontally to the right
margin: 10 # With a padding of 10 units
image: "{{ region }}.png" # Change the picture using this template
```
This `data:` is an [expression](#expressions) using the root `data:` variables.
For each row in `data`, the shape is duplicated and laid out based on `replicate:`.
`replicate:` supports these layouts:
- `horizontal` copies the element right with an optional `margin` (default: 0)
- `vertical` copies the element below with an optional `margin` (default: 0)
### Deprecated commands
- `rectangle`: use [CSS](#css) commands instead
......@@ -265,13 +320,13 @@ To change the picture on an image, use:
### To be documented
- `chart`
- `table`
- `sankey`
Note: these will use the same DSL we use for server-side charts in Gramex. TODO
- `bullet`
- `treemap`
- `heatgrid`
- `calendarmap`
- `heatgrid`
- `sankey`
- `treemap`
- `custom_table`
### Templates
......@@ -293,27 +348,15 @@ change:
`tweets[0]['user']['screen_name']` evaluated in Python. The variable `tweets` is
the result of loading `tweets.json`.
### Layout
### Expressions
To create multiple shapes using data, use `layout:` and `data:`. For example:
For commands that support expressions, values are evaluated as Python expressions
in the context of data. For example:
```yaml
data:
sales: {xlsx: sales.xlsx}
multiple-objects:
Picture 1: # Take the Picture 1 shape
data: sales # Duplicate it for each row in sales
layout: hotizontal # Lay the images out horizontally to the right
padding-right: 10 # With a padding of 10 units
image: "{{ region }}.png" # Change the picture using this template
tweets: tweets.json
change:
slide: 1
data: sales.groupby('city') # replicates slide 1 for every item in sales.groupby('city')
```
The `data:` here is the name of the dataset defined in the root `data:` section.
For each row in `data`, the shape is duplicated and laid out based on `layout:`.
`layout:` supports:
- `horizontal` copies the element right with an optional `padding-right` (default: 0)
- `vertical` copies the element below with an optional `padding-bottom` (default: 0)
- `wrap` copies the element to the right `cols` times, and then moves 1 row
below. It supports `padding-right` and `padding-bottom`
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment