How are you using Phlex? Structure, etc?

[evenreven]

Sorry in advance for a long post... The last few days, I've been refactoring the public-facing part of a hobby project to use Phlex, and I love it! Since the documentation has few real-world examples - understandable, for such a new gem! - I thought I'd share parts of my structure here. Maybe I've had a good idea you didn't consider, or maybe you can tell me how I can improve my code - sharing is good anyway!

I have a StudyProgramme model that has_many :photos, through: :photo_combinations. Photo is the other way, and PhotoCombination belongs_to both. Standard stuff. I do it like this because I have a caption field on the PhotoCombination since captions depend on context and thus can’t be set on the photo model itself. I often have four or five photos per StudyProgramme, the top photo I use as featured image, and the rest goes in a slide show below the text. My backend view is still an erb _form with nested forms with a Cocoon-based Photo chooser with a caption on the PhotoCombination model. Messy (and irrelevant, since we're talking about Phlex), so I won’t bore you with it.

After I refactored the view and deleted study_programmes/show.html.erb, I have this in my controller:

class StudyProgrammeController < ApplicationController
  def show
    @study_programme = StudyProgramme.find(params[:id])
    images = @study_programme.photo_combinations.includes([:photo])
    top_image = images.first
    page_images = images.where.not(id: first_image&.id)
    render Views::Templates::ProgrammePage.new(model: @study_programme, top_image:, page_images:)
  end
  # index etc not relevant here
  # permitted params etc
end

This is my study programme view (I put it under a "templates" namespace, but it could easily be called page or whatever):

module Views
  module Templates
    class ProgrammePage < ApplicationView
      def initialize(model:, top_image:, page_images:)
        @model = model
        @top_image = top_image
        @page_images = page_images
        @title = model.programme_title
        @description = model.programme_description # HTML from the db
      end

      def template
        render Layout.new(title: @title) do
          # Title
          h1 { @title }

          # Top image
          render Views::Components::TopImage.new(model: @top_image, width: 800, height: 600, use_caption: true, lazy: false)

          # Body text
          render Views::Components::Body.new(heading: "Short description of #{@title}", text: @description)

          # Lightbox
          render Views::Components::Lightbox.new(collection: @page_images)
        end
      end
    end
  end
end

As you can see it renders three more views, in addition to a layout. This is my layout.

module Views
  class Layout < ApplicationView
    include Phlex::Rails::Layout

    def initialize(title:)
      @title = title
    end

    def template(&)
      doctype

      html do
        head do
          meta charset: "utf-8"
          csp_meta_tag
          csrf_meta_tags
          meta name: "viewport", content: "width=device-width,initial-scale=1"
          title { @title }
          javascript_tag(entrypoint: "application")
          vite_client_tag
        end

        body do
          main(&)
        end
      end
    end

    private

    def javascript_tag(entrypoint:)
      raw helpers.vite_javascript_tag entrypoint # rubocop:disable Rails/OutputSafety
    end

    def vite_client_tag
      raw helpers.vite_client_tag # rubocop:disable Rails/OutputSafety
    end
  end
end

The last two methods are only because I’m using vite_rails for assets, but if you use Webpacker, the logic would be similar. (Vite outputs the stylesheet tag automatically if you import it in the javascript entrypoint, that’s why there’s no styles here.)

Next, we’re rendering the top image:

module Views
  module Components
    class TopImage < ApplicationView
      def initialize(model:, width:, height: nil, use_caption: true, lazy: true)
        @image = model
        @width = width
        @height = height
        @use_caption = use_caption
        @caption = model.caption
        @lazy = lazy
      end

      def template
        figure(class: "top-image", style: "--image-ar: #{image_ar};") do
          picture_el
          figcaption_el
        end
      end

      private

      def lazy?
        @lazy
      end

      def use_caption?
        @use_caption
      end

      def picture_el
        picture do
          source(srcset: "#{small.url} #{@width / 2}w, #{large.url} #{@width}w", type: "image/webp")
          img(src: large_jpg.url, loading: lazy_attrib, title: image_title, alt: image_alt)
        end
      end

      def lazy_attrib
        lazy? ? "lazy" : "eager"
      end

      def figcaption_el
        figcaption { @caption } if @caption.present? && use_caption?
      end

      def image_processor(width:, imgformat:, quality:, height: nil)
        image = @image.photo.image
        geometry = @height.present? ? "#{width}x#{height}#" : "#{width}x"
        image.thumb(geometry, format: imgformat).encode(imgformat, "-quality #{quality}")
      end

      def large_jpg
        image_processor(width: @width, height: @height, imgformat: "jpeg", quality: "90")
      end

      def large
        image_processor(width: @width, height: @height, imgformat: "webp", quality: "90")
      end

      def small
        width = @width / 2
        height = @height.present? ? (@height / 2) : nil
        image_processor(width:, height:, imgformat: "webp", quality: "85")
      end

      def image_ar
        # NOTE: photo.image.height is technically a Dragonfly method, but will try the database field image_width first
        # That way, if it's saved, the app won't use magick inspect, only the db.
        # If the field doesn't exist, dragonfly will calculate it on the fly.
        @height.present? ? "#{@width} / #{@height}" : "#{@image.photo.image.width} / #{@image.photo.image.height}"
      end

      def image_alt
        @image.photo.alt.presence || @caption
      end

      def image_title
        @caption.presence || @image.photo.title
      end
    end
  end
end

This has a few pieces of Dragonfly-specific logic, so feel free to disregard that. Basically, the complexity is because I wanted to have one featured image component for several use cases. This component resizes and crops (with center gravity) if you pass width + height to render, but only resizes if you pass only width. I use lazy: false on the top image here, because it’s a good practice to not use loading="lazy" on above-the-fold images. Both caption, lazyloading and cropping are optional based on the render arguments. Markup: I use two webp sizes in a picture element, with an img/jpg fallback, as suggested by Andrea Verlicchi here. The inline style is for setting aspect ratio CSS dynamically. I think this is a smart solution to the cumulative layout shift problem - no more padding-bottom hack!

Next, I have a super simple body text component that’s for rendering an HTML text field from the database. Heading is optional and is provided by the ProgammePage and passed to the Body view. (The way I do it here, the heading might as well be in the ProgrammePage template/component, but if we're going to, say, wrap the heading in classes, it would get ugly fast, and it would then make sense to make it parts of this component or even a separate heading component.)

I use the Rails sanitize helper for the text itself. If we were going to write plenty of these, we could abstract the raw helpers.sanitize bit into application_view or something, but in this app I want to use this Body component for every HTML-from-database part of the application, so it would likely only be used once, i.e. here.

module Views
  module Components
    class Body < ApplicationView
      def initialize(text:, heading: nil)
        @heading = heading
        @text = text
      end

      def template
        h3 { @heading } if @heading.present?
        raw helpers.sanitize @text
      end
    end
  end
end

The next part is using the as of now undocumented collection feature. It’s probably not a good idea to use this before the syntax is stable, but I’m just playing around and wanted to try it (I will update this example when/if the feature changes). (UPDATE 30 Jan 2023: the experimental collections syntax was removed in Phlex 1.3.0., so this code will not work. I might rework this example with the new syntax at some point.)

module Views
  class Components::Lightbox < ApplicationView
    include Phlex::Collection

    def collection_template(&)
      div(class: "masonry", &)
    end

    def item_template
      render Views::Components::TopImage.new(model: @item, width: 600)
    end
  end
end

Rendering the lightbox, I’m reusing the top image component for the item_template!I found this really cool, and since my TopImage component is so flexible, these items will - unlike the top image above - only be resized (not cropped) and they will be lazy loaded.

This gives the following structure:

.
├── application_view.rb
├── components
│   ├── body.rb
│   ├── lightbox.rb
│   └── top_image.rb
├── layout.rb
└── templates
    └── news.rb

...where components are meant to be shared across the application, and templates are meant to be collections of render calls (more or less) to components, and the layout (more than one is also a possibility!) the birds-eye view.

That’s it so far! Hopefully this will help someone. If I’m doing things in a weird way, please let me know!

---

I’ve loved doing this so much. I actually really like HTML syntax (I need help, obviously!), so I’ve never warmed to haml or slim and stayed with erb. For this reason, I thought writing HTML with the Phlex ruby dsl would feel wrong. However, recently, I’ve had to use much more erb tags and the constant back and forth between straight html and erb blocks like <%= options_for_select(etc, etc) %> makes my head hurt, even with judicious use of helper methods (which I don’t like either, because of context switching). Phlex is the first time I really enjoyed writing view code. (Also, it's crazy fast!) Looking forward to rewriting more of this project with it.

[joeldrapper]

This is awesome! I need to take some time to go through your examples in more detail, I just wanted to quickly point out that raw should probably never be used to render content from the database. I might rename this method to very_dangerous_raw or something like that to make it clear. The reason is a user might be able to place a <script> tag in your database that exploits some other user’s session when they view the content.

You could use use raw in conjunction with Rails sanitize helpers. Perhaps Phlex should provide some sanitization helpers itself.

[evenreven]

My use case is for output of a postgres text column that already contains safe HTML (not result of user input, but of a parsed XML document (pulled with httparty) that's then sanitized before save). It's possible (I guess) to use a combination of Nokogiri::XML and Phlex instead to parse and output directly, but I don't want to do this kind of expensive operation in the view layer if I can help it.

Does this make sense? Or am i missing something?

Vaguely related question... Is it possible to use the power of Phlex outside of the view layer - in, say, an ActiveJob - to create HTML for saving in a database? I've been using Nokogiri to build HTML before saving in the db, and to say I dislike this workflow would be an understatement.

[joeldrapper]

I always prefer to sanitise output rather than (or in addition to) sanitising input, but it makes sense. As long you're sure that content is safe, that’s what unsafe_raw is for.

You can definitely render a Phlex view in a job and save the output. You should be able to do something like this:

output = MyView.call(arguments)

[evenreven]

Thanks for the quick reply, I'm excited to try that!

I have a CMS lite idea I'm going to try out, where I'm going to save a rich text field with editorjs or some prosemirror editor (like tiptap) as jsonb for the canonical representation of the content, then when pressing a publish button, it'll set off an active job that uses Phlex to build HTML and save in a text column. Then we can safely use unsafe_raw in the view. This way, I can use autosave with the editor without autopublishing changes. I think it'll work.

[joeldrapper]

If you’re saving the TipTap content in JSON, I don’t think you need to transform it to HTML in a job; you can do it in the view layer. Phlex should be plenty fast enough.

Here’s an example TipTapOutput Phlex class that might help you start out. It’s working with the sample JSON output.

# We need to use a `Proc` refinement that defines a wrapping method

module ProcWrap
  refine Proc do
    def &(other)
      -> { other.call(&self) }
    end
  end
end

using ProcWrap

class TipTapOutput < Phlex::HTML
  def initialize(document)
    @document = document
  end

  def template
    visit(@document)
  end

  def visit(node)
    case node["type"]
    when "doc"
      visit_each(node["content"])

    when "paragraph"
      p { visit_each(node["content"]) }

    when "text"
      result = -> { text node["text"] }

      node["marks"]&.each do |mark|
        case mark["type"]
        when "bold"
          result &= -> (&r) { strong { r.call } }
        when "italic"
          result &= -> (&r) { em { r.call } }
        end
      end

      result.call
    end
  end

  private

  def visit_each(nodes)
    nodes.each { |node| visit(node) }
  end
end

If you're using Tailwind, you may want to define a subclass of this for your specific use-case and override tag methods. Here's an example

class ArticleContent < TipTapOutput
  private

  def em = super(class: "italic")
  def strong = super(class: "font-bold")
end

[evenreven]

That is super helpful, thank you so much! I did an experiment with a super hacky version of parts of this, but this is so much better. (I was using case when for marks like you, but then public_send, which is probably a terrible idea for a variety of reasons - I'm a self "taught" programmer who inherited a Rails app at work, so my code quality can best be described as duct-tapey.)

I'm not too worried about speed when it comes to JSONB (XML parsing, on the other hand...), the main reason for saving the Phlex output instead of just doing everything in the view layer is actually being able to explicitly deploy (or commit in vcs speak) the changes to a text once it is good enough (while the editor will autosave to the jsonb column so we don't lose data). In our current cms, we sometimes delay saving a change to existing content because it will be visible right away before proof reading. Which feels silly.

So it's not mainly about speed, but about workflow. But there's probably more than one way to solve this. I'll experiment some more. It's still early in the project.