trmnl_preview 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 683080e96cb1ad78c1e0a1bc0bff5553a2e29547c0324a3df5f609e7cb663dc7
-  data.tar.gz: 38456c612e76196f9261234f2329690f0c5df66840a438eee927da48d588ad56
+  metadata.gz: 3944c7a74517407dbb4ee683c628111668149c622be67a4ba3d69a2655d8b48e
+  data.tar.gz: e6c9d4f7472e4b56d818884ba6ca33307706891da62c40121398036507568fcd
 SHA512:
-  metadata.gz: bb489c533fbca1482f4f76ac8a984b961c2c57be3db296cd6fddc2c515897b3c745f1bd29a333a1592dd60389bfcb1e7fd72c39f7047f42a986a66a5c83e4bdc
-  data.tar.gz: 6f91c8ffeb1ba92ca700da5d677fbb062d64f9338bf75627979f32ba33ebf4a2afaaa8a3072dfd4afea60436798a81bc64dcacb82a51c3bd273005c27e61697c
+  metadata.gz: 1fd0a512a23f1439cc4030543f92272682917d1024ae8ef6eed7449f51d7677add6a0974ed4783b56ad088729ac53a7343e0c00d9026c83d762fb9f825406eb2
+  data.tar.gz: 70c1ba02c0df2d7e427fc079f0bee439fdeea0c120f348d562f734e10f10b210c11db34fbc99c76894afa5622714445efb1fee17fa44029080ba22c216462b1d

data/.ruby-version

@@ -0,0 +1 @@
+3.4.1

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.3.0
+
+- Add poll button
+- Add case image overlays
+- Add `trmnlp build` command
+- Add support for `url` pointing to a local JSON data file
+
+## 0.2.0
+
+- Add "commands" concept to `trmnlp` executable
+- `trmnlp serve` improvements
+  - Add argument for plugin directory
+  - Add options `-b` and `-p` for host bind and port, respectively
+- Add Dockerfile
+
+## 0.1.2
+
+- Initial working release

data/README.md

@@ -1,32 +1,53 @@
 # trmnl_preview
 
-A little self-hosted web server to ease the development and sharing of [TRMNL](https://usetrmnl.com/) plugins.
+A basic self-hosted web server to ease the development and sharing of [TRMNL](https://usetrmnl.com/) plugins.
 
-## Prerequisites
+[Liquid](https://shopify.github.io/liquid/) templates are rendered locally as HTML, leveraging the [TRMNL Design System](https://usetrmnl.com/framework). This server does NOT generate a rendered BMP file. Hence, this is just a _preview_ of the final rendered dashboard.
 
-- Ruby 3.x
+![Screenshot](docs/preview.png)
 
-## Getting Started
+## Creating a Plugin
 
-Clone a fork of https://github.com/schrockwell/trmnl-hello.
+This is the structure of a plugin repository.
 
-Run `bundle`.
+```
+views/
+    full.liquid
+    half_horizontal.liquid
+    half_vertical.liquid
+    quadrant.liquid
+config.toml
+```
 
-Modify `config.toml` (see below for reference).
+See [config.example.toml](config.example.toml) for an example config.
 
-Modify the four view templates in `views/*.liquid`
+The [trmnl-hello](https://github.com/schrockwell/trmnl-hello) repository is provided as a jumping-off point for creating new plugins. Simply fork the repo, clone it, and start hacking.
 
-Run `trmnlp` to start the local web server.
+## Running the Server (Docker)
 
-Browse it locally at http://127.0.0.1:4567/
+```sh
+docker run \
+    -p 4567:4567 \
+    -v /path/to/plugin/on/host:/plugin \
+    schrockwell/trmnlp
+```
+
+## Running the Server (Local Ruby)
+
+Ruby 3.x is required. In the plugin repository:
+
+```sh
+bundle add trmnl_preview    # Creates Gemfile and Gemfile.lock
+trmnlp serve                # Starts the server
+```
 
 ## Usage Notes
 
 Simply refresh the page to re-render.
 
-When the polling strategy is "polling", the specified URL will be fetched once when the server starts.
+When the strategy is "polling", the specified URL will be fetched once, when the server starts.
 
-When the polling strategy is "webhook", you can POST payloads to the `/webhook` endpoint. They are saved to `tmp/data.json` for future renders.
+When the strategy is "webhook", payloads can be POSTed to the `/webhook` endpoint. They are saved to `tmp/data.json` for future renders.
 
 ## `config.toml` Reference
 

data/config.example.toml

@@ -0,0 +1,11 @@
+# strategy = "polling" ==> the data will be fetched once, at server start-up
+# strategy = "webhook" ==> POST new data to /webhook
+strategy = "polling"
+
+# Poll URL (required for polling strategy)
+url = "https://example.com/data.json"
+
+# Polling headers (optional, for polling strategy)
+[polling_headers]
+authorization = "bearer 123"
+content-type = "application/json"

data/exe/trmnlp

@@ -2,4 +2,11 @@
 
 require_relative '../lib/trmnl_preview'
 
-TRMNLPreview::App.run!
+case ARGV[0].to_s.downcase
+when 'serve'
+  require_relative '../lib/trmnl_preview/cmd/serve'
+when 'build'
+  require_relative '../lib/trmnl_preview/cmd/build'
+else
+  require_relative '../lib/trmnl_preview/cmd/usage'
+end

data/lib/trmnl_preview/app.rb

@@ -1,97 +1,54 @@
-require 'json'
-require 'liquid'
-require 'open-uri'
+
 require 'sinatra'
 require 'sinatra/base'
-require 'toml-rb'
-
-require_relative '../trmnl_preview'
-require_relative 'liquid_filters'
-
-class TRMNLPreview::App < Sinatra::Base
-  set :views, File.join(File.dirname(__FILE__), '..', '..', 'views')
-  
-  # Constants
-  VIEWS = %w{full half_horizontal half_vertical quadrant}
-  CONFIG_PATH = File.join(Dir.pwd, 'config.toml')
-  USER_VIEWS_DIR = File.join(Dir.pwd, 'views')
-  TEMP_DIR = File.join(Dir.pwd, 'tmp')
-  DATA_JSON_PATH = File.join(TEMP_DIR, 'data.json')
-
-  unless File.exist?(CONFIG_PATH)
-    puts "No config.toml found in #{Dir.pwd}"
-    exit 1
-  end
-
-  unless Dir.exist?(USER_VIEWS_DIR)
-    puts "No views found at #{USER_VIEWS_DIR}"
-    exit 1
-  end
 
-  FileUtils.mkdir_p(TEMP_DIR)
-
-  config = TomlRB.load_file(CONFIG_PATH)
-  strategy = config['strategy']
-
-  unless ['polling', 'webhook'].include?(strategy)
-    puts "Invalid strategy: #{strategy} (must be 'polling' or 'webhook')"
-    exit 1
-  end
-
-  url = config['url']
-  polling_headers = config['polling_headers'] || {}
+require_relative 'context'
+
+module TRMNLPreview
+  class App < Sinatra::Base
+    # Sinatra settings
+    set :views, File.join(File.dirname(__FILE__), '..', '..', 'web', 'views')
+    set :public_folder, File.join(File.dirname(__FILE__), '..', '..', 'web', 'public')
+    
+    def initialize(*args)
+      super
+
+      begin
+        @context = Context.new(settings.user_dir)
+      rescue StandardError => e
+        puts e.message
+        exit 1
+      end
 
-  if strategy == 'polling'
-    if url.nil?
-      puts "URL is required for polling strategy"
-      exit 1
+      @context.poll_data if @context.strategy == 'polling'
     end
 
-    print "Fetching #{url}... "
-    payload = URI.open(url, polling_headers).read
-    File.write(DATA_JSON_PATH, payload)
-    puts "got #{payload.size} bytes"
-  end
-
-  environment = Liquid::Environment.build do |env|
-    env.register_filter(TRMNLPreview::LiquidFilters)
-  end
-
-  get '/' do
-    redirect '/full'
-  end
-
-  if config['strategy'] == 'webhook'
     post '/webhook' do
-      body = request.body.read
-      File.write(DATA_JSON_PATH, body)
+      @context.set_data(request.body.read)
       "OK"
     end
+    
+    get '/' do
+      redirect '/full'
+    end
 
-    puts "Listening for POSTs to /webhook"
-  end
-
-  VIEWS.each do |view|
-    get "/render/#{view}" do
-      path = File.join(USER_VIEWS_DIR, "#{view}.liquid")
-      unless File.exist?(path)
-        halt 404, "Plugin template not found: views/#{view}.liquid"
+    get '/poll' do
+      @context.poll_data
+      redirect back
+    end
+    
+    VIEWS.each do |view|
+      get "/#{view}" do
+        @view = view
+        erb :index
       end
 
-      user_template = Liquid::Template.parse(File.read(path), environment: environment)
-
-      @view = view
-      erb :render_view do
-        data = JSON.parse(File.read(DATA_JSON_PATH))
-        data = { data: data } if data.is_a?(Array) # per TRMNL docs, bare array is wrapped in 'data' key
-
-        user_template.render(data)
+      get "/render/#{view}" do
+        @view = view
+        erb :render_view do
+          @context.render_template(view)
+        end
       end
     end
-
-    get "/#{view}" do
-      @view = view
-      erb :index
-    end
   end
 end

data/lib/trmnl_preview/cmd/build.rb

@@ -0,0 +1,25 @@
+require 'optionparser'
+
+require_relative '../context'
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: trmnlp build [directory]"
+end.parse!
+
+root = ARGV[1] || Dir.pwd
+begin
+  context = TRMNLPreview::Context.new(root)
+rescue StandardError => e
+  puts e.message
+  exit 1
+end
+
+context.poll_data
+
+TRMNLPreview::VIEWS.each do |view|
+  output_path = File.join(context.temp_dir, "#{view}.html")
+  puts "Creating #{output_path}..."
+  File.write(output_path, context.render_full_page(view))
+end
+
+puts "Done!"

data/lib/trmnl_preview/cmd/serve.rb

@@ -0,0 +1,31 @@
+require 'optionparser'
+
+options = {
+  bind: '127.0.0.1',
+  port: 4567
+}
+
+# Parse options BEFORE requiring the Sinatra app, since it has its own option-parsing behavior.
+# This will remove the option items from ARGV, which is what we want.
+OptionParser.new do |opts|
+  opts.banner = "Usage: trmnlp serve [directory] [options]"
+
+  opts.on("-b", "--bind [HOST]", "Bind to host address (default: 127.0.0.1)") do |host|
+    options[:bind] = host
+  end
+
+  opts.on("-p", "--port [PORT]", "Use port (default: 4567)") do |port|
+    options[:port] = port
+  end
+end.parse!
+
+# Must come AFTER parsing options
+require_relative '../app'
+
+# Now we can configure things
+TRMNLPreview::App.set(:user_dir, ARGV[1] || Dir.pwd)
+TRMNLPreview::App.set(:bind, options[:bind])
+TRMNLPreview::App.set(:port, options[:port])
+
+# Finally, start the app!
+TRMNLPreview::App.run!

data/lib/trmnl_preview/cmd/usage.rb

@@ -0,0 +1,10 @@
+puts <<-USAGE
+Usage:
+
+  trmnlp [command] [options]
+
+Commands (-h for command-specific help):
+
+  serve     Start the TRMNL Preview server
+  build     Generate static HTML files
+USAGE

data/lib/trmnl_preview/context.rb

@@ -0,0 +1,102 @@
+require 'erb'
+require 'fileutils'
+require 'json'
+require 'liquid'
+require 'open-uri'
+require 'toml-rb'
+
+require_relative 'liquid_filters'
+
+module TRMNLPreview
+  class Context
+    attr_reader :strategy, :temp_dir
+    
+    def initialize(root)
+      config_path = File.join(root, 'config.toml')
+      @user_views_dir = File.join(root, 'views')
+      @temp_dir = File.join(root, 'tmp')
+      @data_json_path = File.join(@temp_dir, 'data.json')
+    
+      @liquid_environment = Liquid::Environment.build do |env|
+        env.register_filter(LiquidFilters)
+      end
+
+      unless File.exist?(config_path)
+        raise "No config.toml found in #{root}"
+      end
+    
+      unless Dir.exist?(@user_views_dir)
+        raise "No views found at #{@user_views_dir}"
+      end
+
+      config = TomlRB.load_file(config_path)
+      @strategy = config['strategy']
+      @url = config['url']
+      @polling_headers = config['polling_headers'] || {}
+
+      unless ['polling', 'webhook'].include?(@strategy)
+        raise "Invalid strategy: #{strategy} (must be 'polling' or 'webhook')"
+      end
+
+      FileUtils.mkdir_p(@temp_dir)
+    end
+
+    def user_data
+      data = JSON.parse(File.read(@data_json_path))
+      data = { data: data } if data.is_a?(Array) # per TRMNL docs, bare array is wrapped in 'data' key
+      data
+    end
+
+    def poll_data
+      if @url.nil?
+        raise "URL is required for polling strategy"
+      end
+
+      print "Fetching #{@url}... "
+
+      if @url.match?(/^https?:\/\//)
+        payload = URI.open(@url, @polling_headers).read
+      else
+        payload = File.read(@url)
+      end
+
+      File.write(@data_json_path, payload)
+      puts "got #{payload.size} bytes"
+
+      user_data
+    end
+
+    def set_data(payload)
+      File.write(@data_json_path, payload)
+    end
+
+    def view_path(view)
+      File.join(@user_views_dir, "#{view}.liquid")
+    end
+
+    def render_template(view)
+      path = view_path(view)
+      unless File.exist?(path)
+        return "Missing plugin template: views/#{view}.liquid"
+      end
+
+      user_template = Liquid::Template.parse(File.read(path), environment: @liquid_environment)
+      user_template.render(user_data)
+    end
+
+    def render_full_page(view)
+      page_erb_template = File.read(File.join(__dir__, '..', '..', 'web', 'views', 'render_view.erb'))
+      
+      ERB.new(page_erb_template).result(ERBBinding.new(view).get_binding do
+        render_template(view)
+      end)
+    end
+
+    private 
+
+    class ERBBinding
+      def initialize(view) = @view = view
+      def get_binding = binding
+    end
+  end
+end

data/lib/trmnl_preview/liquid_filters.rb

@@ -1,6 +1,8 @@
-module TRMNLPreview::LiquidFilters
-  def number_with_delimiter(number)
-    # TODO: Replace with ActiveSupport's number_with_delimiter
-    number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+module TRMNLPreview
+  module LiquidFilters
+    def number_with_delimiter(number)
+      # TODO: Replace with ActiveSupport's number_with_delimiter
+      number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
   end
 end

data/lib/trmnl_preview/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLPreview
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/trmnl_preview.rb

@@ -2,11 +2,9 @@
 
 module TRMNLPreview; end
 
-require_relative "trmnl_preview/app"
-require_relative "trmnl_preview/liquid_filters"
+require_relative "trmnl_preview/context"
 require_relative "trmnl_preview/version"
 
 module TRMNLPreview
-  class Error < StandardError; end
-  # Your code goes here...
-end
+  VIEWS = %w{full half_horizontal half_vertical quadrant}
+end

data/trmnl_preview.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile Dockerfile])
     end
   end
   spec.bindir = "exe"

data/web/views/index.erb

@@ -0,0 +1,113 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>TRMNL Preview</title>
+    <style>
+        body {
+            font-family: sans-serif;
+            margin: 10px;
+        }
+        main {
+            display: flex;
+            flex-direction: column;
+            width: fit-content;
+        }
+        menu {
+            padding: 0;
+            margin: 0;
+            display: flex;
+            justify-content: space-between;
+        }
+        menu a {
+            padding: 0.5em 1em;
+            background: #ddd;
+            border-radius: 0.5em;
+            display: inline-block;
+            text-decoration: none;
+            color: black;
+        }
+        menu a:hover {
+            background: #ccc;
+        }
+        menu a.active {
+            background: #333;
+            color: white;
+        }
+        .case {
+            width: 1000px;
+            height: 680px;
+            position: relative;
+        }
+        iframe {
+            position: absolute;
+            border: none;
+            left: 98px;
+            top: 65px;
+            filter: grayscale(100%);
+        }
+        .case .case-overlay {
+            position: absolute;
+            width: 100%;
+            height: 100%;
+            top: 0;
+            left: 0;
+            background-size: cover;
+            mix-blend-mode: multiply;
+            pointer-events: none;
+        }
+        .case--none .case-overlay { background: none; }
+        .case--white .case-overlay { background-image: url('white-case.jpg') }
+        .case--black .case-overlay { background-image: url('black-case.jpg') }
+        .case--clear .case-overlay { background-image: url('clear-case.jpg') }
+        .case--none iframe {
+            border: 1px solid black;
+        }
+    </style>
+    <script>
+        function updateCase() {
+            const value = document.querySelector('.select-case').value;
+            document.querySelector('.case').className = `case case--${value}`;
+            localStorage.setItem('trmnlp-case', value);
+        }
+
+        document.addEventListener('DOMContentLoaded', () => {
+            const caseValue = localStorage.getItem('trmnlp-case') || 'black';
+
+            const select = document.querySelector('.select-case');
+            select.value = caseValue;
+            select.addEventListener('change', () => { updateCase() });
+            
+            updateCase();
+        });
+    </script>
+</head>
+<body>
+    <main>
+        <menu>
+            <div>
+                <a class="<%= 'active' if @view == 'full' %>" href="/full">Full</a>
+                <a class="<%= 'active' if @view == 'half_horizontal' %>" href="/half_horizontal">Half Horizontal</a>
+                <a class="<%= 'active' if @view == 'half_vertical' %>" href="/half_vertical">Half Vertical</a>
+                <a class="<%= 'active' if @view == 'quadrant' %>" href="/quadrant">Quadrant</a>
+            </div>
+            <div>
+                <select class="select-case">
+                    <option value="none">None</option>
+                    <option value="white">White</option>
+                    <option value="black" selected>Black</option>
+                    <option value="clear">Clear</option>
+                </select>
+
+                <a href="/poll">Poll</a>
+            </div>
+        </menu>
+
+        <div class="case case--black">
+            <iframe src="/render/<%= @view %>" width="800" height="480"></iframe>
+            <div class="case-overlay"></div>
+        </div>
+    </main>
+</body>
+</html>

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Rockwell Schrock
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-01-05 00:00:00.000000000 Z
+date: 2025-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -88,18 +87,27 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ruby-version"
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
+- config.example.toml
+- docs/preview.png
 - exe/trmnlp
 - lib/trmnl_preview.rb
 - lib/trmnl_preview/app.rb
+- lib/trmnl_preview/cmd/build.rb
+- lib/trmnl_preview/cmd/serve.rb
+- lib/trmnl_preview/cmd/usage.rb
+- lib/trmnl_preview/context.rb
 - lib/trmnl_preview/liquid_filters.rb
 - lib/trmnl_preview/version.rb
-- sig/trmnl_preview.rbs
 - trmnl_preview.gemspec
-- views/index.erb
-- views/render_view.erb
+- web/public/black-case.jpg
+- web/public/clear-case.jpg
+- web/public/white-case.jpg
+- web/views/index.erb
+- web/views/render_view.erb
 homepage: https://github.com/schrockwell/trmnl_preview
 licenses:
 - MIT
@@ -107,7 +115,6 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/schrockwell/trmnl_preview
   source_code_uri: https://github.com/schrockwell/trmnl_preview
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -122,8 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Local web server to preview TRMNL plugins
 test_files: []

data/Rakefile

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-task default: %i[]

data/sig/trmnl_preview.rbs

@@ -1,4 +0,0 @@
-module TRMNLPreview
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end

data/views/index.erb

@@ -1,42 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>TRMNL Preview</title>
-    <style>
-        body {
-            font-family: sans-serif;
-            background: #eee;
-        }
-        .menu {
-            margin-bottom: 1em;
-        }
-        .menu a {
-            padding: 0.5em 1em;
-            background: #ddd;
-            border-radius: 0.5em;
-            display: inline-block;
-            text-decoration: none;
-            color: black;
-        }
-        .menu a:hover {
-            background: #ccc;
-        }
-        .menu a.active {
-            background: #333;
-            color: white;
-        }
-    </style>
-</head>
-<body>
-    <div class="menu">
-        <a class="<%= 'active' if @view == 'full' %>" href="/full">Full</a>
-        <a class="<%= 'active' if @view == 'half_horizontal' %>" href="/half_horizontal">Half Horizontal</a>
-        <a class="<%= 'active' if @view == 'half_vertical' %>" href="/half_vertical">Half Vertical</a>
-        <a class="<%= 'active' if @view == 'quadrant' %>" href="/quadrant">Quadrant</a>
-    </div>
-
-    <iframe src="/render/<%= @view %>" width="800" height="480"></iframe>
-</body>
-</html>