trmnl_preview 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 683080e96cb1ad78c1e0a1bc0bff5553a2e29547c0324a3df5f609e7cb663dc7
-  data.tar.gz: 38456c612e76196f9261234f2329690f0c5df66840a438eee927da48d588ad56
+  metadata.gz: 1d511eb133cb9ee46d6d343f9ed1bef3c11c3e581ae193310d2d6f50d900c4a4
+  data.tar.gz: ed60374a348285201cd0f49396cd2995c5b87301866aec421cd3c21131c6fe98
 SHA512:
-  metadata.gz: bb489c533fbca1482f4f76ac8a984b961c2c57be3db296cd6fddc2c515897b3c745f1bd29a333a1592dd60389bfcb1e7fd72c39f7047f42a986a66a5c83e4bdc
-  data.tar.gz: 6f91c8ffeb1ba92ca700da5d677fbb062d64f9338bf75627979f32ba33ebf4a2afaaa8a3072dfd4afea60436798a81bc64dcacb82a51c3bd273005c27e61697c
+  metadata.gz: 063e9d97310fdc7c20609e83573006e18df1a081455d8d60d1694fbbc21a43c82c99290395b54e0b815d498884ebf69f984f4d153c3d50131c34b090c6752749
+  data.tar.gz: c44116ac437e7636c403481d6b5b773a5f0d0ccf425b6e2181bc987d272056bef407ce43919d967fa86da80b96b032534d423b43dd60ef71d56c96ec22e4b9ab

data/.ruby-version

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

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 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,9 @@
 
 require_relative '../lib/trmnl_preview'
 
-TRMNLPreview::App.run!
+case ARGV[0].to_s.downcase
+when 'serve'
+  require_relative '../lib/trmnl_preview/cmd/serve'
+else
+  require_relative '../lib/trmnl_preview/cmd/usage'
+end

data/lib/trmnl_preview/app.rb

@@ -5,93 +5,94 @@ 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)
+  # Sinatra settings
+  set :views, File.join(File.dirname(__FILE__), '..', '..', 'views')
+  
+  def initialize(*args)
+    super
 
-  config = TomlRB.load_file(CONFIG_PATH)
-  strategy = config['strategy']
+    @config_path = File.join(settings.user_dir, 'config.toml')
+    @user_views_dir = File.join(settings.user_dir, 'views')
+    @temp_dir = File.join(settings.user_dir, 'tmp')
+    @data_json_path = File.join(@temp_dir, 'data.json')
 
-  unless ['polling', 'webhook'].include?(strategy)
-    puts "Invalid strategy: #{strategy} (must be 'polling' or 'webhook')"
-    exit 1
-  end
+    unless File.exist?(@config_path)
+      puts "No config.toml found in #{settings.user_dir}"
+      exit 1
+    end
+  
+    unless Dir.exist?(@user_views_dir)
+      puts "No views found at #{@user_views_dir}"
+      exit 1
+    end
 
-  url = config['url']
-  polling_headers = config['polling_headers'] || {}
+    FileUtils.mkdir_p(@temp_dir)
 
-  if strategy == 'polling'
-    if url.nil?
-      puts "URL is required for polling strategy"
+    @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
-
-    print "Fetching #{url}... "
-    payload = URI.open(url, polling_headers).read
-    File.write(DATA_JSON_PATH, payload)
-    puts "got #{payload.size} bytes"
+  
+    url = @config['url']
+    polling_headers = @config['polling_headers'] || {}
+  
+    if strategy == 'polling'
+      if url.nil?
+        puts "URL is required for polling strategy"
+        exit 1
+      end
+  
+      print "Fetching #{url}... "
+      payload = URI.open(url, polling_headers).read
+      File.write(@data_json_path, payload)
+      puts "got #{payload.size} bytes"
+    end
+  
+    @liquid_environment = Liquid::Environment.build do |env|
+      env.register_filter(TRMNLPreview::LiquidFilters)
+    end
   end
 
-  environment = Liquid::Environment.build do |env|
-    env.register_filter(TRMNLPreview::LiquidFilters)
+  post '/webhook' do
+    body = request.body.read
+    File.write(@data_json_path, body)
+    "OK"
   end
-
+  
   get '/' do
     redirect '/full'
   end
-
-  if config['strategy'] == 'webhook'
-    post '/webhook' do
-      body = request.body.read
-      File.write(DATA_JSON_PATH, body)
-      "OK"
+  
+  VIEWS.each do |view|
+    get "/#{view}" do
+      @view = view
+      erb :index
     end
 
-    puts "Listening for POSTs to /webhook"
-  end
-
-  VIEWS.each do |view|
     get "/render/#{view}" do
-      path = File.join(USER_VIEWS_DIR, "#{view}.liquid")
+      path = File.join(@user_views_dir, "#{view}.liquid")
       unless File.exist?(path)
         halt 404, "Plugin template not found: views/#{view}.liquid"
       end
 
-      user_template = Liquid::Template.parse(File.read(path), environment: environment)
+      user_template = Liquid::Template.parse(File.read(path), environment: @liquid_environment)
 
       @view = view
       erb :render_view do
-        data = JSON.parse(File.read(DATA_JSON_PATH))
+        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)
       end
     end
-
-    get "/#{view}" do
-      @view = view
-      erb :index
-    end
   end
 end

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,9 @@
+puts <<-USAGE
+Usage:
+
+  trmnlp [command] [options]
+
+Commands (-h for command-specific help):
+
+  serve     Start the TRMNL Preview server
+USAGE

data/lib/trmnl_preview/version.rb

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

data/lib/trmnl_preview.rb

@@ -2,8 +2,7 @@
 
 module TRMNLPreview; end
 
-require_relative "trmnl_preview/app"
-require_relative "trmnl_preview/liquid_filters"
+# require_relative "trmnl_preview/app"
 require_relative "trmnl_preview/version"
 
 module TRMNLPreview

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"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.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,15 +87,19 @@ 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/serve.rb
+- lib/trmnl_preview/cmd/usage.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
@@ -107,7 +110,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 +124,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