cmu-web-placemellon 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e524c128624c27b1e5805e14478ac22e7a8befb682d9a26b0565d5497819f71
+  data.tar.gz: 447af951970cf67d4791c04fb3b92985029107cc2e7b081eba86387d778ec388
+SHA512:
+  metadata.gz: 13e354c272df2e3ecd6a15443a1995cd7e177686c21b5c0cc1102aea482f15011fba2337ea3e14934c75e3a5ef7f6f1b0764ca930cee4c1465a69d0c9f13c598
+  data.tar.gz: 104cb80e4b703698ffd7197b88d5650eb4de5d6c2b51c115a5da8ce8d76849a424bfad86923212d7a997947c84e58e6af17759f24ebcdd0f48d191c68ebaeea6

data/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Carnegie Mellon University
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,79 @@
+# PlaceMellon for Ruby and Rails
+
+Placeholder images from [PlaceMellon](https://placemellon.andrew.cmu.edu/)
+in Ruby code and Rails views: campus photos, Scotty, profile pictures, bio
+placeholders and solid CMU colors, at any size. The gem only builds image
+addresses. It never calls PlaceMellon itself, so it adds nothing to your
+app's requests or tests.
+
+The gem lives in the PlaceMellon repository's `packages/ruby/`. Each
+PlaceMellon release publishes it at the same version.
+
+## Install
+
+Add it to your `Gemfile`, usually in the development group:
+
+```ruby
+gem 'cmu-web-placemellon', '~> 1.3'
+```
+
+## In Rails Views
+
+Rails views get `placemellon_tag`. It takes a width, an optional height
+(leave it out for a square), alt text and PlaceMellon's options; anything
+else goes to `image_tag`:
+
+```erb
+<%= placemellon_tag 400, 300, alt: 'A campus photo', category: :campus %>
+<%= placemellon_tag 96, alt: 'Scotty', scotty: true, format: :png, class: 'avatar' %>
+<%= placemellon_tag 640, 360, alt: 'A placeholder', solid: true, text: true, color: 'carnegie-red' %>
+```
+
+Alt text is required.
+
+## In Ruby
+
+```ruby
+require 'cmu-web-placemellon'
+
+PlaceMellon.url(400, 300)                      # a photo
+PlaceMellon.url(400, 300, category: :labs)     # from one category
+PlaceMellon.url(400, 300, random: true)        # a different photo each time
+PlaceMellon.url(400, 300, format: :webp)       # a smaller WebP photo
+PlaceMellon.url(120, profile: true)            # a default profile picture
+```
+
+## Options
+
+| Option          | Gives                                                               |
+| --------------- | ------------------------------------------------------------------- |
+| `category:`     | Photos from one category: `campus`, `classrooms`, `labs` or `life`  |
+| `random: true`  | A different photo on each request                                   |
+| `gray: true`    | A grayscale photo                                                   |
+| `scotty: true`  | Scotty instead of a photo; add `gradient: true` for a gray gradient |
+| `profile: true` | A default profile picture                                           |
+| `bio: true`     | A bio placeholder                                                   |
+| `solid: true`   | A solid color; add `color:` (a CMU brand color) and `text: true`    |
+| `format:`       | `:jpg` or `:webp` for photos, `:svg` or `:png` for the others       |
+
+Sizes are whole numbers from 1 to 2048. The gem checks sizes, option names
+and formats; PlaceMellon checks the rest and explains any address it can't
+draw. [PlaceMellon's site](https://placemellon.andrew.cmu.edu/) lists every
+category and color.
+
+To point at a local copy of PlaceMellon, set the host once:
+
+```ruby
+PlaceMellon.host = 'http://127.0.0.1:3000'
+```
+
+## Work on the Gem
+
+```bash
+cd packages/ruby
+bundle install
+bundle exec rake test build
+```
+
+`rake version` copies the app's license and its version from
+`package.json` into the gem; `rake clean` removes them and the build.

data/VERSION

@@ -0,0 +1 @@
+2.0.0

data/lib/cmu-web-placemellon.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'place_mellon'

data/lib/place_mellon/helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PlaceMellon
+  # A view helper for Rails, included in every view by the Railtie
+  module Helper
+    # <%= placemellon_tag 400, 300, alt: 'Campus', category: :campus %>
+    # Takes PlaceMellon's options, and image_tag's for everything else.
+    # Alt text is required.
+    def placemellon_tag(width, height = nil, alt:, **options)
+      image = options.slice(:format, *VALUES, *FLAGS)
+      html = options.except(*image.keys)
+      image_tag(PlaceMellon.url(width, height, **image), alt: alt, width: width, height: height || width, **html)
+    end
+  end
+end

data/lib/place_mellon/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module PlaceMellon
+  # Makes placemellon_tag available in Rails views
+  class Railtie < ::Rails::Railtie
+    initializer 'place_mellon.helper' do
+      ActiveSupport.on_load(:action_view) { include PlaceMellon::Helper }
+    end
+  end
+end

data/lib/place_mellon/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PlaceMellon
+  GEM_ROOT = File.expand_path('../..', __dir__)
+  # A built gem carries a VERSION file (rake version); a checkout reads the
+  # app's package.json, so the gem and the app share one version
+  VERSION = if File.file?(File.join(GEM_ROOT, 'VERSION'))
+              File.read(File.join(GEM_ROOT, 'VERSION')).strip
+            else
+              JSON.parse(File.read(File.expand_path('../../package.json', GEM_ROOT))).fetch('version')
+            end.freeze
+end

data/lib/place_mellon.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative 'place_mellon/version'
+
+# Addresses for PlaceMellon's placeholder images
+# (https://placemellon.andrew.cmu.edu/). Only builds URLs; it never calls the
+# service, which checks the options itself.
+module PlaceMellon
+  # The largest width or height the service draws
+  MAX = 2048
+  # Options with a value: a photo category, or a solid color
+  VALUES = %i[category color].freeze
+  # Options that are on or off
+  FLAGS = %i[random scotty profile bio solid text gradient gray].freeze
+  FORMATS = %i[jpg webp svg png].freeze
+
+  class << self
+    # The service the addresses point to; set it for a local copy
+    attr_writer :host
+
+    def host
+      @host || 'https://placemellon.andrew.cmu.edu'
+    end
+
+    # PlaceMellon.url(400, 300, category: :campus)
+    # PlaceMellon.url(96, scotty: true, format: :png)
+    # A height left out makes a square.
+    def url(width, height = nil, format: nil, **options)
+      sizes = [width, height].compact.map { |size| check_size(size) }
+      unknown = options.keys - VALUES - FLAGS
+      raise ArgumentError, "Unknown PlaceMellon option: #{unknown.first}" if unknown.any?
+      if format && !FORMATS.include?(format.to_sym)
+        raise ArgumentError, "PlaceMellon format must be one of #{FORMATS.join(', ')}"
+      end
+
+      sizes[-1] = "#{sizes[-1]}.#{format}" if format
+      query = options.filter_map do |key, value|
+        if VALUES.include?(key)
+          "#{key}=#{URI.encode_www_form_component(value.to_s)}" unless value.nil?
+        elsif value
+          key.to_s
+        end
+      end
+      "#{host.chomp('/')}/#{sizes.join('/')}#{"?#{query.join('&')}" if query.any?}"
+    end
+
+    private
+
+    def check_size(size)
+      return size if size.is_a?(Integer) && size.between?(1, MAX)
+
+      raise ArgumentError, "PlaceMellon sizes are whole numbers from 1 to #{MAX}, not #{size.inspect}"
+    end
+  end
+end
+
+require_relative 'place_mellon/helper'
+require_relative 'place_mellon/railtie' if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: cmu-web-placemellon
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Carnegie Mellon University
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Builds addresses for PlaceMellon, the Carnegie Mellon placeholder image
+  service: campus photos, Scotty, profile pictures and solid colors at any size. Includes
+  a Rails view helper.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- VERSION
+- lib/cmu-web-placemellon.rb
+- lib/place_mellon.rb
+- lib/place_mellon/helper.rb
+- lib/place_mellon/railtie.rb
+- lib/place_mellon/version.rb
+homepage: https://placemellon.andrew.cmu.edu/
+licenses:
+- BSD-3-Clause
+metadata:
+  source_code_uri: https://github.com/cmu-web/cmu-web-placemellon
+  documentation_uri: https://github.com/cmu-web/cmu-web-placemellon/tree/main/packages/ruby#readme
+  bug_tracker_uri: https://github.com/cmu-web/cmu-web-placemellon/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Placeholder image addresses from PlaceMellon, for Ruby and Rails
+test_files: []