Handout Generator
Bugs:
- Some pdf pages come out with the wrong orientation in the final handout.pdf
- I am unable to find a smooth solution. The pdf-lib library I use has not been maintained for 2 years. If a slide is in the wrong rotation, only way is to rotate every single slide/page of the powerpoint/pdf manually or by using a program.
To Add:
(README WIP)
Handout Generator was created to give more options to creating a handout like the ability to create a handout from the command line (TUI) and the ability to customize the template of the handout (ex. # of images, # of lines, # of textfields, their positions, their size and etc.).
However, as of now, only the TUI portion of the feature has been implemented. Customizability will be added after the frontend is finished.
Major Goals
- Create a website that will allow people to create custom templates and generate handouts using a GUI (also allow people to download the custom templates as JSON and allow the templates to be imported into the TUI version: handgen)
- Reason on the focus for a GUI to create templates is because the only way I can think of to create a custom template without a GUI is to create a JSON file from scratch and importing that into the program via a flag, but that can be really annoying and frustrating to debug for the end user if something goes wrong.
- Create the backend with user authentication & database for storing custom templates.
Table Of Contents:
How To install:
- Library: npm i handgen
- Executable: npm i -g handgen
Instructions for Global Installation:
- handgen uses 4 flags: -i, -o, -default, -online
- -i (required)
- Specifies the path to the asset directory where all of the source images & pdfs are going to be at.
- -o (optional)
- Specifies the path of the pdf file produced by handgen
- When flag is not specified, the default path is in the same directory handgen is executed, and the pdf name will be called "handout.pdf".
- -default (optional)
- Specifies the id of one of the default handout templates
- When flag is not specified, the default ID will be "ThreeTraitLine".
- -online (optional)
- Not available yet, but it also specifies the id of a handout template from cloud.
- When flag is not specified, the program will use the default template specified above in "-default".
- -default and -online may not be used as flags at the same time.
Default Template IDs:
One Image Per Page
Two Image Per Page
- TwoTraitNothing
- A portrait mode template with two pictures, one picture on top and one picture on bottom.
- TwoScapeLine
- A landscape mode template with two pictures, one picture to the left and one picture to the right, and contain lines below each picture.
- TwoScapeField
- A landscape mode template with two pictures, one picture to the left and one picture to the right, and contain a field below each picture.
Three Image Per Page
- ThreeTraitLine [DEFAULT]
- A portrait mode template with three pictures to the left and lines to the right of each picture.
- ThreeTraitField
- A portrait mode template with three pictures to the left and a textfield to the right of each picture.
- ThreeScapeLine
- A landscape mode template with three pictures and lines below each picture.
- ThreeScapeField
- A landscape mode template with three pictures and a textfield below each picture.
Four Image Per Page
- FourTraitNothing
- A portrait mode template with only four pictures evenly spaced.
- FourScapeNothing
- A landscape mode template with only four pictures evenly spaced.
Fundamentals - How It Works
Before we delve into how to use handgen in a JS project, we first have to go over the components and the structures that a handout template use to create a handout pdf:
- Page
- Pictures
- Lines
- Textfield
- Text
What is a template?
- A template is the building block used to build a component (the actual page/picture/line/etc.)
- A template specifies the attributes of of a component.
- For example, for a line component, you might specify the width and height of a picture component.
- All templates comes from JSON objects.
Page Template
- A page template contains the following components: pictures, lines, textfield and page number. It is also possible to tweak the width or height of a page template.
- There can be more than one page template in a handout template. For example, on one page, you might want three pictures, and on another page, you might want one picture instead.
Pictures
- A picture template can be an image (png, jpg, jpeg) or a pdf.
- This means that both images and pdf can be crammed (embedded and/or minified) into the handout pdf.
- The type for a picture contains the following properties (or attributes): width, height, x and y coordinates.
Lines
- A line template is a straight line with the color black.
- The type for a line contains the following properties: x1, y1, x2, y2 coordinates.
Textfield
- A textfield template is a rectangular box where the inside of the box is writeable with a keyboard.
- The type for a textfield contains the following properties: width, height, x and y coordinates.
Page Number
- A page number template specifies the location where a page number is located on a page.
- The type for a page number is called a Label, and a Label contains the following properties: size, x and y coordinates.
- Planned on being optional
Explanation for Handout Class
To use the Handout class. First, you need to instantiate a handout
import { Asset, TemplateRepo, Handout } from 'handgen';
const handout = new Handout();
There is only 1 method exposed from Handout, and that is createHandout(assets, templateID, repo).
assets: Asset[] -> Contains an array of assets, which are the images, pdf and/or pptx that you would like to insert into the resulting handout pdf.
- Type Asset is a type that specifies that an object must contain two properties: "type" and "bytes".
- type is a string property that holds the extension of the asset that got turned into a byte.
- bytes is the buffer of the asset (image or pdf file).
templateID: string -> Currently only supports default provided template ID.repo: TemplateRepo -> Specifies if the template is coming from local (default templates) or from remote (online templates)
- Type TemplateRepo is a string of either "default" or "online";
