Admissions Slate Schedule Generator

Slate Schedule Generator

This project accepts prospective student visit schedule data from Slate and generates a formatted PDF schedule for each student based on an HTML template.

Installation

Note: For most purposes, this software will be distributed remotely onto your machine. To request installation, contact Information Technology.

Run the slate_schedule_generator_setup.exe file, and follow the prompts. For silent installation (skip prompts, install in background), run the setup file from a terminal window:

    slate_schedule_generator.exe /S

Running the program

Double-click on the slate_schedule_generator.exe file to run the program. Alternatively, run the Slate Schedule Generator Start Menu shortcut (if installed)

For a commmand-line-interface (CLI), run the slate_schedule_generator_cli.exe. This will run in a terminal window instead of a graphical interface.

Output PDF files are stored in the Documents\slate_schedule_generator folder and named according to current time. If this directory does not already exist, the program will create it.

Printing PDF files

Once the program runs sucessfully, it will generate a PDF formatted to fit an 8.5 x 11 inch piece of paper. In some cases, print previews can cause the output to shrink and not fit the paper properly. To avoid this, be sure to set the sizing setting to Actual size instead of Fit.

Spreadsheet Formatting

To properly generate a schedule, it is important that the input spreadsheet is formatted properly, and contains the columns specified in config.json. By default, the following fields are supported:

Meeting fields:

  • Fac1_Mtg_
  • Fac2_Mtg_
  • Coach_Mtg_
  • Counselor_Mtg_
  • Rotc_Mtg_

Special fields:

  • Special1_
  • Special2_
  • Special3_

Lunch fields:

  • Faculty_Lunch_Mtg_

Custom fields:

Note: Custom fields are a special case, as they do not accept a Name field. The name for a custom event is specified in config.json.

  • Check_In_
  • Cedarville_Experience_
  • Chapel_
  • Lunch_
  • Lunch_Current_Student_
  • Campus_Tour_
  • Dorm_Tour_

Adding Event Information

To add event information for these fields, append any of the following data fields to the field name to create the column name:

  • Time
  • Name
  • Position
  • Location
  • Room

For example, the complete list of supported fields for Fac1_Mtg_ would be:

  • Fac1_Mtg_Time
  • Fac1_Mtg_Name
  • Fac1_Mtg_Position
  • Fac1_Mtg_Location
  • Fac1_Mtg_Room

Event Overflow

Due to the nature of a prospective student visit, there are many different types of events that can end up on a schedule. In some cases, there are too many events to fit properly on the printed schedule, and they will overflow into the footer. To work around this, create a second record in the spreadsheet for the student, and split the events between the two. This will cause the program to generate two schedules that can be used together.

Date Formatting

In order for the script to properly read the information in the exported spreadsheet, it is important that each field is formatted properly. For example, “Time” fields should always contain a time such as “9:00 PM”, and cannot contain any other information. If the program finds an improperly-formatted time, it will replace the time with a default value (12:00 AM).

Config files

The following files are required in the %PROGRAMDATA%\slate_schedule_generator directory and are installed by default:

  • config.json

    Contains the expected fields to be extracted from the spreadsheet file, and the data to be extracted from those fields.

    Supported categories are:

    1. meeting - will prepend “Meeting with” to name provided
    2. special - will not prepend “Meeting with” to name provided
    3. lunch - will prepend “Lunch with” to name provided
    4. custom - nested dictionary of custom-named events that do not accept name field.

    When searching for a given field, the script searches for several different attributes on each category, by appending the attributes to the end of the field name. For example, when searching for Fac1_Mtg_, the script will search for a column named Fac1_Mtg_Time.

    Default info_fields are:

    1. Time
    2. Name
    3. Position
    4. Location
    5. Room

    When a field is not found in the spreadsheet, the program will skip it.

    Custom info fields are supported. To add an info field, the corresponding field must also be added to the HTML template file for display (see template.html)

    When making changes to this file, be sure to create a backup copy of the file, just in case something breaks. If everything else fails, remove the file from the directory and the program will create a new one from defaults.

  • template.html

    Contains the template that is used to generate the formatted schedule. Fields are specified by using double brackets, such as:

      {{ student['First'] }}

    In addition, python code blocks can be specified using the following syntax:

      {% for event in student['Events'] -%} 
      <p>some HTML</p>
  {% endfor -%}

    The program passes a list of dictionary objects representing students, and each student dictionary contains a list of dictionary objects representing events for that student.

    In addition, template.html contains a stylesheet that formats the outputted pdf file. If you are familiar with CSS, feel free to adjust these values as needed. Again, make a backup file first.

Troubleshooting

Common issues that can cause problems:

  • If input data on the spreadsheet is not displaying on the output PDF, it is probably because your column names are wrong. Check to make sure there are no weird spaces, and that the names match the columns specified in config.json.
  • If a column name is added to config.json but is not added to template.html, the added data will not appear on the output PDF file. Be sure any added fields are present in both files.
  • When dragging and dropping filenames, spaces or characters such as ’ and " can cause issues opening the file. If it is not working, try adjusting the file path manually or use the GUI.
  • If the template.html file is not in the %PROGRAMDATA%\Slate Schedule Generator directory, the program cannot format the data. Make sure the file is properly named and in the correct location.
  • If wkhtmltopdf.exe is missing, the program can’t generate a PDF. Download the executable (see Project Dependencies) and place in the \bin directory.
  • If the spreadsheet contains Unicode characters not supported by UTF-8, the program is unable to generate a schedule. Remove these characters from the spreadsheet to fix the issue.

If the program is crashing, your config files are probably wrong, or you are missing the wkhtmltopdf.exe file. Run the program in a terminal window to view error output:

  1. Press Win + R

  2. Type cmd or powershell

  3. Navigate to program location using cd. For example:

     cd C:\Program Files (x86)\slate_schedule_generator

  4. Run program:

     .\slate_schedule_generator_cli.exe

Note: the executable was generated for Python 3.7.3 on a 64-bit installation on Windows. To upgrade to later Python versions, recomplile Python script using PyInstaller (https://www.pyinstaller.org/).

Project Dependencies

For running compiled python executable:

For running python script:

Required file structure for running executable:

(Installation Directory)
C:\Program Files (x86)\Slate Schedule Generator
    slate_schedule_generator.exe
    slate_schedule_generator_cli.exe
    (all other package files included with installation)
    bin
        wkhtmltopdf.exe
    
(Configuration Directory)
C:\ProgramData\Slate Schedule Generator
    config.json (will revert to default config if this is missing)
    template.html

Compiling Project from Source Code (advanced)

Creating executables

To compile an executable from Python code, use PyInstaller:

    pip install pyinstaller
    pyinstaller -n slate_schedule_generator --icon="logo.ico" ssg_gui.py
    pyinstaller -n slate_schedule_generator_cli --icon="logo.ico" slate_schedule_generator.py

These commands will generate two folders in the \dist directory containing the executable files for each Python script.

Once the command finishes, perform the following steps:

  1. Since slate_schedule_generator.exe contains the same dependencies as slate_schedule_generator_cli.exe, combine the two folders by copying slate_schedule_generator_cli.exe and slate_schedule_generator_cli.exe.manifest into the other folder so that both executables are in the same folder. Delete the duplicate folder.

  2. Place the config.json and template.html files in the %ProgramData%\slate_schedule_generator directory.

  3. Place the wkhtmltopdf.exe executable in the \bin directory (download: https://wkhtmltopdf.org/downloads.html). Only the .exe file is required.

  4. Run the executable. If you encounter errors, debug by running from a command line and viewing debug output (see Debugging).

Creating installer

NSIS (Nullsoft Scriptable Install System - nsis.sourceforge.io) is used to create a lightweight single-file installer to install the software on a given machine. The created installer must fulfill the following requirements for the program to function properly:

  1. All program executables are placed in Program Files
  2. Configuration files (template.html and config.json) are placed in %ProgramData%\slate_schedule_generator
  3. Uninstaller removes all installed files, including configuration files
  4. Uninstaller is accessible through Add/Remove Programs

To create an installer from the installation script install_script.nsi, install and run NSIS from nsis.sourceforge.io and click “Compile NSIS scripts”.

The installation script install_script.nsi should function properly, provided that the following files are placed in the same directory as the script (in addition to the compiled files created by PyInstaller):

  1. bin\wkhtmltopdf.exe
  2. template.html
  3. config.json
  4. logo.ico
  5. README.md

Resources for compiling and creating installer

Future release ideas:

  • Drag’n’drop support for GUI
Was this helpful?
0 reviews

Details

Article ID: 78611
Created
Mon 5/20/19 3:21 PM
Modified
Tue 10/24/23 9:16 AM