~mun-tonsi/toki-sona

#toki-sona

toki-sona is an adaptable Ruby script for turning iCal calendars into a range of formatted text outputs, it can also email outputs using SMTP (which could be of use for mailing lists). It uses icalendar/icalendar for manipulating iCal files, OpenURI for fetching remote files, ERB for extensible templating, ManageIQ/optimist for argument parsing, and mikel/mail for working with emails.

#Usage

toki-sona can be interacted with using the command line. To start, clone this Git repository, and then run bundle in the directory to install dependencies. Then run the following:

bundle exec ruby main.rb -t /path/to/template -c https://example.com

The following represents the meaning of these arguments (which you can generate by running bundle exec ruby main.rb -h)

Options:
  -e, --email             Send emails
  -t, --template=<s>      Path to ERB template file
  -c, --calendars=<s+>    URIs where iCal files are located
  -o, --output=<s>        Redirect output to this file
  -f, --offset=<i>        Number of days from now to look for events, default is 7
  -h, --help              Show this message

#ERB templates

#A Markdown output in terminal example

Here's an example template I created for my loved ones over at Ambition's Graveyard in Norwich:

# Upcoming Events
## *At Ambition's Graveyard*
Calendar feed for members events: `[link redacted]`

<% for event in events[0] do %>
### <%= event.dtstart.strftime('%A %e %B') %> - <%= event.summary %> - <%= event.dtstart.strftime('%H:%M') %>-<%= event.dtend.strftime('%H:%M') %>
<%= event.description %>

<% end %>

## *Further Afield*
Calendar feed for further afield events selected by us: `[link redacted]`

<% for event in events[1] do %>
### <%= event.dtstart.strftime('%A %e %B') %> - <%= event.summary %> - <%= event.dtstart.strftime('%H:%M') %>-<%= event.dtend.strftime('%H:%M') %>
#### <%= event.location %>
<%= event.description %>

<% end %>

Output in this case would be generated by running: bundle exec ruby main.rb -t templates/ag.md.erb -c [link redacted] [link redacted] -f 28

#Email example

Only HTML emails can be sent at the moment (sorry), let me know if you'd like proper multipart emails set up! I use toki-sona to generate emails for my reading group at university (the FITLab Reading Group). I have the following template set up:

<p>Hi all,</p>
<% if not events.empty? %>
<p>There follows a list of upcoming FITLab Reading Group sessions:</p>
<% for event in events[0] do %>
<h2> <%= event.summary %></h2>
<p><b>Date:</b> <%= event.dtstart.strftime('%d/%m/%Y at %I:%M%#p') %> <i>(<%= event.dtstart.strftime('%z') %>)</i></p>
<p><b>Location:</b> <%= event.location %></p>
<p><%= event.description %></p>
<% end %>
<% else %>
<p>There are no scheduled FITLab Reading Group sessions (at least as far into the future as I can see). Please contact the FITLab Reading Group chairs or organisers if you have ideas for sessions!</p>
<% end %>
<p>Many thanks,</p>
<p>FITLab Reading Group Email Bot</p>
<p>--</p>
<p>On behalf of the organisers of the FITLab Reading Group,</p>
<p><b>Co-chairs:</b> [redacted]</p>
<p><b>Co-organisers:</b> [redacted] & Genevieve Clifford</p>
<p><b>Hopefully benevolent friend:</b> The FITLab Reading Group Email Bot</p>
<a href="https://fitlab.eu">https://fitlab.eu</a>

<p><i>Beep boop! This email was automatically generated at <%= DateTime.now %> and this email reflects the information held in the calendar then. If something is wrong, please contact <a href="mailto:[redacted]">Genevieve Clifford</a> or log an issue on the <a href="https://gitlab.com/mun-tonsi/toki-sona">toki-sona GitLab Repository</a>.</i></p>

Email relies on a number of environment variables being set, those being:

Environment Variable	Description	Example
`TOKI_SONA_SMTP_PORT`	Port SMTP server can be accessed at	587
`TOKI_SONA_SMTP_HOST`	SMTP Host	smtp.example.com
`TOKI_SONA_SMTP_DOMAIN`	Your email domain	example.com
`TOKI_SONA_SMTP_USER_NAME`	SMTP Username (usually your email address)	toki-sona@example.com
`TOKI_SONA_SMTP_PASSWORD`	SMTP Password	password
`TOKI_SONA_SMTP_SMTP_AUTHENTICATION`	SMTP authentication type	plain
`TOKI_SONA_SMTP_ENABLE_STARTTLS_AUTO`	If STARTTLS is enabled	true
`TOKI_SONA_TO`	Recipient of email	somebody@example.com
`TOKI_SONA_FROM`	Your email address	toki-sona@example.com
`TOKI_SONA_SUBJECT`	Subject of email to be sent	Test Email

Have a look at the Mail::SMTP class documentation if stuck!

This email would be sent using bundle exec ruby main.rb -e -t templates/fitlab.html.erb -c [redacted]

refs

clone

#toki-sona

#Usage

#ERB templates

#A Markdown output in terminal example

#Email example