trmnl_preview 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a39d955b3dbcc869cde5e0210671a94dfa7af0ea1403fb71c883534d85b6eac
-  data.tar.gz: f0159db40a383ce3149071fd4826bdb9035abab379d442e8a93012a35f6cce30
+  metadata.gz: 51839346d4b2bd24698655d8e6a86a1a93aac73d2882a5b907072db9851ffa03
+  data.tar.gz: 0e54398757e865c8907f3b65b4046519dba2dced17d6d62ce3342b89ce2a5d75
 SHA512:
-  metadata.gz: cccd5ba2af16c057717ae4f0acb6843fad3cd9a7f305109817c5d195f278dd1102c39a20cbf21abbbae0e18395b41ac8e5b314f5c10ae763503cc3e877f1403b
-  data.tar.gz: 19eb007c4d077a3078cde135ca200873f5d050abe167306b878b3f7374e052c282d3cb348e806486ce62fa0d6c0913efb1b4feaf100e213ad16d6e5167426ed9
+  metadata.gz: 2e17bf9dba3a94a153c0182493d7b2ee597ba70b54177793fedae27a154817de8a79eb108a50194b5b5e0f1d2c012ff0b9047b9457cbdf52ad9b5e4d6331c6ab
+  data.tar.gz: a66a9b16b7c3512d018bd10a2444a7cfa4ecf335e9fd580583f27ac4cf6030c810bd48ab20878e3ec704b8f0faf64b7bc6e28ad08e585d1bf51ea3a01d0575fb

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.4.0
+
+### Plugin Migration Strategy
+
+The plugin directory structure has changed to better align with the [plugin archive format](https://help.usetrmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0). 
+
+Here is a migration strategy for existing plugin repositories:
+
+1. Create `.trmnlp.yml` and bring over preview settings from `config.toml` - [see README](README.md)
+2. Rename directory `views/` to `src/`
+3. Create `src/settings.yml` and bring over plugin settings from `config.toml` - [see TRMNL docs](https://help.usetrmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0)
+4. Delete `config.toml`
+
+### Changes
+
+- Change plugin directory structure (see README for details)
+- Add `login`, `push`, and `pull` commands
+- Bring up-to-date with latest private plugin features:
+  - Add `static` strategy
+  - Add polling features: multiple URLs, new verbs, and request body
+  - Add settings `dark_mode`, `no_screen_padding`, `custom_fields`
+  - Add interpolation of custom fields in `polling\_\*` options
+  - Add `{{ trmnl }}` variables 
+- Add `watch` config
+- Add interpolation of environment variables in `.trmnlp.yml` via `{{ env }}`
+- Add auto-reload when `.trmnlp.yml` or `settings.yml` changes
+- Add variable display
+- Fix crash when #poll_data fails (#12)
+- Fix git runtime error in Docker container (#12)
+
+
+
+## 0.3.2
+
+- Add bitmap rendering
+- Add TRMNL's [custom plugin filters](https://help.usetrmnl.com/en/articles/10347358-custom-plugin-filters)
+- Add support for user-supplied custom filters
+
+## 0.3.1
+
+- Add live render
+
 ## 0.3.0
 
 - Add poll button

data/README.md

@@ -1,8 +1,8 @@
-# trmnl_preview
+# trmnlp
 
 A basic self-hosted web server to ease the development and sharing of [TRMNL](https://usetrmnl.com/) plugins.
 
-[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.
+[Liquid](https://shopify.github.io/liquid/) templates are rendered leveraging the [TRMNL Design System](https://usetrmnl.com/framework). They may be generated as HTML (faster, and a good approximation of the final result) or as BMP images (slower, but more accurate).
 
 The server watches the filesystem for changes to the Liquid templates, seamlessly updating the preview without the need to refresh.
 
@@ -10,20 +10,25 @@ The server watches the filesystem for changes to the Liquid templates, seamlessl
 
 ## Creating a Plugin
 
-This is the structure of a plugin repository.
+This is the structure of a plugin project.
 
 ```
-views/
+.trmnlp.yml
+src/
     full.liquid
     half_horizontal.liquid
     half_vertical.liquid
     quadrant.liquid
-config.toml
+    settings.yml
 ```
 
-See [config.example.toml](config.example.toml) for an example config.
+## Syncing Plugin With TRMNL Server
 
-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.
+```sh
+trmnl login      # authenticate with TRMNL account
+trmnl pull [id]  # download (plugin ID required on first pull only)
+trmnl push       # upload
+```
 
 ## Running the Server (Docker)
 
@@ -31,36 +36,65 @@ The [trmnl-hello](https://github.com/schrockwell/trmnl-hello) repository is prov
 docker run \
     -p 4567:4567 \
     -v /path/to/plugin/on/host:/plugin \
-    schrockwell/trmnlp
+    trmnl/trmnlp
 ```
 
 ## Running the Server (Local Ruby)
 
-Ruby 3.x is required. In the plugin repository:
+Prerequisites:
+
+- Ruby 3.x
+- For BMP rendering (optional):
+  - Firefox
+  - ImageMagick
+
+In the plugin project:
 
 ```sh
-bundle add trmnl_preview    # Creates Gemfile and Gemfile.lock
-trmnlp serve                # Starts the server
+gem install trmnl_preview
+trmnlp serve
 ```
 
-## Usage Notes
+## `./.trmnlp.yml` Reference (Project Config)
+
+The `.trmnlp.yml` file lives in the root of the plugin project, and is for configuring the local dev server.
 
-Simply refresh the page to re-render.
+System environment variables are made available in the `{{ env }}` Liquid varible in this file only. This can be used to safely
+supply plugin secrets, like API keys.
 
-When the strategy is "polling", the specified URL will be fetched once, when the server starts.
+All fields are optional.
+
+```yaml
+# {{ env.VARIABLE }} interpolation is available here
+---
+# auto-reload when files change (`watch: false` to disable)
+watch:
+  - src
+  - .trmnlp.yml
+
+# values of custom fields (defined in src/settings.yml)
+custom_fields:
+  station: "{{ env.ICAO }}"
+
+# override variables
+variables:
+  trmnl:
+    user:
+      name: Peter Quill
+    plugin_settings:
+      instance_name: Kevin Bacon Facts
+
+```
 
-When the strategy is "webhook", payloads can be POSTed to the `/webhook` endpoint. They are saved to `tmp/data.json` for future renders.
+## `./src/settings.yml` Reference (Plugin Config)
 
-## `config.toml` Reference
+The `settings.yml` file is part of the plugin definition. 
 
-- `strategy` - Either "polling" or "webhook"
-- `url` - The URL from which to fetch JSON data (polling strategy only)
-- `live_render` - Set to `false` to disable automatic rendering when Liquid templates change (default `true`)
-- `[polling_headers]` - A section of headers to append to the HTTP poll request (polling strategy only)
+See [TRMNL documentation](https://help.usetrmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0) for details on this file's contents.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/schrockwell/trmnl_preview.
+Bug reports and pull requests are welcome on GitHub at https://github.com/usetrmnl/trmnlp.
 
 ## License
 

data/bin/trmnlp

@@ -0,0 +1,14 @@
+#! /usr/bin/env ruby
+
+require "thor"
+
+require_relative '../lib/trmnlp/cli'
+
+begin
+  TRMNLP::CLI.start
+rescue TRMNLP::Error => e
+  puts "Error: #{e.message}"
+  exit 1
+rescue Interrupt
+  exit 1
+end

data/lib/trmnlp/api_client.rb

@@ -0,0 +1,62 @@
+require 'faraday'
+require 'faraday/multipart'
+
+require_relative 'config'
+
+module TRMNLP
+  class APIClient
+    def initialize(config)
+      @config = config
+    end
+
+    def get_plugin_setting_archive(id)
+      response = conn.get("plugin_settings/#{id}/archive")
+
+      if response.status == 200
+        temp_file = Tempfile.new(["plugin_settings_#{id}", '.zip'])
+        temp_file.binmode
+        temp_file.write(response.body)
+        temp_file.rewind
+
+        # return the path to the temp file
+        Pathname.new(temp_file.path)
+      else
+        raise Error, "failed to download plugin settings archive: #{response.status} #{response.body}"
+      end
+    end
+
+    def post_plugin_setting_archive(id, path)
+      payload = {
+        file: Faraday::Multipart::FilePart.new(path, 'application/zip')
+      }
+
+      response = conn.post("plugin_settings/#{id}/archive", payload)
+
+      if response.status == 200
+        true
+      else
+        raise Error, "failed to upload plugin settings archive: #{response.status} #{response.body}"
+      end
+    end
+
+    private
+  
+    attr_reader :config
+  
+    def api_uri = config.app.api_uri
+
+    def conn
+      @conn ||= Faraday.new(url: api_uri, headers:) do |f|
+        f.request :multipart
+      end
+    end
+
+
+    def headers
+      {
+        'Authorization' => "Bearer #{config.app.api_key}",
+        'User-Agent' => "trmnlp/#{VERSION}",
+      }
+    end
+  end
+end

data/lib/trmnlp/app.rb

@@ -0,0 +1,98 @@
+
+require 'faye/websocket'
+require 'sinatra'
+require 'sinatra/base'
+
+require_relative 'context'
+require_relative 'screen_generator'
+
+module TRMNLP
+  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
+
+      @context = settings.context
+
+      @context.poll_data
+
+      @context.start_filewatcher if @context.config.project.live_render?
+
+      @live_reload_clients = []
+      @context.on_view_change do |view, user_data|
+        @live_reload_clients.each do |ws|
+          payload = {
+            'type' => 'reload',
+            'view' => view,
+            'user_data' => user_data
+          }
+
+          ws.send(payload.to_json)
+        end
+      end
+    end
+
+    post '/webhook' do
+      @context.put_webhook(request.body.read)
+      "OK"
+    end
+    
+    get '/' do
+      redirect '/full'
+    end
+
+    get '/data' do
+      content_type :json
+      JSON.pretty_generate(@context.user_data)
+    end
+
+    get '/live_reload' do
+      ws = Faye::WebSocket.new(request.env)
+
+      ws.on(:open) do |event|
+        @live_reload_clients << ws
+      end
+  
+      ws.on(:close) do |event|
+        @live_reload_clients.delete(ws)
+      end
+  
+      ws.rack_response
+    end
+
+    get '/poll' do
+      @context.poll_data
+      redirect back
+    end
+    
+    VIEWS.each do |view|
+      get "/#{view}" do
+        @view = view
+        @user_data = JSON.pretty_generate(@context.user_data)
+        @live_reload = @context.config.project.live_render?
+
+        erb :index
+      end
+
+      get "/render/#{view}.html" do
+        @view = view
+        @screen_classes = @context.screen_classes
+        
+        erb :render_html do
+          @context.render_template(view)
+        end
+      end
+
+      get "/render/#{view}.bmp" do
+        @view = view
+        html = @context.render_full_page(view)
+        generator = ScreenGenerator.new(html, image: true)
+        img_path = generator.process
+        send_file img_path, type: 'image/png', disposition: 'inline'
+      end
+    end
+  end
+end

data/lib/trmnlp/cli.rb

@@ -0,0 +1,51 @@
+require 'thor'
+
+require_relative '../trmnlp'
+require_relative '../trmnlp/commands'
+
+module TRMNLP
+  class CLI < Thor
+    package_name 'trmnlp'
+
+    class_option :dir, type: :string, default: Dir.pwd, aliases: '-d',
+                  desc: 'Plugin directory'
+
+    def self.exit_on_failure? = true
+
+    desc 'build', 'Generate static HTML files'
+    def build
+      Commands::Build.new(options).call
+    end
+
+    desc 'login', 'Authenticate with TRMNL server'
+    def login
+      Commands::Login.new(options).call
+    end
+
+    desc 'pull [id]', 'Download plugin settings from TRMNL server'
+    method_option :force, type: :boolean, default: false, aliases: '-f',
+                  desc: 'Skip confirmation prompts'
+    def pull(plugin_settings_id = nil)
+      Commands::Pull.new(options).call(plugin_settings_id)
+    end
+
+    desc 'push [id]', 'Upload plugin settings to TRMNL server'
+    method_option :force, type: :boolean, default: false, aliases: '-f',
+                  desc: 'Skip confirmation prompts'
+    def push(plugin_settings_id = nil)
+      Commands::Push.new(options).call(plugin_settings_id)
+    end
+
+    desc 'serve', 'Start a local dev server'
+    method_option :bind, type: :string, default: '127.0.0.1', aliases: '-b', desc: 'Bind address'
+    method_option :port, type: :numeric, default: 4567, aliases: '-p', desc: 'Port number'
+    def serve
+      Commands::Serve.new(options).call
+    end
+
+    desc 'version', 'Show version'
+    def version
+      puts VERSION
+    end
+  end
+end

data/lib/trmnlp/commands/base.rb

@@ -0,0 +1,23 @@
+require_relative '../context'
+
+module TRMNLP
+  module Commands
+    class Base
+      def initialize(options)
+        @options = options
+        @context = Context.new(options.dir)
+      end
+
+      def call
+        raise NotImplementedError
+      end
+
+      private
+
+      attr_accessor :options, :context
+
+      def config = context.config
+      def paths = context.paths
+    end
+  end
+end

data/lib/trmnlp/commands/build.rb

@@ -0,0 +1,22 @@
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    class Build < Base
+      def call
+        context = Context.new(options.dir)
+        context.validate!
+        context.poll_data
+        context.paths.create_build_dir
+
+        VIEWS.each do |view|
+          output_path = context.paths.build_dir.join("#{view}.html")
+          puts "Writing #{output_path}..."
+          output_path.write(context.render_full_page(view))
+        end
+  
+        puts "Done!"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/login.rb

@@ -0,0 +1,25 @@
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    class Login < Base
+      def call
+        if config.app.logged_in?
+          anonymous_key = config.app.api_key[0..10] + '*' * (config.app.api_key.length - 11)
+          puts "Currently authenticated as: #{anonymous_key}" 
+        end
+
+        puts "Please visit #{config.app.account_uri} to grab your API key, then paste it here."
+        
+        print "API Key: "
+        api_key = STDIN.gets.chomp
+        raise Error, "API key cannot be empty" if api_key.empty?
+        
+        config.app.api_key = api_key
+        config.app.save
+        
+        puts "Saved changes to #{paths.app_config}"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/pull.rb

@@ -0,0 +1,45 @@
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Pull < Base
+      def call(plugin_settings_id)
+        context.validate!
+        
+        raise Error, "please run `trmnlp login`" unless config.app.logged_in?
+
+        plugin_settings_id ||= config.plugin.id
+        raise Error, 'plugin ID must be specified' if plugin_settings_id.nil?
+
+        unless options.force
+          print "Local plugin files will be overwritten. Are you sure? (y/n) "
+          answer = $stdin.gets.chomp.downcase
+          raise Error, 'aborting' unless answer == 'y' || answer == 'yes'
+        end
+
+        api = APIClient.new(config)
+        temp_path = api.get_plugin_setting_archive(plugin_settings_id)
+        size = 0
+
+        begin
+          Zip::File.open(temp_path) do |zip_file|
+            zip_file.each do |entry|
+              dest_path = paths.src_dir.join(entry.name)
+              dest_path.dirname.mkpath
+              zip_file.extract(entry, dest_path) { true } # overwrite existing
+            end
+          end
+
+          size = File.size(temp_path)
+        ensure
+          temp_path.delete
+        end
+
+        puts "Downloaded plugin (#{size} bytes)"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/push.rb

@@ -0,0 +1,43 @@
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Push < Base
+      def call(plugin_settings_id)
+        context.validate!
+        
+        raise Error, "please run `trmnlp login`" unless config.app.logged_in?
+
+        plugin_settings_id ||= config.plugin.id
+        raise Error, 'plugin ID must be specified' if plugin_settings_id.nil?
+
+        unless options.force
+          print "Plugin settings on the server will be overwritten. Are you sure? (y/n) "
+          answer = $stdin.gets.chomp.downcase
+          raise Error, 'aborting' unless answer == 'y' || answer == 'yes'
+        end
+
+        api = APIClient.new(config)
+        size = 0
+
+        Tempfile.create(binmode: true) do |temp_file|
+          Zip::File.open(temp_file.path, Zip::File::CREATE) do |zip_file|
+            paths.src_files.each do |file|
+              zip_file.add(File.basename(file), file)
+            end
+          end
+        
+          api.post_plugin_setting_archive(plugin_settings_id, temp_file.path)
+
+          size = File.size(temp_file.path)
+        end
+        
+
+        puts "Uploaded plugin (#{size} bytes)"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/serve.rb

@@ -0,0 +1,25 @@
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Serve < Base
+      def call
+        context.validate!
+        
+        # Must come AFTER parsing options
+        require_relative '../app'
+
+        # Now we can configure things
+        App.set(:context, context)
+        App.set(:bind, options.bind)
+        App.set(:port, options.port)
+
+        # Finally, start the app!
+        App.run!
+      end
+    end
+  end
+end

data/lib/trmnlp/commands.rb

@@ -0,0 +1 @@
+Dir[File.join(__dir__, 'commands', '*.rb')].each { |file| require file }

data/lib/trmnlp/config/app.rb

@@ -0,0 +1,39 @@
+require 'yaml'
+
+module TRMNLP
+  class Config
+    # Stores trmnlp-wide configuration (irrespective of the current plugin)
+    class App
+      def initialize(paths)
+        @paths = paths
+        @config = read_config
+      end
+
+      def save
+        paths.app_config_dir.mkpath
+        paths.app_config.write(YAML.dump(@config))
+      end
+
+      def logged_in? = api_key && !api_key.empty?
+      def logged_out? = !logged_in?
+
+      def api_key = @config['api_key']
+
+      def api_key=(key)
+        @config['api_key'] = key
+      end
+
+      def base_uri = URI.parse(@config['base_url'] || 'https://usetrmnl.com')
+
+      def api_uri = URI.join(base_uri, 'api')
+
+      def account_uri = URI.join(base_uri, 'account')
+
+      private
+
+      attr_reader :paths
+
+      def read_config = paths.app_config.exist? ? YAML.safe_load(paths.app_config.read) : {}
+    end
+  end
+end