DEV Community: Arnaud Joubay

How to add a Diagnostic Mode using Settings.bundle and SwiftUI

Arnaud Joubay — Wed, 27 Apr 2022 09:39:54 +0000

Technical stuff shouldn't surface in your app, but it can be useful at times: let's see how we can enable a "Diagnostic Mode" or a "Developer" menu in your app using Settings.bundle.

Fight your inner geek

Before diving into the instructions, here are some personal insights explaining why I needed this.

I get it, you love tweaking everything, and your app should let users gut it open and dissect everything.

But for the average user, anything technical can create confusion and complexity. Our job as software developers is to solve problems, not create new ones. And by offering too many options, you're creating a burden for your users: they have to understand what these options are for, figure out if/when they need them and learn how to use them.

Even as a tech-savvy user, I don't want to be bothered with too many options inside the app itself if it's not part of the experience.

My personal rule is that any menu item that users are unlikely to need shouldn't appear in the in-app Settings.

For instance, my app has a hidden "iCloud Sync" menu option in its Settings to help identify potential iCloud sync issues.

Until now, this menu appeared automatically based on the connectivity status (which I get from CloudKitSyncMonitor).

But there are 2 drawbacks:

it can be disturbing or anxiety-inducing : sometimes the menu will appear for a split second during the course of a normal event, and if you don't know what this is about it can be troubling
you can't access it willingly : I added a "Data integrity" section that is not directly related to CloudKit's connectivity status and I want to be able to access it

So I wanted to have a way to reveal this menu manually, and this is where Settings.bundle comes in.

This means I will also be able to add other menu options that could help me collect data, like the entire SQLite store if need be.

By adding a toggle in the app Settings (the ones inside the device Settings, not the in-app Settings), where (almost) no one ever goes looking.

Adding Settings.bundle

I'm only going to cover adding a "Diagnostic Mode" toggle, I'm sure you can figure out the rest from there.

First, add a new file (⌘N) and look for "Settings Bundle"

Snapshot of template picker

This will add the Settings.bundle which includes a default Root.plist file and a localization file.

In the "Preference Items":

keep only the "Toggle Switch"
change the Title to "Diagnostic Mode"
change the Identifier to "diagnostic_mode_enabled"
set the Default Value to NO so that it's false by default

It should look like this:

Target Root.plist

Let's see if this value is available to us:

add a breakpoint somewhere in your app
run it (⌘R)
get into the console
Enter po UserDefaults.standard.bool(forKey: "diagnostic_mode_enabled")

false, it works 🥳

WRONG.

Go back and now enterpo UserDefaults.standard.dictionaryRepresentation().keys.sorted()

The diagnostic_mode_enabled key is missing 😒.

You only got false because bool(forKey:) returns false if the key doesn't exist, and not because Default Value is "NO".

Here's the catch: that key won't be available until the user changes the setting.

So you'd better be careful about the default values you use there. In our case, since we want false by default (including if the user didn't touch the settings), NO is perfect.

Showing the button in your SwiftUI view

The only thing you have to do is to listen to the UserDefaults.didChangeNotification and toggle a @State variable to show or hide your Button or NavigationLink.

It should look something like this:

struct SettingsSection: View {
    @State var isShowingCloudLink = false

    var body: some View {
        Section {
            if isShowingCloudLink {
                NavigationLink(destination: CloudSettingsView()) {
                    Label(…)
                }
            }
        }
        .onReceive(
            NotificationCenter.default
                .publisher(for: UserDefaults.didChangeNotification)
                .receive(on: RunLoop.main)
        ) { _ in
            isShowingCloudLink = UserDefaults.standard.bool(forKey: "diagnostic_mode_enabled")
        }
    }
}

Code Sample of the SeriousSection in my Settings

Don't forget to receive on RunLoop.main or you will get a notification from Xcode warning that you are "Publishing changes from background threads".

🍒 As suggested by @alpennec, it's a good idea to wrap the isShowingCloudLink = UserDefaults.standard.bool(forKey: "diagnostic_mode_enabled") in a `withAnimation {}.

Localizing the Settings

If your app is available in multiple languages, you'll probably want to localize the settings.

Unfortunately, this has to be done manually (instead of the usual box-checking from the File Inspector)

Right-click on "en.lproj" and select "Show in Finder"
Duplicate and rename "en.lproj" for each language you support

Since the Settings.bundle is added as a reference, you don't have to drag them into Xcode, they will appear automatically.

If you're using Localazy like me, here's what the config for your localazy.json could look like (more about this here)

`
{

"upload": {
    "files": [
        {
            "type": "ios-strings",
            "pattern": "YourApp/Settings.bundle/en.lproj/Root.strings",
            "path": "YourApp/Settings.bundle"
        }
    ]
},

"download": {
    "files": [
        {
          "conditions": [["!startsWith: fastlane, ${path}"]],
          "output": "${path}/${iosLprojFolder}/${file}"
        }
    ]
}

}

🫵 Enjoyed this article?

If you liked this article or want to talk, please like/RT/comment this tweet:

Arnaud Joubay 🥐🐮

@sowenjub

How to add a "Diagnostic Mode" in your #SwiftUI app?

My "iCloud Sync" menu appears automatically if there's an issue but I wanted something that could be triggered manually and wrote a blog about it.

Here are the highlights, a catch, and a link to the article at the end 👇

11:13 AM - 27 Apr 2022

Translating your iOS app with Localazy

Arnaud Joubay — Fri, 28 May 2021 22:00:27 +0000

A couple of people have asked me to translate No Meat Today in their language, but the last time I tried to tackle that, none of the solutions I found were satisfying or in my price range.

I just found Localazy and I'm sold. And not just because there’s /lazy/ in the name. It’s built by devs and from the CLI to the way it works, it felt like we understood each other and it was behaving “as it should”.

So here’s a little recount of my experience so far, hopefully that’ll help you get started.

If you can’t wait to get started, you can register using this link and I’ll earn extra phrases (thanks 😁).

What needs translation?

In order to get No Meat Today ready for a new country, I have to translate these file formats:

strings: until SwiftUI arrived, I would split Localizable.strings into multiple files and use table names but I’ve started to regroup files and use a simple prefix in the key instead
stringsdict: this is used to handle plural
plist: I use this for the daily messages, so it’s a list of sentences, packaged by theme (Default, Premium, Star Wars, Xmas…)
some assets: I only have some screenshots for the paywall that are translated (en/fr), I can default to English
txt: marketing texts & screenshots published on the App Store. This is downloaded into my app folder by fastlane.tools

Localazy supports only the first 3 file formats: strings, stringsdict and plist, but that’s already better than some other solutions I considered.

I suggested them to support txt files, you can vote for it if you like that idea.

Pricing

Fair warning: you will probably have to pay. But something that feels fair.

You get 200 phrases for free and can buy more. Adding 500 (so 700 total) will cost you a one-time fee of $50, and 1000 (1200 total) $90.

I found the project launch on Product Hunt and they advertised 1000 keys for free and a 75% discount. I contacted them about it and Václav was transparent about how this was too generous to build a viable business and that they had to decrease it. I wasn’t really surprised to be honest, and the current pricing still seems pretty reasonable to me.

They also offer a starter pack subscription at $19/mo or $199/year, and it wouldn’t be surprising if they decided to drop the one time fee at some point. Hopefully that will include more affordable tiers, but in any case, Václav promised me that any phrases bought now will be owned forever, which is enough for me.

You can get free phrases with a referral link (here is mine, again, I have no shame). Know that this referral bonus is added on a daily basis, and you only get it if the user integrates their app (upload texts).

I was told they would offer more ways how to earn free phrases.

Setup

The main pages you’ll want to look at are

It can be worth having a look at these two as well since they describe the configuration of the two core commands of Localazy: upload and download.

Install the CLI

Installation is done via Homebrew

xcode-select --install # Only if you haven't done so before
brew tap localazy/tools
brew install localazy

Create your configuration file

I followed the Quick Start - iOS & macOS – Localazy instructions at first, but this didn’t work for me.

I have a Watch Extension, so for instance I have a Base.lproj in both the “No Meat Today” subfolder and “No Meat Today Watch App Extension”.

After playing with upload/download a bit, I ended up with this configuration.

{

    "writeKey": "my-write-key",
    "readKey": "my-read-key",

    "upload": {
        "files": [
            {
                "type": "ios-strings",
                "pattern": "No Meat Today/Base.lproj/Localizable.strings",
                "path": "No Meat Today"
            },
            {
                "type": "ios-strings",
                "pattern": "No Meat Today/fr.lproj/Localizable.strings",
                "path": "No Meat Today",
                "lang": "fr"
            },
            {
                "type": "ios-stringsdict",
                "pattern": "No Meat Today/Base.lproj/Localizable.stringsdict",
                "path": "No Meat Today"
            },
            {
                "type": "ios-stringsdict",
                "pattern": "No Meat Today/fr.lproj/Localizable.stringsdict",
                "path": "No Meat Today",
                "lang": "fr"
            },
            {
                "type": "ios-plist",
                "pattern": "No Meat Today/Base.lproj/Silliness.plist",
                "path": "No Meat Today"
            },
            {
                "type": "ios-plist",
                "pattern": "No Meat Today/fr.lproj/Silliness.plist",
                "path": "No Meat Today",
                "lang": "fr"
            },
            {
                "type": "ios-strings",
                "pattern": "No Meat Today Watch App Extension/en.lproj/Localizable.strings",
                "path": "No Meat Today Watch App Extension"
            },
            {
                "type": "ios-strings",
                "pattern": "No Meat Today Watch App Extension/fr.lproj/Localizable.strings",
                "path": "No Meat Today Watch App Extension",
                "lang": "fr"
            }
        ]
    },

    "download": {
        "files": "${path}/${iosLprojFolder}/${file}"
    }   
}

As you can see, unlike the proposed configuration I use a path variable so that I can support the same Localizable.stringsfile in two different subfolders, which means I can translate all extensions (Watch App, Widget…).

The app’s default language is English, and my app is localised in French, which means I already had translated texts. The above configuration allowed me to upload my translations in one go.

Does it mean I’ll have to add new rows for each new language? I don’t think so.

If you edit a translation file and call localazy upload it will push the edit translation for review, which is quite nice. While I will probably want to do that for French (since it’s my native language and I may spot typos or find better translations while coding), it’s unlikely that I will try to edit strings in a language that I don’t speak. So for these other languages, I will only download and not upload, since I won’t do any changes to these files.

Lingo: before you read the rest

First, a reminder of what a localisation in a strings file looks like and some terms used thereafter.

/* This is a comment */
"a.key" = "This is a key";

translation notes: the comment / first line
key: the left hand side of the 2nd line, a uniq string to identify your text across all languages
phrase: the right hand side of the 2nd line
source language: the language used in your Base.lproj files
source phrases: the phrases in your source/base language

Translating

This is what the UI looks like. I think it’s pretty straightforward. But more importantly, I invited a translator who is not a dev and they found it easy to use as well.

Some things to notice:

everything that can help is there: the key, the source phrase, the translation notes, even the file path
at the bottom you can see 2 types of suggestions: ShareTM is the database of translations from other apps/devs who decided to share their translations, and the other one is an automatic translation. This is really helpful to get a first quick & dirty translation of each phrase.
I love bad puns

Good to know & other tips

Things below should help you get started, I figured some of it by trial and error, and the rest by talking with someone in the team (🙌 Vaclav!)

Your default language is kinda hidden

When you first upload your strings, you can be surprised that you don’t find your base/source language. It took me a while to see it, but your source phrases are hidden behind the little sandwich menu next to the mention of your source language.

When I first uploaded my strings, I only found the French language and couldn’t figure out where the English phrases were. I even tried to add en_US as a language before I realised the source language wasn’t treated as the other languages.

I mentioned this to the team and apparently they’ll try to improve this.

Know that another way to access your source phrases is by heading to the “File management” section.

You will lose control over the format of your files (but not the Base one 🙌, and it’s OK anyway)

Up until now, I would make sure my files were organised in the same way, having the same number of lines, spaces, comments. I would then open both language files simultaneously and modify them at the same time.

The identical number of lines especially made it easier to spot discrepancies, which meant untranslated keys.

So naturally, when I started searching for a service to handle translations, I imagined there might be one that would scan my files, keep the keys exactly where they were (append the missing ones) and only change the phrases/translations.

But, this is not how things work.

Instead, each time you download the translations, the language files are overwritten and keys are sorted alphabetically.

I can live with that, I guess. I mean, as I explained above, I’m unlikely to modify phrases in languages other than English and French.

Deleting a key doesn’t delete it in the base language

By default, base files are not overwritten, which means that if you delete a key, it will be deleted in all your language files except the base one, where you’ll have to delete it manually.

This is a good thing, because it means that you can format your base file as you want.

In particular, you can make use of // MARK : - Section to make it easier to navigate your Localizable.strings.

If you do use these, make sure you add a different comment (even an empty one such as /**/) above the first key so that the MARK doesn’t show up as translation notes.

Finally, if you do want to overwrite the files in your base language, you can for it by setting the includeSourceLang in your config file.

What if I change a translation in the source language?

This is something I was worried about and it works just as you would expect: when you edit a translation, all languages see a notice that the source phrase was changed, so that they can be changed if necessary.

If you do it from the web, you get a bit more flexibility because you can decide whether existing translations need to be updated or not.

But, I wouldn’t do it from there, because, remember, the source phrases are not downloaded, so you’d have to change it manually in Xcode.

What if I change a translation in a language that is not the source language?

If you change a translation in Xcode, say in the fr.lproj/Localizable.strings, and then run localazy upload, it will upload the translation for review but it won’t be taken into account until your review it

This means that if you run localazy download before you review the change on the web, your change will be overwritten.

But what if you run localazy upload again before you review it, will you lose your change? No, because there is a versioning system and you’ll still be able to find your unreviewed change. 💪

There is a Glossary

You can add terms that require extra context or attention in a Glossary.

For instance, I invented the term “Cowliday” and added it to the Glossary to explain it and give some instructions that will show up each time the term is used.

When translating a phrase, the term is highlighted and hovering it will show the comments.

Parting notes

Localazy supports all the file formats I expected it to, and hopefully txt support will arrive some day to simplify App Store marketing localisation
It’s free for apps with less than 200 phrases, and affordable for small apps plus there are ways to get free phrases
CLI is a charm
Setup is pretty easy if you follow the configuration above
The UI to translate is reactive and works well, and is easy to use for non-devs (well, I tested with a single person for now)
Register using my referral link

Final note: if you want to help translate No Meat Today in your language, I’m looking for volunteers.

Capybara: 2 ways to click links in emails

Arnaud Joubay — Sat, 19 Dec 2020 19:02:00 +0000

If you want to write system tests you'll probably want to cover a use-case involving an email sent to a user (for instance, a sign up confirmation link).

There are at least 2 ways to do that:

with nokogiri if you want to keep things lean
with capybara-email if you appreciate a little comfort

With nokogiri

Add the gem to your Gemfile and run bundle install.
Chances are you'll find it in your Gemfile.lock already since it's a pretty standard gem with 5k+ stars.

group :test do
  gem "nokogiri"
end

And you can open your email and click the line like this:

email = ActionMailer::Base.deliveries.last
html = Nokogiri::HTML(email.html_part.body.to_s)
target_link = html.at("a:contains('Click this link')")
visit target_link["href"]

With capybara-email gem

Add the gem to your Gemfile and run bundle install. It only has 300+ stars, which is still pretty good, and it's also a rather simple gem so you could easily decide to contribute to it if your app depended on it.

group :test do
  gem "capybara-email"
end

And you can open your email with just 2 lines:

open_email "arnaud@example.com"
current_email.click_link "Click this link"

Replacing Selenium with Cuprite for Rails system tests

Arnaud Joubay — Fri, 18 Dec 2020 12:02:00 +0000

Replacing Selenium with Cuprite for Rails system tests

In the world of tests, system tests are as close to real users as it gets: you control a browser and make it use your app as you expect humans to.

To do so, you need two things:

a browser : you will see it (safari, chrome…) run on its own on your machine unless you set it to be "headless", a gory way to tell your machine that you actually don't want to see the insides of your tests
a driver : the pilot that will take your test instructions and command the browser

By default, Rails ships with Selenium, but there's a new kid in town: Cuprite, a "Headless Chrome driver for Capybara", which is faster and has some nice tricks up its sleeves like options to pause and debug.

I discovered cuprite thanks to Evil Martians blog post: "**System of a test:** Proper browser testing in Ruby on Rails".

The following is just a quick-start version for those who don't care about docker or rspec, with some minor twists.

Basic setup

To get started, you simply need to add the cuprite gem. Selenium will have to stay unless you're on Rails 6.1.

group :test do
  gem 'capybara'
  gem 'selenium-webdriver' # Only for rails <= 6.1
  gem 'cuprite'
end

And then you can edit test/application_system_test_case.rb

require "test_helper"
require "capybara/cuprite" # <- Add this

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  # And replace selenium with cuprite
  driven_by :cuprite, using: :chromium, screen_size: [1400, 1400]
end

And with this you're good to go.

You'll notice that I'm not using :chrome but the open source browser it's based on: Chromium. This is because I just uninstalled Chrome, because https://chromeisbad.com.

https://twitter.com/sowenjub/status/1338958371844726784?s=20

A more elaborate setup

There are a couple more setup files I grabbed from Evil Martians' setup, with a slightly different organisation since I'm not using rspec.

test/
  test_helpers/
    system/
      better_rails_system_tests.rb
      capybara_setup.rb
      cuprite_helpers.rb
      cuprite_setup.rb

And with this, test/application_system_test_case.rb will end up looking like this:

require "test_helper"
require "test_helpers/system/better_rails_system_tests"
require "test_helpers/system/capybara_setup"
require "test_helpers/system/cuprite_helpers"
require "test_helpers/system/cuprite_setup"

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :cuprite, using: :chromium, screen_size: [1400, 1400]

  include BetterRailsSystemTests
  include CupriteHelpers
end

And of course you need to create the files, taken from Evil Martians.

# test_helpers/system/better_rails_system_tests

module BetterRailsSystemTests
  # Use our `Capybara.save_path` to store screenshots with other capybara artifacts
  # (Rails screenshots path is not configurable https://github.com/rails/rails/blob/49baf092439fc74fc3377b12e3334c3dd9d0752f/actionpack/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb#L79)
  def absolute_image_path
    Rails.root.join("#{Capybara.save_path}/screenshots/#{image_name}.png")
  end

  # Make failure screenshots compatible with multi-session setup.
  # That's where we use Capybara.last_used_session introduced before.
  def take_screenshot
    return super unless Capybara.last_used_session

    Capybara.using_session(Capybara.last_used_session) { super }
  end
end



# test_helpers/system/capybara_setup

# Usually, especially when using Selenium, developers tend to increase the max wait time.
# With Cuprite, there is no need for that.
# We use a Capybara default value here explicitly.
Capybara.default_max_wait_time = 2

# Normalize whitespaces when using `has_text?` and similar matchers,
# i.e., ignore newlines, trailing spaces, etc.
# That makes tests less dependent on slightly UI changes.
Capybara.default_normalize_ws = true

# Where to store system tests artifacts (e.g. screenshots, downloaded files, etc.).
# It could be useful to be able to configure this path from the outside (e.g., on CI).
Capybara.save_path = ENV.fetch("CAPYBARA_ARTIFACTS", "./tmp/capybara")

# The Capybara.using_session allows you to manipulate a different browser session, and thus, multiple independent sessions within a single test scenario. That’s especially useful for testing real-time features, e.g., something with WebSocket.
# This patch tracks the name of the last session used. We’re going to use this information to support taking failure screenshots in multi-session tests.
Capybara.singleton_class.prepend(Module.new do
  attr_accessor :last_used_session

  def using_session(name, &block)
    self.last_used_session = name
    super
  ensure
    self.last_used_session = nil
  end
end)

For this one I created a dedicated file but you could put it at the end of cuprite_setup as well.

# test_helpers/system/cuprite_helpers

module CupriteHelpers
  # Drop #pause anywhere in a test to stop the execution.
  # Useful when you want to checkout the contents of a web page in the middle of a test
  # running in a headful mode.
  def pause
    page.driver.pause
  end

  # Drop #debug anywhere in a test to open a Chrome inspector and pause the execution
  def debug(*args)
    page.driver.debug(*args)
  end
end



# test_helpers/system/cuprite_setup

# First, load Cuprite Capybara integration
require "capybara/cuprite"

# Then, we need to register our driver to be able to use it later
# with #driven_by method.
Capybara.register_driver(:cuprite) do |app|
  Capybara::Cuprite::Driver.new(
    app,
    **{
      window_size: [1200, 800],
      # See additional options for Dockerized environment in the respective section of this article
      browser_options: {},
      # Increase Chrome startup wait time (required for stable CI builds)
      process_timeout: 10,
      # Enable debugging capabilities
      inspector: true,
      # Allow running Chrome in a headful mode by setting HEADLESS env
      # var to a falsey value
      headless: !ENV["HEADLESS"].in?(%w[n 0 no false])
    }
  )
end

# Configure Capybara to use :cuprite driver by default
Capybara.default_driver = Capybara.javascript_driver = :cuprite

And now we just have to write a simple test:

require "application_system_test_case"

class HomeTest < ApplicationSystemTestCase
  test "open home screen" do
    visit root_url
    save_and_open_page # Will save the html page in /tmp/capybara and open it in your default browser
    take_screenshot # Will save a screenshot in /tmp/capybara/screenshots
    pause # To see the current view, requires HEADLESS=0 (or n, no, false)
    debug() # To see the current view with debug tools
    assert_selector "h1", text: "Hello, world"
  end
end

To launch it, run the following:

# If you want to see the browser or use `pause`
HEADLESS=0 rails test test/system/home_test.rb

# Otherwise this will do
rails test test/system/home_test.rb

Auto-linking URLs with Trix Editor and StimulusJS

Arnaud Joubay — Tue, 20 Oct 2020 08:25:00 +0000

The https://trix-editor.org is fantastic, but there's one simple thing I expected to be built-in that isn't: copy/pasting a URL should create a link automatically instead of inserting the link as plain text.

Thinking of it, it's not so surprising because there are many things one could want to do instead, like embedding a video or a tweet. But it's a common request, and the GitHub issue includes a solution with jQuery that I used to build my Stimulus controller.

So, without further ado, here's a simple 2 steps rails tutorial to add URL auto-linking to your forms.

The controller

Create a /app/javascript/controller/trix_paste_controller.js file and copy/paste the code below.

import { Controller } from "stimulus"

export default class extends Controller {
  connect() {
    document.addEventListener("paste", this.pasteHandler.bind(this));
  }

  disconnect() {
    document.removeEventListener("paste", this.pasteHandler.bind(this))
  }

  pasteHandler(event) {
    const pastedText = event.clipboardData?.getData?.("Text")
    if (!!pastedText && !!pastedText.match(/^(https?:\/\/(?:www\.|(?!www))[^\s\.]+\.[^\s]{2,}|www\.[^\s]+\.[^\s]{2,})$/ig)) {
      this.pasteUrl(pastedText)
    }
  }

  pasteUrl(pastedText) {
    const editor = this.element.editor
    let currentText = editor.getDocument().toString()
    let currentSelection = editor.getSelectedRange()
    let textWeAreInterestedIn = currentText.substring(0, currentSelection[0])
    let startOfPastedText = textWeAreInterestedIn.lastIndexOf(pastedText)
    editor.recordUndoEntry("Auto Link Paste")
    editor.setSelectedRange([startOfPastedText, currentSelection[0]])
    editor.activateAttribute('href', pastedText)
    editor.setSelectedRange(currentSelection)
  }
}

Your forms

And now, anytime you want need this auto-linking feature, just reference the controller like so:

= f.rich_text_area :content, data: { controller: "trix-paste" }

That's it, and it's "trix-paste" and not "trix-autolink" because I have further plans for this controller.

That's it! Follow me here or @sowenjub on twitter for more

Multiple YAML defaults in Rails fixtures

Arnaud Joubay — Tue, 25 Aug 2020 16:05:00 +0000

You know that you can use YAML defaults in your fixtures to extract common attributes values and make your fixtures more readable.

DEFAULTS: &DEFAULTS
  created_on: <%= 3.weeks.ago.to_s(:db) %>

first:
  name: Smurf
  <<: *DEFAULTS

second:
  name: Fraggle
  <<: *DEFAULTS

What if you want to use more than one set of defaults?

The old way - DEFAULTS

The Rails example is a bit confusing because it uses "DEFAULTS" for both the label and the anchor/alias, but here's how to handle multiple defaults:

DEFAULTS: &decisions
  icon: 🧠
  name: Decisions

DEFAULTS: &help
  icon: 👋
  name: Help

founders_decisions:
  team: founders
  <<: *decisions

founders_help_requests:
  team: founders
  <<: *help

To understand how this works, you need to know two things.

The Rails docs tell us that it doesn't matter how many "DEFAULTS" label we have: they won't overwrite themselves even though they use the same label.

Any fixture labeled “DEFAULTS” is safely ignored
The YAML spec explains how aliasing works

Repeated nodes (objects) are first identified by an anchor (marked with the ampersand - “&”), and are then aliased (referenced with an asterisk - “*”) thereafter.

Edge Rails way - fixture:ignore

There's another way to do that on Edge Rails. You can specify fixtures that should be ignored and that you can therefore use as defaults.

We can rewrite the example above like this:

_fixture:
  ignore:
    - decisions
    - help

decisions: &decisions
  icon: 🧠
  name: Decisions

help: &help
  icon: 👋
  name: Help

founders_decisions:
  team: founders
  <<: *decisions

founders_help_requests:
  team: founders
  <<: *help

Which one should I use?

If you're using the Rails 6.0.3.2 or below, you don't have a choice anyway. But even then, while the edge option is interesting because the anchor/alias mirrors the label, I'll stick with the "old way" for two reasons:

it's less code (you don't have to write the _fixture block)
the DEFAULTS label is easy to spot and explicit. You could use DECISION_DEFAULTS: &decisions instead of decisions: &decisions but the label isn't really useful and, again, you're writing more code than if it's just DEFAULTS: &decisions

Power your Publish (Swift) static site with Tailwind CSS

Arnaud Joubay — Thu, 13 Aug 2020 13:42:00 +0000

Within minutes, you will be able to deploy a static site/blog (with Publish) that you can style easily (with TailwindCSS).

If you don't want to create your own theme, you can save some time and use my Casperish theme, a port of Ghost's Casper theme using Tailwind CSS.

Install Publish

Publish is a static site generator built specifically for Swift developers, created by John Sundell (@johnsundell) and powering his very own swiftbysundell.com.

You need to have installed Xcode and its Command Line Tools. It's preferable to have a basic understanding of how it works (build, run, understand crash logs).

For now, open your terminal and follow the README.


git clone https://github.com/JohnSundell/Publish.git
cd Publish
make

Create your website

Publish is just the engine, it's now time to create your website.

Let's get out of /Publish and create your website source next to it. We'll call it MyWebsite.


cd ..
mkdir MyWebsite
cd MyWebsite
publish new

And since we're impatient, let's see what it looks like at this point.


publish run

This should output something like this


Fetching https://github.com/johnsundell/publish.git
…
…
…
Publishing MyWebsite (6 steps)
[1/6] Copy 'Resources' files
[2/6] Add Markdown files from 'Content' folder
[3/6] Sort items
[4/6] Generate HTML
[5/6] Generate RSS feed
[6/6] Generate site map
✅ Successfully published MyWebsite
🌍 Starting web server at http://localhost:8000

Press ENTER to stop the server and exit

Open http://localhost:8000 in your browser of choice (Safari here) and it should look like this:

or in dark mode:

Time to launch Xcode

We've been lazy alright, it's time to open Xcode and dive into some code.

From /Publish/MyWebsite run


open Package.swift

It will look like this:

A couple things to notice:

You can see at the top of the screen that the active scheme is "My Mac". This is important because you won't be able to build/run on devices or simulators
/Sources/MyWebsite/main.swift is were you can configure your app
You won't have the package.json or yarn.lockfiles at this point
/Content contains the markdown content we saw when we opened the site (ex: "Welcome to MyWebsite")

Pause for coffee and think about your future

From now on, before your refresh your browser to see the result of any change you made to your configuration or content, don't forget to rebuild your site in Xcode using ⌘+R.

Getting ready for TailwindCSS with a new Plot theme

To build the website from the Content folder, Publish used its default theme called Foundation which is two parts:

Theme+Foundation.swift which adopts the HTMLFactory protocol in order to create HTML for a site's various locations using the Plot DSL. Basically, it defines the HTML markup of each pages (index, article, page, tags index, tag page) ⇒ we'll want to have access to this in some way to inject our TailwindCSS classes.
styles.css which is the CSS stylesheet for that theme ⇒ we'll want to change that with the ones generated by TailwindCSS.

As you may have guessed, we need to build our own theme.

What do we need to do?

Let's start with the end and work our way up.

We will tell Publish to use our own theme, so open main.swift and change the last line (should be line 25).


// main.swift

// From
try MyWebsite().publish(withTheme: .foundation)
// to
try MyWebsite().publish(withTheme: .myTheme)

Alright. Except this won't work of course so don't try to build or run right now.

Now we need to define myTheme somewhere. We'll just create a new theme file in the Sources, next to /Sources/MyWebsite/main.swift.

Let's call it Theme+MyTheme.swift (from Xcode, right click on the Sources/MyWebsite folder and "New file").

But what should we put in there? The Publish README explains how to build a custom theme. Again, we'll write things as they should be in the end, and work our way up.

So we want to end up with something like this:


import Foundation
import Plot
import Publish

extension Theme where Site == MyWebsite {
    static var myTheme: Self {
        Theme(
            htmlFactory: MyThemeHTMLFactory<MyWebsite>(),
            resourcePaths: ["Resources/MyTheme/styles.css"]
        )
    }
}

What did we add there that doesn't exist already? Two things:

MyThemeHTMLFactory
"Resources/MyTheme/styles.css"

Looks familiar? This is the same setup I mentioned above when I introduced the Foundation theme.

If you open the Theme+Foundation.swift file (you can find it in Xcode under "Swift Package Dependencies" by opening the Publish package and going down to /Publish/Sources/Publish/API), you will

MyThemeHTMLFactory: Our own HTML Factory

We want to build a custom theme, so let's take inspiration from the free one we're given.

In Xcode, under "Swift Package Dependencies" you will find the Publish package, and inside of it is Publish/Sources/Publish/API/Theme+Foundation.swift.

A few lines below the public extension Theme declaration that we don't need since we just defined our own, you will find the foundation factory that we will use as a starting point.

We need to do 3 things:

Copy the rest of the file, which includes one struct and one extension


private struct FoundationHTMLFactory<Site: Website>: HTMLFactory {
  …
}

private extension Node where Context == HTML.BodyContext {
  …
}

Paste it in our Theme+MyTheme.swift, below our extension Theme where Site == MyWebsite {} declaration.
Change FoundationHTMLFactory to MyThemeHTMLFactory

So to be clear, Theme+MyTheme.swift should look like this


import Foundation
import Plot
import Publish

extension Theme where Site == MyWebsite {
    static var myTheme: Self {
        Theme(
            htmlFactory: MyThemeHTMLFactory<MyWebsite>(),
            resourcePaths: ["Resources/MyTheme/styles.css"]
        )
    }
}

private struct MyThemeHTMLFactory<Site: Website>: HTMLFactory {
        // What's inside didn't change
}

private extension Node where Context == HTML.BodyContext {
        // What's inside didn't change
}

OK!

There's one last thing we need: "Resources/MyTheme/styles.css"

Let's add TailwindCSS!

Let's add Tailwind by following the documentation https://tailwindcss.com/docs/installation.

We will also add the typography plugin since we're dealing with Markdown, and this plugin was specifically created to add beautiful typographic defaults to any vanilla HTML you don't control.

From /MyWebsite, open your terminal and run:


yarn add tailwindcss
yarn add @tailwindcss/typography

We'll now add our theme stylesheet in Resources


cd Resources
mkdir MyTheme
touch theme.css

Open theme.css in Xcode, and add those lines:


@import "tailwindcss/base";

@import "tailwindcss/components";

@import "tailwindcss/utilities";

We need to create a config file for TailwindCSS since we want the typography plugin, so we'll create a config file in /Resources/MyTheme as well.


npx tailwindcss init

Open the tailwind.config.js file it created in Xcode and add the typography plugin.


module.exports = {
  content: [],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [require('@tailwindcss/typography')],
}

Now to give this a spin and make sure it works so far, let's use the tailwind cli (from within /Resources/MyTheme)


npx tailwindcss build theme.css -o styles.css -c tailwind.config.js

TADA! We now have our .css file

At this point (or anytime you make a change), you can just run the package Product > Run (or ⌘+R) and refresh your page in the browser (assuming your server, launched with publish run is still running).

It should look like this.

So, that's a step back for sure.

But now, you can ride like the wind and build your own theme using Tailwind!

Getting started

We already know it works since all styles were reset, but let's add a class to make sure it really does.

Open your Theme+MyTheme.swift file, locate makeIndexHTML() and change the header as explained below:


func makeIndexHTML(for index: Index,
                       context: PublishingContext<Site>) throws -> HTML {
        HTML(
            .lang(context.site.language),
            .head(for: index, on: context.site),
            .body(
                .header(for: context, selectedSection: nil),
                .wrapper(
                    // Turn this
                    .h1(.text(index.title)),
                    // into this
                    .h1(.text(index.title), .class("text-2xl font-semibold")),
                    .p(
                        .class("description"),
                        .text(context.site.description)
                    ),
                    .h2("Latest content"),
                    .itemList(
                        for: context.allItems(
                            sortedBy: \.date,
                            order: .descending
                        ),
                        on: context.site
                    )
                ),
                .footer(for: context.site)
            )
        )
    }

Now rerun (⌘+R), refresh your browser, and enjoy a bigger title!

That's not much, but there rest is up to you, sky's the limit.

Controlling styles.css File Size

Right now we included all TailwindCSS styles in the styles.css file, so the file is 10 times bigger than it could be.

In order to shave off a few pounds, we'll setup purge in the tailwind.config.jsfile, which should end up looking like this.

It will only keep classes present in your theme file (assuming you did name it Theme+MyTheme.swift otherwise you need to adjust the content line).


module.exports = {
  content: ['../../Sources/**/Theme+*.swift'],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [require('@tailwindcss/typography')],
}

Now we need to re-build the styles.css. Before you do it, check the number of lines in your current styles.css file so you can compare before/after the purge.


npx tailwindcss build theme.css -o styles.css -c tailwind.config.js

And with this, we are done!

Too much work?

Don't worry, I got your back!

If you want a website that looks like this, just checkout my article Your Publish website with my Casperish theme in less than 5 min, and then read Deploy your Publish website for free on GitHub Pages.

Deploy your Publish website for free on GitHub Pages

Arnaud Joubay — Thu, 13 Aug 2020 13:10:00 +0000

🐙 Create a new GitHub repository

First things first, let's create a repository to host your website content.

We'll call it mywebsite , which means it will be accessible at https://yourusername.github.io/mywebsite.

Instead of mywebsite, if you use [yourusername.github.io](http://yourusername.github.io) it will be accessible at https://yourusername.github.io. See https://pages.github.com for more infos about that.

🎞 Setup the Publish pipeline

Open your main.swift file and add deployedUsing: .gitHub("yourusername/mywebsite") to your publish pipeline, which should look something like this:


try MyWebsite().publish(
     withTheme: .casperish,
     deployedUsing: .gitHub("sowenjub/mywebsite"),
     additionalSteps: [
         .installPlugin(.readingTime()),
         .installPlugin(.pygments()),
     ],
     plugins: [.pygments()]
 )

Now run your site in Xcode (Product > Run command or ⌘+R), then open your terminal and run


publish deploy

Head over to your repository, refresh and make sure your files are there.

🥁 Setup GitHub Pages

Open your repository settings, scroll down to the GitHub Pages section and select the master branch. Don't forget to click the Save button.

Once you're done, it should give your the address to your website.

And you're done! Unless you want to use a custom domain name, which can be set in the same settings panel.

🍒 Bonus: Deploying from Xcode

Instead of deploy using the command line with publish deploy, you can deploy straight from Xcode.

First, create a New Scheme, we'll call it Deploy MyWebsite. Click on it to reopen the same menu and select "Edit Scheme…".

Select Run and in the Arguments Passed On Lauch, add --deploy without space.

Now anytime your Run your website with the scheme (Product > Run command or ⌘+R), it will deploy your site to GitHub.

Publish your website with my Casperish theme in less than 5 min

Arnaud Joubay — Thu, 13 Aug 2020 12:59:00 +0000

I ported Ghost's Casper theme (v2) so you don't have to: it's called CasperishTheme and is available on GitHub. In this post explains how to install and customize it. It uses TailwindCSS and is based on Ghostwind with a few tweaks, upgrades and adaptations.

I'll assume that you have Xcode and its Command Line Tools installed on your machine. I detailed in another blog post how to setup a Publish website with a TailwindCSS theme that you can customize to your taste, so I won't go into much details here.

What's included with this theme

Porting the Casper theme was not only about mimicking its CSS but also about adopting its features while staying within what Publish can do (quite a lot with the help of some plugins).

So this theme includes:

Support for both Publish sections and pages (see "Organising your articles" at the end)
Support for subfolder hosting (compatible with GitHub Pages or /blog path of an existing landing page)
Icons for 5 social profiles: Dev.to, GitHub, LinkedIn, Stack Overflow, Twitter
Reading time, shown at the bottom of articles cards
Cover images for each article
Beautiful typographic defaults for your posts thanks to TailwindCSS typography plugin
A newsletter form (because why not?)
Syntax Highligthing with a Monokai theme because if you're considering Publish it's likely you will blog about code one day or the other

⬇️ Install Publish


git clone https://github.com/JohnSundell/Publish.git
cd Publish
make

✨ Create your website

Let's get out of /Publish and create your website source next to it. We'll call it MyWebsite.


cd ..
mkdir MyWebsite
cd MyWebsite
publish new

👻 Install the CasperishTheme

Open Xcode


open Package.swift

Locate Package.swift manifest (it should be the first file) add the theme as a dependency.


import PackageDescription

let package = Package(
    name: "MyWebsite",
    products: [
        .executable(
            name: "MyWebsite",
            targets: ["MyWebsite"]
        )
    ],
    dependencies: [
        .package(name: "Publish", url: "https://github.com/johnsundell/publish.git", from: "0.7.0"),
        .package(name: "CasperishTheme", url: "https://github.com/sowenjub/CasperishTheme.git", .branch("master")),
    ],
    targets: [
        .target(
            name: "MyWebsite",
            dependencies: ["Publish", "CasperishTheme"]
        )
    ]
)

Note: ideally, instead of using the master branch, we would use versioning as we do for publish itself. But we can't do that at the moment because of the syntax highlighting library, so in the meantime, we're using the master branch.

🧑‍🎨 Setup your website

Open MyWebsite/Sources/main.swift and customize it using the example below. The numbered comments pinpoint the changes required (more explanation below)


import Foundation
import Publish
import Plot
import CasperishTheme // 1

// This type acts as the configuration for your website.
struct MyWebsite: Website, CasperishWebsite { // 2
    enum SectionID: String, WebsiteSectionID {
        // Add the sections that you want your website to contain here:
        case posts
    }

    struct ItemMetadata: WebsiteItemMetadata, CasperishWebsiteItemMetadata { // 3
        // Add any site-specific metadata that you want to use here.
        var cover: String? // 3 bis
    }

    // Update these properties to configure your website:
    var url = URL(string: "https://your-website-url.com")!
    var name = "MyWebsite"
    var description = "A description of MyWebsite"
    var language: Language { .english }
    var imagePath: Path? { nil }

    // 4
    // Update these properties to configure your casperish-website:
    var rootPathString = "/"
    var headerColor = "#424242"
    var cover = ""
    var author = "Arnaud Joubay"
    var avatar = "http://i.pravatar.cc/300"
    var bio = "Swift & Rails Indie Maker"
    var icon = "🏝"
    var newsletterAction = ""
    var contacts: [(ContactPoint, String)] { [
        (.twitter, "sowenjub"),
        (.dev, "sowenjub"),
        (.linkedIn, "arnaudjoubay"),
        (.gitHub, "sowenjub"),
        (.stackoverflow, "229688"),
    ]}
}

// This will generate your website using the built-in Foundation theme:
try MyWebsite().publish(
     withTheme: .casperish,
     additionalSteps: [
         .installPlugin(.readingTime()),
         .installPlugin(.pygments()),
     ],
     plugins: [.pygments()]
 ) // 5

Well, you need the CasperishTheme package obviously
Your Website must adopt the CasperishWebsite protocol, which enables theme specific configurations (see 4.)
Your ItemMetadata must adopt the CasperishWebsiteItemMetadata which will allow you to add cover photos to each of your posts (which are items in the Publish jargon). So we also need to add the line var cover: String? inside.
This is where you can really make this theme your own:
- rootPathString this allows you to publish the website in a subfolder, such as on GitHub Pages without a custom domain name. Leave it to "/" if your site will leave at the root domain
- headerColor hexadecimal code for the header's background-color. It will be hidden by the cover image if you use one
- cover optional path the to cover image. Leave blank ("") if you want to use the headerColor instead. If you have a cover.jpg image, the path should be "/cover.jpg" if your image is at the root of your /Resources folder (don't forget the / or it won't work on subpages).
- author and bio are displayed just above the footer
- avatar is the path to your profile picture, displayed for each post. The path should be "/my avatar.jpg" if your image is at the root of your /Resources folder.
- icon can be an emoji or any short text suitable to be the icon in the navigation bar on mobile
- - newsletterAction leave blank ("") if you want to hide the newsletter, otherwise replace with the target url
- contacts is an array of nicknames used to display links to your web profiles in the header (on desktop). For now, it only supports Twitter, Dev.to, LinkedIn, Github and Stack Overflow. 5. To generate your website you need to include the 2 plugins that ships with the theme

⌨️ Edit your first post

Open Content/posts/first-post.md and write your first post!

Example of first post


---
title: My first post
cover: /first_post.jpg
date: 2020-08-04 00:46
description: A description of my first post.
tags: first, article
---
# My first post's content title

My first post's text.

If you want to get up and running fast, you can cheat and replace /first_post.jpg with https://source.unsplash.com/collection/1118905/ or even remove the line entirely and your post won't have a cover.

🚀 Run your website

You're done! To see the result, just run the following command from /MyWebsite


publish run

Now open your browser and enjoy the result.

If you use this as your theme, ping me and I'll list your blog to the CasperishTheme repository. ✌️

🍻 Bonus: things to know

Posts cover images

The theme allows posts to have cover images, you just have to set it in your front matter.

So if you want to use /Resources/first_post.jpg as you cover for a post, add cover: /first_post.jpg like below:


---
title: My first post
cover: /first_post.jpg
date: 2020-08-04 00:46
description: A description of my first post.
tags: life, anew
---
# My first post

My first post's text.

And if you don't want a cover, just remove the cover line!

Title

Publish is smart: it will guess the title front your post content. But this means your title will appear twice: once above the cover image, and once below.

Instead, you should set it in your front matter (as is done is the example above).

Organising your articles

In order to organise your content, you can play two variables:

your categories (displayed in the menu, declared in your main.swift as SectionID)
your tags (displayed above each post, declared in each post's front matter)

Emoji picker controller with StimulusJS and Emoji Button

Arnaud Joubay — Wed, 15 Jul 2020 14:31:43 +0000

I needed an emoji picker for my latest Rails app and found Emoji Button by @joeattardi that he introduced here.

Since he already did the heavy-lifting required to provide a vanilla JavaScript emoji picker component, I just needed to add it to my app and create a Stimulus controller.
And here's how to do it for yours.

I'll assume you already have StimulusJS installed. From there, it's only a couple of steps.

First, open your Terminal and add the emoji-button package.

yarn add @joeattardi/emoji-button

Then, create a app/javascript/controllers/emoji_picker_controller.js with this code inside

import { Controller } from "stimulus"
import EmojiButton from '@joeattardi/emoji-button'

export default class extends Controller {
  static targets = [ "button", "input" ]

  connect() {
    this.picker = new EmojiButton()
    this.picker.on('emoji', emoji => {
      this.buttonTarget.innerHTML = emoji
      this.inputTarget.value = emoji
    })
  }

  toggle(event) {
    event.preventDefault()
    this.picker.togglePicker(event.target)
  }
}

And now, if you have a Post model with an emoji attribute, you can do this in your form (the syntax below uses Slim instead of ERB):

= form_for post, url: post_path(post), data: { controller: "emoji-picker" } do |f|
  button data-action="emoji-picker#toggle" data-target="emoji-picker.button"
    = post.emoji.presence || content_tag(:i, nil, class: "fad fa-smile text-gray-400")
    = f.hidden_field :emoji, data: { target: "emoji-picker.input" }

The content_tag(:i, nil, class: "fad fa-smile text-gray-400") bit uses FontAwesome to show a default gray emoji when there is none.

And that's all there is to it. Anytime you click the button, the picker will be toggled, and if you select an emoji, both the button and the hidden form input will be updated.

Rails+TailwindCSS: adding "required" to form labels (and how to find the solution by yourself)

Arnaud Joubay — Fri, 10 Jul 2020 13:44:26 +0000

This post addresses a simple need: adding a "required" text next to any form field label that is… required.

But I wanted a solution:

using only TailwindCSS/TailwindUI existing classes
that can be reused easily
internationalization friendly (because we're using a word - required - and not the "*" sign as you often see)
that doesn't reinvent the wheel in some way
that looks like this

For the coder in a hurry, my solution

The gist of it is label_builder.translation.

= f.label :email, required: true, class: "block text-xxs uppercase text-gray-500" do |label_builder|
  = label_builder.translation
  span.ml-2.normal-case.text-orange-400.text-xxs.font-semibold= t("required")
  = f.email_field :email, autocomplete: false, required: true, class: "form-input mt-1 block w-full text-field focus:shadow-outline focus:border-green-300", placeholder: "richard@piedpiper.com"

Note: I use the Slim template language instead of ERB; it's easier to read so I trust that even if you've never heard of it you won't be lost.

For the curious mind, how I got there and why

FAIR WARNING: the rest is not your typical technical article. You already have the solution above, the rest is about how I found the solution. So it's more a story than a guide.

Here I was setting up a simple profile form, adding the proper required: true attributes and looking at it when I realized: how the hell would a user know which fields are required and which aren't?

Like anyone, anytime I see a form, my mind looks for the easy way out and tries to figure out how to hit that submit button as quickly as possible.
This bland form triggered my fill or flight response and I knew I had to do something about it.

Starting point

With a bit of TailwindCSS, here is what it was looking like.

and the code

= f.label :email, required: true, class: "block text-xxs uppercase text-gray-500"
= f.email_field :email, autocomplete: false, required: true, class: "form-input mt-1 block w-full text-field focus:shadow-outline focus:border-green-300", placeholder: "richard@piedpiper.com"

It's as basic as it gets: a label and an email_field with some classes.
I will skip the TailwindCSS explanations, just know that "form-input" comes from a plugin.

Goal check:

✅ using only TailwindCSS/TailwindUI existing classes
❌ that can be reused easily
❌ internationalization friendly
❌ that doesn't reinvent the wheel in some way
❌ that looks like the cover image

Approach n°1: Add a "*" after the email

Often, forms signal that a field is required by appending an asterisk to the label title, which can be done with a bit of CSS.

  .required:after {
    content:" *";
  }

I went to the TailwindCSS docs and couldn't find anything ready-made to handle this.
Sure, I could add it to my stylesheet files, but I already had another idea in mind.
I played a little bit with Basecamp recently as I watched the On Writing Software (well?) videos by DHH. And it reminded me that using the word "required" instead of a simple "*" sign is great to improve clarity.

Approach n°2: Appeal to humanity

This confusing title is a bad pun inspired the method we'll be using in this approach: Model.human_attribute_name.

Since label can take a block to render, it's easy to come up with a first solution.

So I went from

= f.label :email, required: true, class: "block text-xxs uppercase text-gray-500"

= f.label :email, required: true, class: "block text-xxs uppercase text-gray-500" do
  | Email
  span.ml-2.normal-case.text-orange-400.text-xxs.font-semibold required

OK. It looks like the final result, but we're not quite there yet, because both "Email" and "required" are hardcoded.

Goal check:

✅ using only TailwindCSS/TailwindUI existing classes
❌ that can be reused easily
❌ internationalization friendly
❌ that doesn't reinvent the wheel in some way
✅ that looks like the cover image

The "required" text doesn't need much talking about. We just have to replace it with = t("required") and add a translation somewhere, probably in config/locals/en.yml since it will be pretty generic.

en:
  required: required

But what about the email? I needed a solution that would be a bit more generic.
The standard way to look up translations for any attribute is Model.human_attribute_name(:attribute), so I did just that.

= f.label :email, required: true, class: "block text-xxs uppercase text-gray-500" do
  / 👍 Not horrible
  = f.object.class.c(:email)
  span.ml-2.normal-case.text-orange-400.text-xxs.font-semibold= t("required")
  = f.email_field :email, autocomplete: false, required: true, class: "form-input mt-1 block w-full text-field focus:shadow-outline focus:border-green-300", placeholder: "richard@piedpiper.com"

At this point, I am relying on common techniques. A little bit unsatisfying but it gets the job done.

What did I find unsatisfying, you may wonder?

Generally speaking, rails take care of many intricacies you might not think of. When you're replicating part of a method (in our case the part that takes a symbol - :email - and turns it into text - Email -), it's highly likely you're forgetting edge cases or oversimplifying.
It's like using a steering wheel versus ropes tied to the wheels. Sure, it works, you have a direct grip on things, but there's a reason we built an intermediary thingy.

In particular, by doing our own thing instead of relying on rails' wisdom, we're missing out on lazy lookup cleverness.
And in our case, by using Model.human_attribute_name directly, we are reinventing the wheel.

Goal check:

✅ using only TailwindCSS/TailwindUI existing classes
✅ that can be reused easily
✅ internationalization friendly
❌ that doesn't reinvent the wheel in some way
✅ that looks like the cover image

Final approach

Where to go from there? I knew that the label helper was handling the translation at some level, and I wanted to know if you could tap into it.

There was two way to deal with this. The easy way, and the way I did it because… I got carried away.

Let's start with the laborious (but still interesting) way

The easiest way to know how the label helper handles the translation is to look at the source code
Using Dash, I opened the rails source code and found this

def label(method, text = nil, options = {}, &block)
  @template.label(@object_name, method, text, objectify_options(options), &block)
end

I clicked the label call and looked at the definitions found by Github's code navigation (I only discovered recently that Github lets you do that, so I'm mentioning it here in case you didn't know about).

The method's signature of the first row seems to match the one used before, so I followed it and found this, which doesn't do much:

def label(object_name, method, content_or_options = nil, options = nil, &block)
    Tags::Label.new(object_name, method, self, content_or_options, options).render(&block)
end

From there, I followed Tags::Label and finally arrived on the LabelBuilder
Here I started to skim through the code, but I didn't have to go far because, at the very top, I saw a promising def translation.

I went back to the code, added a parameter to the block call that I felt should be named label_builder, and called its translation method.

= f.label :email, required: true, class: "block text-xxs uppercase text-gray-500" do |label_builder|
  / ✨ True magic
  = label_builder.translation
  span.ml-2.normal-case.text-orange-400.text-xxs.font-semibold= t("required")
  = f.email_field :email, autocomplete: false, required: true, class: "form-input mt-1 block w-full text-field focus:shadow-outline focus:border-green-300", placeholder: "richard@piedpiper.com"

This translation is closer to the template engine than the previous solution.

The easy way

Before we go further, here is the easy way to find that same method in less time.

You just have to a) use the console

= f.label :email, required: true, class: "block text-xxs uppercase text-gray-500" do |label_builder|
  - console

b) load the page in your browser, wait for the console to appear, and type label_builder.methods to return the list of the names of methods of our label_builder: :translation is the very first one.

Why didn't I think of that? Force of habits mostly.
I've found a lot of solutions recently by reading code so it was my first instinct. Also, I didn't think it would be that easy, ie that the LabelBuilder would just expose the translation.
But I must admit that the prospect of reading code and learning a thing or two because of it was also appealing. I find that it's always worth my time.

Why is it better and what did we learn?

Remember when I told you that we were missing out on lazy lookup cleverness?
You can reveal it using i18n-debug.

The previous solution using human_attribute_name looks for this key:

en.activerecord.attributes.contact.email

Our new solution first looks for one specific to labels and only falls back on the model one if it's nil.

en.helpers.label.contact.email
en.activerecord.attributes.contact.email

This is way more satisfying 😌 and the end of the original article.

I wanted to not only share my solution but also the tools I use as well as a way to go beyond duck-taping (which to me is any approach up to - and including - the human_attribute_name approach).

At this point you know how to add a "required" text to form labels:

✅ using only TailwindCSS/TailwindUI existing classes
✅ that can be reused easily
✅ internationalization friendly
✅ that doesn't reinvent the wheel in some way
✅ that looks like the cover image

For the Stakhanovites, going further with a Form Builder

I didn't plan to go that far initially, but I couldn't resist once I thought about it 😬

If you're going to do that often, you'll probably want to start customizing form builders in order to make all of this even more reusable, write less code and get even closer to vanilla rails.

Indeed, with a form builder we can simply write something like this:

= f.label :email, required: true, class: "block text-xxs uppercase text-gray-500", required_class: "ml-2 normal-case text-orange-400 text-xxs font-semibold"
= f.email_field :email, autocomplete: false, required: true, class: "form-input mt-1 block w-full text-field focus:shadow-outline focus:border-green-300", placeholder: "richard@piedpiper.com"

If you compare it to our starting point, you'll see that there is only one difference: an extra required_class.

Now, this is 😎.

What would that form builder look like? Here's my take on this. It's the first form builder I write, so if you have more experienced and notice something weird please do tell.

# app/form_builders/requiring_form_builder.rb
class RequiringFormBuilder < ActionView::Helpers::FormBuilder
  def label(method, text = nil, options = {}, &block)
    text_is_options = text.is_a?(Hash)
    required = text_is_options ? text[:required] : options[:required]
    if required
      required_class = text_is_options ? text.delete(:required_class) : options.delete(:required_class)
      super(method, text, options) do |label_builder|
        @template.concat label_builder.translation
        @template.concat @template.content_tag(:span, I18n.t("required", scope: :helpers), class: required_class)
        @template.concat(@template.capture(label_builder, &block)) if block_given?
      end
    else
      super(method, text, options, &block)
    end
  end
end

There are two other things required for this to work.

First, the form_with declaration must declare the builder:

= form_with model: @user, builder: RequiringFormBuilder do |f|

Second, you might have noticed that I use I18n.t("required", scope: :helpers) and not I18n.t("required") as we did before because it seems more appropriate to put that under the helpers namespace (in my case in a file called config/locals/helpers/en.yml). So you need to move that in the proper translation file, or at the minimum to change

en:
  required: required

into

en:
  helpers:
    required: required

I won't go into the details, but I'll point to two parts in the rails code that helped me write this code.

https://github.com/rails/rails/blob/a0e0f0263902896a7aacf703bcab35bee16bdaf8/actionview/lib/action_view/helpers/tags/label.rb#L30 because text can, in fact, be the options
https://github.com/rails/rails/blob/477fae3eb3d3b3bfdbe28586fecb8578c0be4721/actionview/lib/action_view/helpers/form_helper.rb#L1924 because we don't want to break block calling (do |label_builder|)

With this form builder, we can now simply add a required_class to any required label field.

If you enjoyed this article, you can follow me on Twitter @sowenjub.