slack_progress_bar

Slack Progress Bar

Create beautiful progress bars for Slack using emoji!

Slack Progress Bar is a Ruby library capable of generating a progress bar made with Slack emoji. The library can also generate the emoji images that you'll need in your Slack workspace.

⭐ Try it out!

Installation

Add this line to your application's Gemfile:

gem "slack_progress_bar"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install slack_progress_bar

Usage

Configuration

The library uses default colors based on the GitHub Primer color system that allow you to hit the ground running without any in-app configuration.

UPDATE: GitHub Primer's colors have changed since this library was originally written, but we're keeping the default colors for consistency.

Alias	Letter	Hex value	Preview
purple	p	6f42c1ff
blue	b	0366d6ff
green	g	28a745ff
yellow	y	ffd33dff
orange	o	f66a0aff
red	r	d73a49ff
white	w	959da544

You can configure color naming and sequence in a Rails initializer or any other Ruby configuration file:

SlackProgressBar.configure do |config|
  # These one-character color names are used in emoji image filenames.
  # The last color configured here is the default and is used to fill the remainder of a progress bar.
  config.letters = ["r", "g", "b", "w"]

  # Define your own aliases that map to each letter above, useful when generating a progress bar.
  config.aliases = {
    red: "r",
    green: "g",
    blue: "b",
    white: "w",
    deleted: "r",
    created: "g",
    updated: "b",
  }
end

The default emoji prefix is pb. For example, one Slack emoji using the configuration above could be :pb-rgbw:. The separator is - and isn't configurable. You can customize the prefix to prevent naming collisions.

SlackProgressBar.configure do |config|
  # Name emoji like `bar-gggg`.
  config.prefix = "bar"
end

Generating a progress bar

Slack Progress Bar's primary interface for generating a progress bar is the SlackProgressBar.new and SlackProgressBar#.to_s methods. Examples below will assume default configuration.

By default, Slack Progress Bar generates an empty progress bar with 14 emoji and rounded caps:

bar = SlackProgressBar.new
puts bar.to_s

:pb-w-a::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-w-z:

But most folks want to show some, well… progress!

bar = SlackProgressBar.new(counts: { blue: 3, green: 2, red: 1 })
puts bar.to_s

:pb-b-a::pb-bbbb::pb-bbbb::pb-bbbb::pb-bbbb::pb-bbbb::pb-bbbb::pb-gggg::pb-gggg::pb-gggg::pb-gggg::pb-rrrr::pb-rrrr::pb-r-z:

And if you want to indicate that progress is not yet finished:

# Equivalent to: SlackProgressBar.new(counts: { blue: 3, green: 2, red: 1, white: 4 })
bar = SlackProgressBar.new(counts: { blue: 3, green: 2, red: 1 }, total: 10)
puts bar.to_s

:pb-b-a::pb-bbbb::pb-bbbb::pb-bbbb::pb-bbgg::pb-gggg::pb-gggg::pb-rrrr::pb-rwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-w-z:

You can also change the size (in emoji) of the progress bar from its default of 14:

bar = SlackProgressBar.new(counts: { blue: 3, green: 2, red: 1 }, total: 10, size: 10)
puts bar.to_s

:pb-b-a::pb-bbbb::pb-bbbb::pb-bggg::pb-gggg::pb-rrrw::pb-wwww::pb-wwww::pb-wwww::pb-w-z:

Finally, you can choose to generate your progress bar with square caps:

bar = SlackProgressBar.new(counts: { blue: 3, green: 2, red: 1 }, total: 10, size: 10, rounded: false)
puts bar.to_s

:pb-bbbb::pb-bbbb::pb-bbbb::pb-gggg::pb-gggg::pb-rrrr::pb-wwww::pb-wwww::pb-wwww::pb-wwww:

Generating the emoji

⭐ tl;dr: If you want to use the default 7-color configuration, you can download all 232 emoji images (120 KB ZIP).

The observent reader will notice that SlackProgressBar#to_s (above) only generates a string. For Slack to render your beautiful progress bar, you'll need to generate and upload beautiful Slack emoji images! The slack_progress_bar gem comes with a slack_progress_bar command line interface and we'll use the slack_progress_bar generate command to create all the images you'll need.

For the default configuration, run slack_progress_bar generate with no arguments. Images will be created in your current working directory.

bundle exec slack_progress_bar generate

The default configuration generates 232 images, which need to be uploaded to your Slack workspace. As of this writing, there is no API available to automate this manual process! 😅

You can reduce the number of images required by reducing the number of colors in your configuration:

bundle exec slack_progress_bar generate --colors r:d73a49ff g:28a745ff b:0366d6ff w:959da544

The command above, configured for four colors, will generate only 48 images. Use the table below to help determine how many colors you're willing to support:

Colors	Images
2	12
3	25
4	48
5	86
6	145
7	232
8	355

When generating your images, each color you configure contains eight hex digits. The first six are RGB and the last two are alpha transparency.

⭐ You can experiment with different colors and progress bar styles using the Slack Progress Bar sandbox.

Questions

How does it work?

Slack Progress Bar works in two steps. First it performs the one-time process of generating 128px square emoji images. Once those are uploaded to your Slack workspace, it references the names of those emoji to generate beautiful progress bars.

What's the progress bar's granularity?

By default, exactly 2%. That's why the default rounded progress bar size is 14 emoji. Each cap represents a "stripe" and every interior emoji represents four more stripes, for a total of 50 stripes at 2% per stripe. Below is an exploded progress bar to illustrate how the images are combined:

:pb-p-a::pb-bbgg::pb-gyyy::pb-yooo::pb-oooo::pb-orrr::pb-rrrr::pb-rrrr::pb-rwww::pb-wwww::pb-wwww::pb-wwww::pb-wwww::pb-w-z:

                           

Why not use narrow emoji?

When you use a narrow rectangular emoji in Slack, horizontal margins are added so that it takes up the same amount of space as a square emoji. The result is that you can't position multiple narrow emoji right next to each other. That's why Slack Progress Bar uses perfectly square emoji throughout.

Can I animate my progress bar?

Sure! Slack's API gives you the ability to create and update messages. So after you create your initial message with a blank progress bar, you can update that message as frequently as you like with the latest and greatest version of your progress bar.

Can I change the color order?

Sadly, no. 😢 In an effort to reduce the number of images you need to generate and upload, the order in which colors appear is fixed. For Slack Progress Bar to generate 7-color, order-flexible progress bars, it would need to generate 2,423 images rather than 232! 😱

Does it have dark mode?

Sure, kind of! Setting alpha transparency for your color configuration gives you some control over how your progress bars look in light and dark surroundings. For example, the default "white" color is dimmed using alpha transparency. The effect is a progress bar that's beautiful any time of day or night:

I have a different question!

Great! Please feel free to open an issue and I'll do my best to give you an answer. 💛

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/laserlemon/slack_progress_bar. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the SlackProgressBar project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.