DEV Community: Daveyon Mayne 😻

Infinite Y-Axis Calendar View Scroll

Daveyon Mayne 😻 — Wed, 03 Jan 2024 06:55:00 +0000

I admired the ScrollView on iOS. When done right, you get a smooth infinite scrolling of the y-axis while it handles loading of data onto the view. A similar design was done for the DayOne iOS app; it's an infinite scroll back in the past as it's a journaling app so that make sense. I'm building a similar app but for farmers for my app called ektarOS (FarmSwop).



# index.html.erb: ie farmswop.com/calendar

<div class="journal-calendar-container">
  <header class="journal-calendar-header bg-earth-50 z-50 dark:bg-gray-850 dark:text-bubble-800 grid grid-cols-7 p-1">
    <span class="journal-calendar-header__item">mon</span>
    <span class="journal-calendar-header__item">tue</span>
    <span class="journal-calendar-header__item">wed</span>
    <span class="journal-calendar-header__item">thu</span>
    <span class="journal-calendar-header__item">fri</span>
    <span class="journal-calendar-header__item">sat</span>
    <span class="journal-calendar-header__item">sun</span>
  </header>

  <div id="journal-container" class="h-screen overflow-y-auto">
    <%= render "journals/calendar/scrollable", direction: "past" %>
    <%= render "journals/calendar/scrollable", direction: "future" %>
  </div>
</div>

As you can see, I'm rendering journals/calendar/scrollable twice; the top one that fetches past data while the other fetches present and future data. Let's take a look at the partial:

views/journals/calendar/scrollable:



<%= turbo_frame_tag "#{direction}_journal_timeline",
  src: journal_timeline_path(direction: direction, month_year: local_assigns[:month_year] || nil ),
  loading: :lazy, target: "_top" do %>
    <p>Loading...</p>
<% end %>

On page load, we make two requests; one for past data and the other for present/future data. journal_timeline_path renders a repeat of views/journals/calendar/scrollable in an odd way:



<%= turbo_frame_tag :"#{@direction}_journal_timeline" do %>
  <div class="flex flex-col flex-grow">

    <% if @direction == "past" %>
      <%= render "journals/calendar/scrollable", month_year: @month_year, direction: @direction %>

      <%= render "shared/journal_calendar",direction: @direction, calendar_data: @calendar_data %>

    <% else %>
      <%= render "shared/journal_calendar", direction: @direction, calendar_data: @calendar_data %>

      <%= render "journals/calendar/scrollable", month_year: @month_year, direction: @direction %>
    <% end %>

  </div>
<% end %>

For past data, I try to keep journals/calendar/scrollable from not being in view until the user scrolls up. It's not perfect as yet, we have to use JavaScript for this section. I'll come to that later.

shared/journal_calendar:



<%= turbo_frame_tag :"#{direction}_journal_timeline" do %>
  <article class="bg-earth-100 dark:bg-gray-850 invisible" data-controller="journal" data-direction="<%= direction %>">
    <div class="bg-earth-50 dark:bg-gray-840 dark:text-bubble-900 px-4 py-1 text-sm font-stdmedium">
      <%= @date.strftime('%B %Y') %>
    </div>
    <div class="flex items-center justify-between overflow-x-auto">
      <table class="w-full">
        <thead>

        </thead>
        <tbody>
          <% calendar_data.each do |week| %>
            <tr>
              <% week.each do |day| %>
                <td class="journal__cell <%= day.present? ? 'journal__cell--on' : 'journal__cell--off' %>">
                  <!-- Your rendered cell -->
                  <%# render "shared/journal_cal_cell", day: %>
                </td>
              <% end %>
            </tr>
          <% end %>
        </tbody>
      </table>
    </div>
  </article>
<% end %>

The Calendar Controller

Calendar days are server-side rendered. No JavaScript is used to render the dates nor its data.



class Journals::CalendarController < ApplicationController  
  def index; end
end

And that's it! Literally! Joking! Journals::CalendarController is only needed to render the index page. If you look back at views/journals/calendar/scrollable, it fetches journal_timeline_path. Here's that controller:



class Journals::TimelineController < ApplicationController
  def index
    @direction = params[:direction]
    @month_year = params[:month_year].present? ? Date.parse(params[:month_year]) : Date.today

    case @direction
    when "past"
      @month_year -= 1.month
    end

    @date = @month_year.beginning_of_month
    @calendar_data = Journal::Timeline.new(start_date: @date, bucket: @bucket).calendar_data

    case @direction
    when "past"
      @month_year -= 1.month
    else
      @month_year += 1.month
    end
  end
end

You may see references to "buckets", they are not relevant to this post. Most of this code I copied directly from my code editor.



class Journal::Timeline
  def initialize(start_date: nil, bucket: nil)
    @start_date = start_date
    @bucket = bucket
  end

  def calendar_data
    generate_calendar_data
  end

  private

    def generate_calendar_data
      calendar_data = []
      current_date = @start_date
      week = []

      # Determine the number of empty cells before the first day of the month
      empty_cells = (current_date.wday - 1) % 7
      empty_cells = 6 if empty_cells < 0

      # Calculate the date of the first day of the current month
      first_day_of_current_month = current_date.beginning_of_month

      # Add days from the previous month, if needed
      empty_cells.downto(1) do |i|
        date = first_day_of_current_month.prev_day(i)
        day_data = initialize_day_data(date)
        week << {} # day_data
      end

      # Generate calendar data for the entire month
      while current_date.month == @start_date.month
        day_data = initialize_day_data(current_date)
        week << day_data

        if current_date.sunday?
          calendar_data << week
          week = []
        end

        current_date = current_date.tomorrow
      end

      # Add the last week to the calendar data
      calendar_data << week unless week.empty?

      calendar_data
    end

    def initialize_day_data(date)
      # Get the data you need by date
      journals = Recording.select do |rec|
        observed_at_date = rec.recordable.observed_at.to_date if rec.recordable.observed_at.present?
        created_at_date = rec.recordable.created_at.to_date

        observed_at_date == date.to_date || created_at_date == date.to_date
      end

      # Your data format
      {
        day: date.day,
        date: date.strftime("%d-%m-%Y"),
        journals: journals
        # Add any other data you need for the day, such as events
      }
    end
end

generate_calendar_data took some time for me to get right. I hope it was well written?

The Stimulus JavaScripts!

Every time shared/journal_calendar gets rendered, we execute some other code:

app/javascript/controllers/journal_controller.js:



import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ['cell']

  connect() {
    const container = document.getElementById('journal-container');
    const scrollTopBefore = container.scrollTop;

    const direction = this.element.dataset.direction;

    const newItemsHeight = this.element.clientHeight; // clientHeight/offsetHeight

    if (direction === 'past') {
      // Adjust the scroll position
      container.scrollTop = scrollTopBefore + newItemsHeight;

      this.element.classList.remove('invisible')

    } else {
       // Not sure I need this anymore.
      this.element.classList.remove('invisible')
    }
  }
}

There's a bug with this JS. While the "past" data scrolls nicely on desktop, not so much on mobile devices. I suspect the issue with getting the height with clientHeight. Any ways, I'll look on that later.

That's all there is for an infinite y-axis scroll. For initialize_day_data > journals, you can put an empty array if you do not have any data and the infinite scrolling should work, but without any data.

Spot any bug(s)? Please let me know!

Have a great day! 👋

Dreaded Notification prompting can only be done from a user gesture

Daveyon Mayne 😻 — Thu, 13 Jul 2023 21:03:48 +0000

You could remove the heavy lifting from your codebase by harnessing the power browsers already give to you, for free, it's the Notification interface available in all modern browsers.

Except Chrome, when using the api with other browsers, you may receive an error message when you push a notification to your users's browser. This is because most modern browsers implement restrictions on displaying notifications without user gestures as a security and user experience measure. There's a workaround for this and I'll explain through the use of coding examples:

Check to see of the user is using a browser other than Chrome
Store message(s) in their localStorage
Listen for a document click then present message to user.

Simple, huh? Here's the code:



// The notification data
const notificationData = {...}

if(navigator.userAgent.indexOf("Firefox") !== -1 || navigator.userAgent.indexOf("Safari") !== -1 && navigator.userAgent.indexOf("Chrome") === -1) {
  // Store message in localStorage as an array
  let notifications = localStorage.getItem("notifications");
  let notificationArray = [];

  if (notifications) {
    // Parse the stored string back to an array
    notificationArray = JSON.parse(notifications);
  }

  // Append the new notification data to the array
  notificationArray.push(notificationData);

  // Save the updated array as a string in localStorage
  localStorage.setItem("notifications", JSON.stringify(notificationArray));

  // Add an document click event to iterate and show notifications: parse string to array before looping
  document.addEventListener("click", () => {
    const storedNotifications = localStorage.getItem("notifications");
    let storedNotificationArray = [];

    if (storedNotifications) {
      // Parse the stored string back to an array
      storedNotificationArray = JSON.parse(storedNotifications);
    }

    // Loop through the stored notifications and show them
    for (const notification of storedNotificationArray) {
      // Display the notification
      this._displayNotification(notification);
    }

    // Clear the notifications from localStorage
    localStorage.removeItem("notifications");
  });
} else {
  // Show the notification straight away: Chrome and others
  this._displayNotification(notificationData)
}

As the I've explained previously, we check to see if the user is using Firefox and Safari. We then store the message as an array and save to localStorage. Should more messages come in, it get appended to the notification array in the localStorage. We that add an event listener to the document and once clicked, we loop notification array then display to the user. After, the array gets removed from localStorage. _displayNotification would be your function that shows the notification:



_displayNotification = (notification) => {
  // Use the notification data (title, body, image, url) to construct and show the notification
  const n = new Notification(notification.title, { body: notification.body, icon: notification.image, requireInteraction: true });

  n.onclick = (event) => {
    event.preventDefault()

    window.open(notification.url, "_blank")
  }
};

Assuming you already have the user's permission, this should works as is.

What if the user's computer is off or does not have the browser open on your webpage? You've need a different approach such as using a ServiceWorker or your app should know that the user is offline and do something. Notification can get complex but this post is to get around the error message and it works well. I have yet to try other browsers such as Opera. Please let me know what you think in the comments.

Here's a shorter version on my Twitter post 👉 https://twitter.com/sylarruby/status/1679598870307696641?s=20

Bye for now ✌🏼

Partials used for turbo streaming must be free of global references.

Daveyon Mayne 😻 — Sat, 08 Jul 2023 13:21:02 +0000

It's never a good idea for partials to reference a global variable, such variable would be current_user. DHH mentioned this already and I'll show you how to gain access to the current user's information. I do it by storing information of the current_user in a meta:


<head>
  <meta name="current_user" content="<%= current_user.json_info %>">
</head>

json_info would contain the information that you need:

# user.rb

[..]

def json_info
  {
    id: self.id, 
    name: <NAME>,
    # Maybe full url to their avatar?
    avatar_url: Rails.application.routes.url_helpers.rails_blob_path(self.avatar, only_path: true)
  }.to_json
end

Basic stuff. With that, our current_user object lives inside the meta of the document head.

This partial will be a Stimulus controller and our partial is called _message.html.erb that lives inside the shared folder:

<article 
  data-controller="message" 
  id="<%= dom_id(message) %>" 
  data-author-id="<%= message.user.id %>">
   <%= message.body %>
</article>

Notice I have here data-author-id, very important, and I've connected a Stimulus controller. Every time this partial get's rendered in the DOM, the connect function gets triggered:

// message_controller.js

import { Controller } from '@hotwired/stimulus'

export default class extends Controller {

  connect() {
    const currentUserBlob = this._getMetaValue('current_user');
    const id = JSON.parse(currentUserBlob).id

    const authorId = this.element.getAttribute('data-author-id')

    // Do something when authorId matches/does not match id.
    // This could be hiding/removing an element or something else.
  }

  _getMetaValue = (name) => {
    const element = document.head.querySelector(`meta[name="${name}"]`)
    return element?.getAttribute("content")
  }

}

Our message model message.rb would look something like this:


[..]

belongs_to :user
belongs_to :message_thread
has_rich_text :body

after_create_commit do
  # We cannot pass current user
  broadcast_append_to(self.message_thread, target: self.message_thread, partial: "shared/message", locals: { message: self })
end

message.rb is just an high-level example showing only the message object that was passed in and nothing else. Depending on what you're doing with "current_user", you'd implement that logic in the Stimulus controller's connect function.

The entire page may look like this:


<%= turbo_stream_from @thread %>

<section id="<%= dom_id(@thread) %>">
  <% @messages.each do |message|
    <%= render "shared/message", message: message %>
  <% end %>
</section>

As a rule of thumb, partials should be free from global references/objects but where a partial is used with ApplicationRenderer, you must connect it with a Stimulus controller to gain access to the current_user.

🎉 Self-promotion 🎉

I'm building Farm Swop, a platform for farmers where farmers can connect with nearby farmers to share/exchange support, machinery etc. It's in active development. Feel free to join to see my progress while I BuildInPublic.

Photo by Jill Heyer on Unsplash

Let your customers subscribe to an out of stock product with Spree Commerce -- Refactored --

Daveyon Mayne 😻 — Sun, 19 Mar 2023 11:53:01 +0000

This is a refactored version of my original post here that uses the spree_frontend. To be able to follow along, please take 2-3 minutes to have a read. v1, as I would call it, uses an outdated version of Spree Commerce. v2 (this post) now uses Spree v4.5.x which uses the spree_backend gem.

I've updated StockItemsControllerDecorator

# https://github.com/spree/spree_backend/blob/main/app/controllers/spree/admin/stock_items_controller.rb
module Spree
  module Admin
    module StockItemsControllerDecorator
      # renamed from NotifyCustomersHelper
      include NotifyCustomers

      def self.prepended(base)
        base.before_action :process_notifiees_on_stock_item, only: :update

        # We have not taken into account should stock_movement.save fails.
        # see https://github.com/spree/spree_backend/blob/main/app/controllers/spree/admin/stock_items_controller.rb#L13
        base.before_action :process_notifiees_on_stock_movement, only: :create

        # We don't need to track when deleted as the "track Inventory" can be checked when deleted.
        # For this, look at Spree::Admin::VariantsIncludingMasterController#update
        # base.before_action :notify_notifiees, only: :destroy
      end 
    end
  end
end
::Spree::Admin::StockItemsController.prepend Spree::Admin::StockItemsControllerDecorator if ::Spree::Admin::StockItemsController.included_modules.exclude?(Spree::Admin::StockItemsControllerDecorator)

VariantsIncludingMasterControllerDecorator was also refactored as we will only send an email when no longer tracking inventory:

module Spree
  module Admin
    module VariantsIncludingMasterControllerDecorator
      include NotifyCustomers

      def self.prepended(base)
        # Defined in NotifyCustomers. Continue reading...
        base.before_action :notify_notifiees, only: :update
      end
    end
  end
end
::Spree::Admin::VariantsIncludingMasterController.prepend Spree::Admin::VariantsIncludingMasterControllerDecorator if ::Spree::Admin::VariantsIncludingMasterController.included_modules.exclude?(Spree::Admin::VariantsIncludingMasterControllerDecorator)

I've also refactored NotifyCustomers and instead look for the variant instead of the product:

module NotifyCustomers
  private
    # We've made the executive decision by not keeping stocks.
    # Alert all customers that the product is available to purchase.
    def notify_notifiees 
      variant_id = params[:id]
      not_tracking = !ActiveRecord::Type::Boolean.new.cast(
        params[:variant][:track_inventory]
      )

      not_tracking && email_all_notifiees(variant_id)
    end

    def process_notifiees_on_stock_movement
      quantity = params[:stock_movement][:quantity].to_i
      variant_id = params[:variant_id]

      unless quantity.zero?
        email_all_notifiees(variant_id)
      end

    end

    def email_all_notifiees(variant_id)
      notifiees = lookup_notifiees_by(variant_id)

      send_notification_email(notifiees)

      # We said we'd delete their email address
      notifiees.destroy_all
    end

    def process_notifiees_on_stock_item
      # Backorderable: boolean
      # stock_item.backorderable

      # Number of items in stock: integer
      # stock_item.count_on_hand

      unless stock_item.count_on_hand.zero?
        variant_id = stock_item.variant.id
        email_all_notifiees(variant_id)
      end
    end

    def lookup_notifiees_by(variant_id)
        Spree::VariantNotification.where(variant_id: variant_id)
    end

    def send_notification_email(notifiees)
      if notifiees.present?
        emails_to_send = notifiees.pluck(:email)
        puts "---- SENDING EMAIL TO #{emails_to_send.length} email addresses (plural for now)"

        # Now send the email
        # You'll need to implement a mailer for this
      end
    end
end

Migration file was also updated (I'm doing this in a new project):

class CreateSpreeVariantNotifications < ActiveRecord::Migration[7.0]
  def change
    create_table :spree_variant_notifications do |t|
      t.references  :user
      t.references  :variant, null: false
      t.string      :email, null: false

      t.timestamps
    end
  end
end

Updated models:

module Spree
  class VariantNotification < ApplicationRecord
    validates   :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }

    # Optional as a user doesnt have to be signed in
    belongs_to  :user, class_name: 'Spree::User', optional: true

    belongs_to  :variant, class_name: 'Spree::Variant'
  end
end

module Spree
  module VariantDecorator
    def self.prepended(base)
      base.has_many :notifications, class_name: 'Spree::VariantNotification', foreign_key: 'variant_id', dependent: :destroy
    end
  end
end

::Spree::Variant.prepend Spree::VariantDecorator if ::Spree::Variant.included_modules.exclude?(Spree::VariantDecorator)

Also the place where the email gets processed into our database, the controller:

module Spree
  # Though belongs to a variant, we'll keep this for the product
  module Products
    class NotifyController < Spree::StoreController
      before_action :set_variant
      include ActionView::Helpers::TextHelper

      # Does not uses a layout
      layout false

      def notify_me
        email = strip_tags(notify_params[:email])

        @notif = @variant.notifications.find_or_create_by(email: email) do |perm|
                    # user_id can be null
                    perm.user_id = spree_current_user&.id || notify_params[:user_id]
                  end

          respond_to do |format|

            if @notif.save
              format.turbo_stream
            else
              format.html { redirect_to spree.product_path(@variant.product), alert: "Something went wrong", status: 422 }
            end
          end
      end


      private
        def notify_params
          params.fetch(:product_notification, {}).permit(:email)
        end

        def set_variant
          @variant = Spree::Variant.find_by(id: params[:variant_id])
          unless @variant.present?
            redirect_to root_path
          end
        end
    end
  end
end

# Route updated to:
post '/products/:variant_id/notify', to: 'products/notify#notify_me', as: 'variant_notify'

_notify_me_when_available.html, inside _cart_form but placed outside the order form was also updated:

<%= form_with(
    scope: :product_notification, 
    url: spree.variant_notify_path(variant),
    data: {
      controller: "reset-form",
      action: "turbo:submit-end->reset-form#reset"
    },
    id: dom_id(variant, :notify)) do |form| %>
  <%= form.label :email, "Notify me when in stock" %>
  <%= form.email_field :email, class: 'spree-flat-input', placeholder: "Enter your email address", required: true %>
  <%= form.submit "Notify me", class: "btn btn-primary w-100 text-uppercase font-weight-bold mt-2" %>
  <p class="mt-2 text-sm">After this notification, your email address will be deleted and not used again.</p>
<% end %>

I'm using turbo in this new project of mine. When form gets submitted, I clear the input field and when successful, I update the DOM with a partial (spree/shared/_variant_notify_success):

<div class="p-3 text-center bg-green-600 text-white sm:text-base text-sm">
  <p>Great! We'll send you a one-time email when item becomes available.</p>
</div>

Using..

<%= turbo_stream.replace dom_id(@variant, :notify) do %>
  <%= render "spree/shared/variant_notify_success" %>
<% end %>

...outside the order form:

<%# Outside order form %>
<% unless is_product_available_in_currency && @product.can_supply? %>
  <%= render 'spree/shared/notify_me_when_available', variant: default_variant %>
<% end %>

Additional work is needed to show/hide the notification form should a variant is out of stock. My example will only display the notification form when product cannot supply.

Spree frontend has an event lister for .product-variants-variant-values-radio as seen here. You could put your logic there to show/hide the notification form. Here's the logic:

Inside your click event for OPTION_VALUE_SELECTOR (in your own js file or use Stimulus):

With the selected variant_id, parse the data for data-variants on the cart from. Inside the array of data-variants, check that the variant is purchasable, using variants.find(o.id == variant_id).purchasable, for example. Based on true or false, show/hide the notification form. I got purchasable from here.

That should be all for now. At the time of this post, I have not implement show/hide when an option is selected. Live demo here.

User's initial as an avatar image

Daveyon Mayne 😻 — Fri, 28 Oct 2022 16:33:09 +0000

Basecamp does something like this but I do not know exactly how they've done it. This is my take on using an image for the user's avatar, uploaded using Active Storage.

My profile model is setup with an has_one_attached:

# profile.rb

has_one_attached :avatar
belongs_to :user

User model is not important here but it looks like this:

# user.rb

has_one :profile

The logic is that once the user has registered with their name, we generate the image initial then upload it.


def generate_avatar(user)
  # The first character from the user's name.
  # Basecamp does some extra checks to check for numbers
  # and alphabet from the name. When invalid, they
  # return a question mark: ?
  initial = user.profile.name.first.upcase

  # A colour that will not change for the user: red, green, hex value etc
  colour = user.default_colour

  # A HTML markup with background color; inline or in the css file
  html = "<div style='background:#{colour};width:280px;height:280px' class='custom_avatar'><span>#{initial}</span></div>"

  # See rest of post
  kit = IMGKit.new(html, :width => 280, :quality => 50)

  # A custom stylesheet
  kit.stylesheets << "#{Rails.root}/app/assets/stylesheets_custom/custom_avatar.css"

  # Store image in a temp folder
  file_path = Tempfile.new(["file", '.jpg']).path
  kit.to_file(file_path)

  # Upload the image
  user.profile.avatar.attach(io: File.open(file_path), filename: 'avatar.jpg')
end

The setup

Gemfile.rb:

# https://github.com/csquared/IMGKit
gem 'imgkit'
gem 'wkhtmltoimage-binary'

Run bundle install to install the gems above. I'm using IMGKit.

Custom Stylesheet

I put this in app/stylesheets_custom/*


* {
  margin: 0;
  padding: 0;
}
.custom_avatar {
  width: 280px;
  height: 280px;
  padding: 0;
  margin: 0;
  font-size: 8rem;
  font-weight: bold;
  color: white;
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-align: center;
      -ms-flex-align: center;
          align-items: center;
  -webkit-box-pack: center;
      -ms-flex-pack: center;
          justify-content: center;
}

For reusable methods, I create a module and place in: controllers/concerns/*:

# user_avatar_image.rb

module UserAvatarImage

  def random_colour
    ["#A9294F", "#ED6663", "#389393", "#D82148", "#8C5425", "#6F38C5"].sample
  end

  def generate_avatar(user)
    # The first character from the user's name
    initial = user.profile.name.first.upcase

    # A colour that will not change for the user: red, green, hex value etc
    colour = user.default_colour

    # A HTML markup with background color; inline or in the css file
    html = "<div style='background:#{colour};width:280px;height:280px' class='custom_avatar'><span>#{initial}</span></div>"

    # See rest of post
    kit = IMGKit.new(html, :width => 280, :quality => 50)

    # A custom style sheet
    kit.stylesheets << "#{Rails.root}/app/assets/stylesheets_custom/custom_avatar.css"

    # Store image in a temp folder
    file_path = Tempfile.new(["file", '.jpg']).path
    kit.to_file(file_path)

    # Upload the image
    user.profile.avatar.attach(io: File.open(file_path), filename: 'avatar.jpg')
  end
end

The Flow

During user registration, random_colour is used to set a random colour. Next, we call generate_avatar(resource) to generate and upload the image. You would call generate_avatar every time the user changes their name 😉

Feel free to to modify the font size and dimensions for the image. Enjoy!

Using Draft.js as a single-line input

Daveyon Mayne 😻 — Mon, 11 Oct 2021 17:03:00 +0000

Hey all 👋🏼 Today I want to share with you a very simple code on how to use Draft.js as a single line input.

import Draft, { Editor, ... } from 'draft-js'

const keyBindingFn = (e) => {
  if (!e.metaKey && e.code === 'Enter') {
    // Function to execute...
    return false
  }

  // Return Draft's default command for this key.
  return Draft.getDefaultKeyBinding(e)
}

<Editor 
  [..]
  keyBindingFn={keyBindingFn}
/>

The code above will add line breaks should the user presses the command key (mac) + enter key. Nothing will happen if the enter button alone is pressed. You could then execute a function to save the entered value.

Note the user could copy/paste inside the editor. For my setup, I'm ok with that.

✌🏼

Let your customers subscribe to an out of stock product with Spree Commerce

Daveyon Mayne 😻 — Sat, 06 Mar 2021 10:56:26 +0000

----- Updated 👉 Refactored version ------

Sometimes it's good to have your customers be notified when an item they wish to purchase comes in stock. In reality they'd go elsewhere to buy, right? If it's available elsewhere, cheaper, they'd pretty much go somewhere else to purchase. But what if what you sell is unique, of better quality or your customer loves your support or you in general? We're going to implement an out of stock email notification system; I call this "notifiees". The beauty of this is that we can name or variables/definitions just the way we like 😂

Before diving right in, let's see how Spree updates the product quantity. The "amount of items in stock" is what we want to target although most businesses do not use "track inventory". We'll come to that in future explanation.

If your business relies on inventory/stock, then this tutorial is for you.

In the StockItemsController, we want to "watch" three actions:

update
create
destroy

Update

When we update a stock item, we should email all customers, providing the quantity is more then 0 🙄

Create

Again, send an email to all customers when stock movement is added.

Destroy

We've decided that we're no longer tracking inventory. This enables the add to cart button so why not email all customers.

# see https://github.com/spree/spree/blob/master/backend/app/controllers/spree/admin/stock_items_controller.rb
module Spree
    module Admin
        module StockItemsControllerDecorator
            def self.prepended(base)
                base.before_action :process_notifiees_on_stock_item, only: :update

                # We have not taken into account should stock_movement.save fails.
                # see https://github.com/spree/spree/blob/master/backend/app/controllers/spree/admin/stock_items_controller.rb#L13
                base.before_action :process_notifiees_on_stock_movement, only: :create

                base.before_action :notify_notifiees, only: :destroy
            end



            private
                # We've made the executive decision by not keeping stocks.
                # Alert all customers that the product is available to purchase.
                def notify_notifiees
                    variant_id = stock_item.variant.id

                    email_all_notifiees(variant_id)
                end

                def process_notifiees_on_stock_movement
                    quantity = params[:stock_movement][:quantity].to_i
                    variant_id = params[:variant_id]

                    if quantity > 0
                        email_all_notifiees(variant_id)
                    end

                end

                def email_all_notifiees(variant_id)
                    product_id = Spree::Variant.find(variant_id).product.id

                    notifiees = lookup_notifiees_by(product_id)

                    send_notification_email(notifiees)

                    # We said we'd delete their email address
                    notifiees.destroy_all
                end

                def process_notifiees_on_stock_item
                    # Backorderable: boolean
                    # stock_item.backorderable

                    # Number of items in stock: integer
                    # stock_item.count_on_hand

                    if stock_item.count_on_hand > 0
                        variant_id = stock_item.variant.id
                        email_all_notifiees(variant_id)
                    end
                end

                def lookup_notifiees_by(product_id)
                    ProductNotification.where(product_id: product_id)
                end

                def send_notification_email(notifiees)
                    if notifiees.present?
                        emails_to_send = notifiees.pluck(:email)
                        # send the email
                    end
                end
        end
    end
end
::Spree::Admin::StockItemsController.prepend Spree::Admin::StockItemsControllerDecorator if ::Spree::Admin::StockItemsController.included_modules.exclude?(Spree::Admin::StockItemsControllerDecorator)

This logic does not take into account where the customer would subscribe to the variant but instead the product itself. Ideally you'd want to change this code to suite your business logic. My online store won't be using different types of variants but as I go along, it will.

In the code you'll notice I have ProductNotification. ProductNotification model is where I save the "notifiees". I save their email address, product id (you may want to save the variant instead, I may change this up) and, optionally, a user id.

Migration:

class CreateProductNotifications < ActiveRecord::Migration[6.1]
  def change
    create_table :product_notifications do |t|
      t.references  :user, null: true
      t.references  :product
      t.string      :email

      t.timestamps
    end
  end
end

Model:

class ProductNotification < ApplicationRecord
    validates   :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP } 
    belongs_to  :user, class_name: 'Spree::User', optional: true
    belongs_to  :product, class_name: 'Spree::Product'
end

The user is optional because I want guests to also subscribe and if a user is logged in, it will use their user id.

Spree Product Model

module Spree
    module ProductDecorator
        def self.prepended(base)
            base.has_many :product_notifications, class_name: 'ProductNotification', foreign_key: 'product_id', dependent: :destroy
        end
    end
end

::Spree::Product.prepend Spree::ProductDecorator if ::Spree::Product.included_modules.exclude?(Spree::ProductDecorator)

Controller:

class Spree::Products::NotifyController < ApplicationController
    include ActionView::Helpers::TextHelper

    layout false

    def notify_me
        email = strip_tags(notify_params[:email])

        @notif = ProductNotification.find_or_create_by(email: email) do |perm|
            perm.product_id = notify_params[:product_id]
            perm.user_id = notify_params[:user_id]
        end

        if @notif.save
            @notif_saved = true
        else
            @notif_saved = false
        end
    end

    private
        def notify_params
            params.require(:product_notification).permit(
                :email,
                :product_id
            ).tap do |p|
                # Overkill to have this here, I know.
                p[:user_id] = spree_current_user ? spree_current_user.id : nil
            end
        end
end

Routes

I save all routes under Spree::Core::Engine.add_routes do block:

[..]

Spree::Core::Engine.add_routes do
  [..]
  post '/products/notify', to: 'products/notify#notify_me', as: 'product_notify'
  [..]
end

Frontend

For the frontend, I modify the _cart_form.html and my notify form is shown when I cannot supply:

[..]
<% if !@product.can_supply? %>
  <%= render 'notify_me_when_available' %>
<% end %>

And inside _notify_me_when_available.html.erb:

<form
    data-controller="product-notify"
    data-action="ajax:success->product-notify#result"
    class="product-notify-me mt-4" data-remote="true" action="<%= spree.product_notify_path %>" method="post">
    <input
        type="hidden"
        name="product_notification[product_id]"
        value="<%= @product.id %>"
    />
    <div class="form-group mb-2">
        <label>Notify me when in stock</label>
        <input 
            name="product_notification[email]"
            data-product-notify-target="email"
            class="spree-flat-input" 
            type="text" placeholder="Enter your email address" 
        />    
    </div>
    <span class="product-description">Your email address will only be used for this notification, after which it gets deleted.</span>
    <div>
        <button class="btn btn-primary w-100 text-uppercase font-weight-bold mt-2">Notify me</button>
    </div>
    <div data-product-notify-target="display">
    </div>
</form>

I haven't change things up to use rails form elements as yet but you should. I use Stimulus here, you really don't need to. I'm only making an ajax request to the above controller, passing in the product_id and email then update the UI if any errors.

Inside views/spree/products/notify/notify_me.html.erb:

<%# This is server-rendered %>

<% if @notif_saved %>
    <div class="alert alert-success">
        Great! We'll send you a one-time email when item becomes available.
    </div>
<% else %>
    <div class="alert alert-danger">
        Oops! You may have provided an invalid email address.
    </div>
<% end %>

Stimulus Controller:

import { Controller } from "stimulus"

export default class extends Controller {
  static targets = [ "display", "email" ]

  result(event) {
    const data = event.detail[0].body.innerHTML
    if (data.length > 0) {
      this.emailTarget.value = ""
      return this.displayTarget.innerHTML = data
    }
  }
}

Using Stimulus for this is overkill as you could achieve what you want with a simple, plain JavaScript. If you want to use Stimulus, be sure to import the js file in views/spree/shared/_head.html.erb

At this stage, when you save an email address, you should see this:

Show the notifees count

To see the total amount of potential customers watching your product, in views/spree/admin/products/index.html.erb, within the loop, inside the table just add:

 <td class="notify"><%= product.product_notifications.count %></td>

Accidentally sending out email

You may want to put a confirmation action on "backordable" as whenever that's ticked/unticked, emails will be sent out 😁

Big Issue

There's a flaw to this implementation. Should you untick/tick "Track Inventory", these actions will never get triggered because that action is located at Spree::Admin::VariantsIncludingMasterController#update which points to here.

Conclusion

I'm still scratching the surface on what Spree Commerce is capable of. I don't feel this implementation is perfect but it's a starting point for me. I will find a better way in doing this but I don't want to go to the Rails event path to watch for database updates. If anyone has a better solution, please let me know. For now, I'll use this method, change the code to have customers subscribe to variant id instead of the product id.

EDIT

Write once, use everywhere. We need or logic in VariantsIncludingMasterController so let's move our code from StockItemsControllerDecorator into a helper method:

module NotifyCustomersHelper
    # We've made the executive decision by not keeping stocks.
    # Alert all customers that the product is available to purchase.
    def notify_notifiees
        variant_id = stock_item.variant.id

        email_all_notifiees(variant_id)
    end

    def process_notifiees_on_stock_movement
        quantity = params[:stock_movement][:quantity].to_i
        variant_id = params[:variant_id]

        if quantity > 0
            email_all_notifiees(variant_id)
        end

    end

    def email_all_notifiees(variant_id)
        product_id = Spree::Variant.find(variant_id).product.id

        notifiees = lookup_notifiees_by(product_id)

        send_notification_email(notifiees)

        # We said we'd delete their email address
        notifiees.destroy_all
    end

    def process_notifiees_on_stock_item
        # Backorderable: boolean
        # stock_item.backorderable

        # Number of items in stock: integer
        # stock_item.count_on_hand

        if stock_item.count_on_hand > 0
            variant_id = stock_item.variant.id
            email_all_notifiees(variant_id)
        end
    end

    def lookup_notifiees_by(product_id)
        ProductNotification.where(product_id: product_id)
    end

    def send_notification_email(notifiees)
        if notifiees.present?
            emails_to_send = notifiees.pluck(:email)
            # send the email
        end
    end
end

Now, our StockItemsControllerDecorator becomes:

# see https://github.com/spree/spree/blob/master/backend/app/controllers/spree/admin/stock_items_controller.rb
module Spree
    module Admin
        module StockItemsControllerDecorator
            include NotifyCustomersHelper

            def self.prepended(base)
                base.before_action :process_notifiees_on_stock_item, only: :update

                # We have not taken into account should stock_movement.save fails.
                # see https://github.com/spree/spree/blob/master/backend/app/controllers/spree/admin/stock_items_controller.rb#L13
                base.before_action :process_notifiees_on_stock_movement, only: :create

                base.before_action :notify_notifiees, only: :destroy
            end
        end
    end
end
::Spree::Admin::StockItemsController.prepend Spree::Admin::StockItemsControllerDecorator if ::Spree::Admin::StockItemsController.included_modules.exclude?(Spree::Admin::StockItemsControllerDecorator)

Next, create VariantsIncludingMasterControllerDecorator inside spree/admin/variants_including_master_controller_decorator.rb:

# See: https://github.com/spree/spree/blob/master/backend/app/controllers/spree/admin/variants_including_master_controller.rb
module Spree
    module Admin
        module VariantsIncludingMasterControllerDecorator
            include NotifyCustomersHelper

            def self.prepended(base)
                base.before_action :send_notification_email_on_inventory_change, only: :update
            end

            def send_notification_email_on_inventory_change
                variant_id = params[:id].to_i
                track_inventory = params[:variant][:track_inventory]

                # If we're no longer tracking, send email
                # track_inventory comes in the form of string "true" or "false"
                if track_inventory == 'false'
                    email_all_notifiees(variant_id)
                end
            end
        end
    end
end
::Spree::Admin::VariantsIncludingMasterController.prepend Spree::Admin::VariantsIncludingMasterControllerDecorator if ::Spree::Admin::VariantsIncludingMasterController.included_modules.exclude?(Spree::Admin::VariantsIncludingMasterControllerDecorator)

Now when we no longer track the inventory, all customers get an email notification. Be careful with this approach. You may accidentally unticked/ticked these boxes which triggers an email to send to all "watchable" customers. You may want to create a dedicated button for this action.

Homework

You will need to pass the product that the customer was watching to the send_notification_email function. In the email, your customer would click a link that takes them directly to the product page.

Persisting Data in CoreData using SwiftUI.

Daveyon Mayne 😻 — Sun, 14 Feb 2021 13:14:42 +0000

I've tasked myself with learning Swift, Swift 5 to be exact, though I've tried to replicate Apple's Calendar app using Swift 2 many moons ago which did worked. Things has changed since and now I wanted to add another programming language to my list of programming stack.

Reintroduction

My name is Daveyon Mayne and I'm a software engineer at RTC Automotive Solutions. My core work is working on our in-house software called CloseIt for car dealers/dealerships.

Imagine you have a form where your customer fills out long form by taking the information from their customer face-to-face or over the phone or via any other medium and your user accidentally closes the form. All data will be lost where your user now use the phrase "erm… could I take your name, age etc again please?" They've lost the data entered before saving. As good programmers we should always persist the data when any data is entered or removed. Ever seen few apps present you with "Saving draft…"? Yes, as you type, your data is saved into a database somewhere. This could be locally or remotely. I'll be skipping the boring stuff as code if life.

I'll assume you've created a new project with CoreData selected. If not, "youtube" some videos on how to enable CoreData. I'm using Xcode 12.

import SwiftUI

struct CreateCustomerView: View {
    @StateObject private var customerForm = CustomerDraftFormFields()

        // We could move this in CustomerDraftFormFields class 
        // and keep our view... clean? 🤷🏽
        let titles = ["Mr", "Miss", "Mrs", "Dr"]


        var body: some View {
            // I'm not using a NavigationView here. You can.
            // You can use Form or List here. I use List because of styling
            List {
                // I use a Group because my List has more than 10 items
                // For this example, you do not need it
                Group {
                    Section {
                        Picker("Title", selection: $customerForm.title, content: {
                            ForEach(titles, id: \.self) {title in
                                Text(title).tag(title)
                            }
                        })

                        TextField("First Name", text: $customerForm.firstName)
                            .disableAutocorrection(true)
                        TextField("Last Name", text: $customerForm.surname)
                            .disableAutocorrection(true)
                    }
                }
            }
        }
}

With that little amount of setup, you should have a basic view to work with. You will have some errors so let's fix that. We need a CustomerDraftFormFields class:

import Foundation

class CustomerDraftFormFields: ObservableObject {
    @Published var title: String = ""
    @Published var firstName: String = ""
    @Published var surname: String = ""

    // It looks much better to keep this here.
    let titles = ["Mr", "Miss", "Mrs", "Dr"]
}

Let's make a slight update to how we loop the titles:

[...]

Section {
    Picker("Title", selection: $customerForm.title, content: {
        ForEach(self.customerForm.titles, id: \.self) {title in
            Text(title).tag(title)
        }
    })

    [...]
}

Listen For State Change

There needs to be a way to listen for some sort of events when any of our form fields change. To do this, we add didSet on each of our fields we are listening for data change.

class CustomerDraftFormFields: ObservableObject {
    @Published var title: String = "" {
        didSet {
            print(title)
        }
    }
    @Published var firstName: String = "" {
        didSet {
            print(firstName)
        }
    }
    @Published var surname: String = "" {
        didSet {
            print(surname)
        }
    }

    [...]
}

Making a change to either fields, we get a print of the value. didSet runs after the property was set and willSet is.... yes, it runs before the property was set.

CoreData

I won't be going through the data setup. I'll assume that's already been taken cared of and you have an entity called DraftCustomers. Call this what ever you like but for this example, we'll use DraftCustomers. Update your class file to import CoreData:

import Foundation
import CoreData

[...]

Now we need to pre-populate the saved values from CoreData to our form fields, if any:

import Foundation
import CoreData

class CustomerDraftFormFields: ObservableObject {
    // Make reference to our context
    private let viewContext = PersistenceController.shared.container.viewContext
    private let fetchRequest: NSFetchRequest<DraftCustomers> = DraftCustomers.fetchRequest()

    [...]

    // Pre-populate the values on first load.
    init() {
        // Only include the first record in the array.
        // fetchRequest will be an array containing only one record (the first)
        fetchRequest.fetchLimit = 1

        do {
            // If there's an error, catch will active
            let customers = try viewContext.fetch(fetchRequest)

            if customers.count == 1 {
                title = customers.first?.title ?? ""
                firstName = customers.first?.firstName ?? ""
                surname = customers.first?.surname ?? ""
            }

        } catch {
            let error = error as NSError
            fatalError("Could not fetch draft customer: \(error)")
        }
    }
}

With just that amount of setup, our form fields should be pre-populated. We haven't saved anything as yet so nothing will be shown. Let's save some data. Still in our class:

[...]

private func saveOrUpdateDraft(column: String, value: Any) {
    fetchRequest.fetchLimit = 1

    do {
        let customers = try viewContext.fetch(fetchRequest)

        if customers.count == 1 {
            let customer = customers[0] as NSManagedObject
            customer.setValue(value, forKey: column)

            // Update the entity record
            try viewContext.save()
        } else {
            let customer = DraftCustomers(context: viewContext)
            customer.setValue(value, forKey: column)

            // Create a new entity record
            try viewContext.save()
        }
    } catch {
        let error = error as NSError
        fatalError("Could not save customer as draft: \(error)")
    }
}

We've defined a function called saveOrUpdateDraft(...). The sole purpose of this function is to update a record or create a new record if not found. When you first run this function, it will (should) save the data to our database, but not just yet. Let's update our didSet:

@Published var title: String = "" {
    didSet {
        saveOrUpdateDraft(column: "title", value: title)
    }
}

@Published var firstName: String = "" {
    didSet {
        saveOrUpdateDraft(column: "firstName", value: firstName)
    }
}

@Published var surname: String = "" {
    didSet {
        saveOrUpdateDraft(column: "surname", value: surname)
    }
}

[...]

Every time we update our form fields, saveOrUpdateDraft will run. In the code we specified the column and its value to be entered (created or updated).

You may have a more complex setup but you get a basic idea on how to save or updating a data if already exists in the database.

Improvements

It's still my early days in learning Xcode + Swift. Could this be refactored or refactor for less performance hit? Let me know and I'll update where needed.

Live query render with Rails 6 and Stimulus JS

Daveyon Mayne 😻 — Thu, 20 Aug 2020 10:47:54 +0000

I thought I'd give Stimulus another try with a side project I'm working on. This time, I only wanted a "splash" of JavaScript magic here and there while I keep our Lord and Saviour in mind, DHH, when designing.

DHH talks about his love for server-side rendering and how to break down your controller logic into what I call, "micro-controllers". This approach makes much sense, to me.

I'm coming from a React frontend development where I separate the client from the server (api). Everything is done through Restful fetching which returns json. When doing a search/query, you fetch the data then update your state with the returned data and that's how you'd implement a live query. A live query is when you have an input field, the user makes a query and the list updates instantly or, a dropdown is populated with the results. Things work differently with jQuery or Stimulus. In our case, we'll be using Stimulus.

Perquisites:

You have Rails 5+ installed
You have Stimulus installed
You do not have jQuery installed - 😁 🥳 - Ok, you can but not needed

We won't be using any js.erb files here since we're using Stimulus. If Basecamp doesn't uses it, I thought I'd follow suit.

Let's say we have a URL /customers, and a controller called customers_controller.rb:

# before_action :authenticate_user! # For Devise
[..]

def index
  @customers = Customer.all.limit(100)
end

[..]

And our views views/customers/index.html.erb:

<main>
  <!-- Filter section -->
  <section>
    <input type="text" name="query" value="" placeholder="Search" />
  </section>

  <!-- Results section -->
  <section data-target="customers.display">
   <%= render partial: 'shared/customer_row', locals: {customers: @customers}  %>
  </section>
</main>

Partials

Inside views/shared/_customer_row.html.erb:

<ul>
  <% customers.each do | customer | %>
    <li><%= customer.first_name + ' ' + customer.surname %></li> 
  <% end %>
</ul>

With this minimal setup, we should see a text input field and a list of customers.

JS Magic with Stimulus

As the user types in our text field (input), we need to submit that data to the server (controller). To do that, we need few things:

A stimulus controller customers_controller.js
a form

// Stimulus controller
import { Controller } from "stimulus"
import Rails from "@rails/ujs"

export default class extends Controller {
  static targets = [ "form", "query", "display"]

  connect() {
    // Depending on your setup
    // you may need to call
    // Rails.start()
    console.log('Hello from customers controller - js')
  }

  search(event) {
    // You could also use
    // const query = this.queryTarget.value
    // Your call.
    const query = event.target.value.toLowerCase()
    console.log(query)
  }

  result(event) {}

  error(event) {
    console.log(event)
  }
}

I won't go into how Stimulus works but do have a read on their reference.

Let's update the html:

<main data-controller="customers">
  <!-- Filter section -->
  <section>
    <form
      data-action="ajax:success->customers#result"
      data-action="ajax:error->customers#error"
      data-target="customer.form"
      data-remote="true"
      method="post"
      action=""
    >
      <input
        data-action="keyup->customers#search"
        data-target="customers.query"
        type="text" 
        name="query" 
        value=""
        placeholder="Search"
      />
    </form>
  </section>

  <!-- Results section -->
  [..]
</main>

Refreshing the page then check you browser console, you'd see the message "Hello from customers controller - js". If not, stop and debug you have Stimulus installed correctly and the controller name is present on your html element: data-controller="customers". When entering a value in the input, you should see what you've typed being logged in your browser console.

Micro Controllers

This post talks about how DHH organizes his Rails Controllers. We'll use same principles here.

Inside our rails app controllers/customers/filter_controller.rb

class Customers::FilterController < ApplicationController
  before_action :set_customers
  include ActionView::Helpers::TextHelper

  # This controller will never renders any layout.
  layout false

  def filter
    initiate_query
  end

  private
    def set_customers
      # We're duplicating here with customers_controller.rb's index action 😬
      @customers = Customer.all.limit(100)
    end

    def initiate_query
      query = strip_tags(params[:query]).downcase

      if query.present? && query.length > 2
        @customers = Customers::Filter.filter(query)
      end
    end
end

Routing

Inside routes.rb

[..]

post '/customers/filter', to: 'customers/filter#filter', as: 'customers_filter'

[..]

We've separated our filter logic from our CRUD customers controller. Now our controller is much simpler to read and manage. We've done the same for our model Customers::Filter. Let's create that:

Inside model/customers/filter.rb:

class Customers::Filter < ApplicationRecord
  def self.filter query
    Customer.find_by_sql("
      SELECT * FROM customers cus
      WHERE LOWER(cus.first_name) LIKE '%#{query}%'
      OR LOWER(cus.surname) LIKE '%#{query}%'
      OR CONCAT(LOWER(cus.first_name), ' ', LOWER(cus.surname)) LIKE '%#{query}%'
    ")
  end
end

Wow? No. This is just a simple query for a customer by their first name and surname. You may have more logic here, but for brevity, we keep it short and simple.

Though our Customers::FilterController will not use a layout, we still need to render the data, right? For that, we need a matching action view name for filter. Inside views/customers/filter/filter.html.erb:

<%= render partial: 'shared/customer_row', locals: {customers: @customers}  %>

This is what our returned data will looks like - it's server-side rendered HTML.

Now we need to update our form's action customers_filter then fetch some data as we type:

[..]
<!-- Filter section -->
<section>
  <form
    data-action="ajax:success->customers#result"
    data-action="ajax:error->customers#error"
    data-target="customer.form"
    data-remote="true"
    method="post"
    action="<%= customers_filter_path %>"
  >
    <input
      data-action="keyup->customers#search"
      data-target="customers.query"
      type="text" 
      name="query" 
      value=""
      placeholder="Search"
    />
  </form>
</section>
[..]

Remember we got customers_filter from routes.rb. We now need to update our js:

[..]

search(event) {
  Rails.fire(this.formTarget, 'submit')
}

result(event) {
  const data = event.detail[0].body.innerHTML
  if (data.length > 0) {
    return this.displayTarget.innerHTML = data
  }

  // You could also show a div with something else?
  this.displayTarget.innerHTML = '<p>No matching results found</p>'
}

[..]

In our search(), we don't need the query as it's passed to the server via a param. If you have any business logics that need the query text, in JS, then you can do whatever there. Now when you make a query, the HTML results update automatically.

Update

You should noticed I'm duplicating @customers = Customer.all.limit(100). Let's put this into a concern.

Inside controllers/concerns/all_customers_concern.rb

module AllCustomersConcern
  extend ActiveSupport::Concern

  included do
    helper_method :all_customers
  end

  def all_customers
    Customer.all.limit(100)
  end
end

Next, update all controllers:

class CustomersController < ApplicationController
  include AllCustomersConcern

  def index
    @customers = all_customers
  end

  [..]
end

class Customers::FilterController < ApplicationController
  [..]
  include AllCustomersConcern
  [..]
  private
    def set_customers
      @customers = all_customers
    end
end

Conclusion

Rails with Stimulus make it very easy to build any complex filtering system by breaking down logics into micro controllers. Normally I'd put everything in one controller but I guess DHH's approach becomes very useful.

Typos/bugs/improvements? Feel fee to comment and I'll update. I hope this is useful as it does for me. Peace!

Thanks

A huge shout out to Jeff Carnes for helping me out. I've never done this before and I'm well pleased.

How to require another PropType if it's dependant on another?

Daveyon Mayne 😻 — Tue, 02 Jun 2020 07:53:05 +0000

How to require another PropType if it's dependant on another?

Let's look at a situation where we have few tabs and below those tabs we have a button that can do something when clicked. I'll use <ul> in this case to represent the tabs:

export function Tabs(props) {

  // Basic style to create a picture: text on left, button on far right
  const newGroupTabMarkup = props.newGroupTab ? (
    <div style={{display: 'grid', alignItems: 'center',  gridTemplateColumns: '1fr 30px'}}>
      <span style={{fontWeight: '600', fontSize: '18px'}}>Groups</span>
      <button
        onClick={props.onCreateGroup}
      >New</button>
    </div>
  ) : null


  return (
    <div>
      <ul>
        {props.tabs.map(tab => <li key={tab.id}>{tab.name}</li>)}
      </ul>
      {newGroupTabMarkup}
    </div>
  )
}

Rendering our function component we'll see our tabs. What if we want to show newGroupTabMarkup?

import { Tabs } from '../Tabs'

const items = [
  {id: 1, name: 'Tab 1'},
  {id: 2, name: 'Tab 2'}
]

return (
  <Tabs 
    newGroupTab
    tabs={items}
  />
)

This opens up room for visual errors. If our users now click the "New" button, nothing happens. What if we never supplied the "tabs" props? Try is out and see what happens. But we can fix that, but you supply the correct styling.

[..]

const tabsMarkup = props.tabs ? (
  <ul>
    {props.tabs.map(tab => <li key={tab.id}>{tab.name}</li>)}
  </ul>
) : <div>Tabs not supplied</div>

return (
  <div>
    {tabsMarkup}
    {newGroupTabMarkup}
  </div>
)

[..]

That should fix the UI, but what about the "New" button? We could supply the props onCreateGroup function and everything should now work. This post is all about Typechecking With PropTypes. Let's start off with "tabs" prop and what should be the required format we accept.

import PropTypes from 'prop-types'

[..]

Tabs.propTypes = {
  tabs: PropTypes.arrayOf(PropTypes.shape({
     id: PropTypes.number.isRequired, // or PropTypes.string.isRequired 🤷🏽‍♂️
     name: PropTypes.string.isRequired
  })).isRequired,

  // And this:
  newGroupTab: PropTypes.bool,

  // You could put this in a regular function: function(...) { return ...}
  onCreateGroup: (props, propName) => props['newGroupTab'] === true && (props[propName] === undefined || typeof(props[propName]) !== 'function') && new Error('Please provide an onCreateGroup function!'),
  [..]
}

Now that we supplied "newGroupTab", an error will occur requiring us to provide "onCreateGroup" function.


[..]

return (
  <Tabs 
    tabs={items}
    onCreateGroup={() => console.log("TODO: Implement new tab creation")}
    newGroupTab
  />
)

There will be more code required for a tab to be clickable ie "selected tab", you could easily implement that ✌🏼

Implementing an Invoice Numbering System with PHP using Laravel 6

Daveyon Mayne 😻 — Sun, 10 May 2020 10:32:13 +0000

In my last post in How I believe Xero pulled off implementing their Invoice Numbering System, I showed you how I created a customisable and incremental invoice numbering system using Ruby on Rails. This post will demonstrate how it's done using PHP (Laravel 6).

To recap, we have two sections that make up an invoice number:

The Prefix
A numeric value

This approach is customisable as a user can change the prefix to match their business needs and start the sequential value at any number ie 001, 0001 or 1,
max ten characters. 001 is widely used.

In your terminal, run:

php artisan make:migration create_invoice_settings_table

Now, edit the migration file to match below:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateInvoiceSettingsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('invoice_settings', function (Blueprint $table) {
            $table->bigIncrements('id');
            $table->bigInteger('organisation_id')->unsigned();
            $table->string('prefix')->default('INV-');
            $table->string('number_sequence')->default('001');

            // You may have other fields...

            // The association
            $table->foreign('organisation_id')->references('id')->on('organisations');
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::drop('invoice_settings');
    }
}

Run your migration to create the table with default values.

A new InvoiceSettings should be created when a organisation is added to your system, that way we have the default data assigned to an organisation or create a Seeder to create this recored for the current organisation.

Our InvoiceSettings controller would look as follows:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
// use App\InvoiceSettings;

class InvoiceSettingsController extends Controller
{
    // A constructor will not be used in this example.

    /**
     * Gets the defaults values.
     *
     * @param  int  $organisationId
     * @return Response
     */
    public function show($organisationId)
    {
        //
    } 

    /**
     * Update the invoice settings for the given organisation.
     *
     * @param  request  $request
     * @return Response
     */
    public function update(Request $request)
    {
        //
    }
}

Go ahead and create an invoice settings model with migration etc then uncomment InvoiceSettings alias in the above when finished.

Validation

Most Laravel developer place their validations in the controller, we won't be doing that, you should not be doing that. Our controllers should be easily testable, slim and saves item to the database/retrieves items from database etc.

If you have created a route for localhost:4000/organisations/1/invoice-settings, you should see a form with two fields, populating the default invoice settings values. Go ahead and implement that yourself by using an api route or using the blade template.

Once you've done that, we'll create a Laravel Form Request

# Spell this how you see fit
php artisan make:request ShouldBeSequentializeAndUnique

[...]
use Illuminate\Validation\Rule;
use Illuminate\Validation\ValidationException;

[...]

/**
 * Get the custom validation rules that apply to the request.
 *
 * @return array
 */
public function rules()
{
    return $this->customRule();
}

/**
 * Validate sequence number is numeric and not already in database.
 * 
 * @return array|exception
 */
private function customRule()
{
    $prefix = $this->prefix;
    $numberSequence = $this->number_sequence;

    // In most cases, you should have this already in your controller,
    // but we need it here also.
    $organisationId = request()->organisation_id;
    $invoiceReferenceNumber = strtolower($prefix . $numberSequence); // we now/should have something like inv-001

    $rules = [
      'prefix'          => 'required|string|max:10',
      'organisation_id' => 'required|integer',

         'number_sequence' => [
           'required', 'numeric', 'digits_between:1,10',

            Rule::unique('some-table')->where(function ($query) use ($organisationId, $invoiceReferenceNumber) {
              $q = $query
                  ->whereRaw('LOWER(number) LIKE ?', '%' . $invoiceReferenceNumber . '%')
                  ->where('organisation_id', $organisationId)->first();
              if ($q) {
                  throw ValidationException::withMessages(['number_sequence' => 'Sequence number already in use']);
              }
              return $q;
            })
          ],
    ];

    return $rules;
}

WOW! What's going here? For starters, prefix should be a string with a max length of 10 characters. number_sequence should be numeric with a max length of 10 characters. Noticed we have not used max:10 as the input field type should be number. When it's set to type=number, max:10 sums up the value; instead, we use digits_between 1 and 10.

What is some-table? For your homework, create another migration called invoices with a column called number of type string (required), then replace some-table with invoices. Obviously you'll need other columns etc.

Our Rule searches for invoices with the same $invoiceReferenceNumber and if found then $numberSequence is already in use as we combined prefix + numberSequence to make an invoice reference number.

Generating an invoice with number iNv-001 will throw an error*. Generating an invoice with ii-001 will not throw an error* as the user only wants to change the prefix.

This error* only refers to updating the invoice settings, not when creating an invoice. For your homework, create a validation to ensure number is unique for all invoices but only per user's organisation.

Our controller should now look like:


<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Http\Requests\ShouldBeSequentializeAndUnique;
use App\InvoiceSettings;

class InvoiceSettingsController extends Controller
{
    // A constructor will not be used in this example.


    /**
     * Update the invoice settings for the given organisation.
     *
     * @param  ShouldBeSequentializeAndUnique  $request
     * @return Json
     */
    public function update(ShouldBeSequentializeAndUnique $request)
    {
        // Run the validation.
        $validated = $request->validated();

        // $organisationId comes from session or the param.

       // Everything should be ok from here.
       InvoiceSettings::where('organisation_id', $organisationId)
           ->update([
                 'prefix'          => $request->prefix,
                 'number_sequence' => $request->number_sequence
             ]);

      return response()->json($validated, 200);
    }
}

EDIT per comment

public function update(ShouldBeSequentializeAndUnique $request)
    {     
       // $organisationId comes from session or the param.

       // Everything should be ok from here.
       $settings = InvoiceSettings::updateOrCreate(
         ['organisation_id'   => $request->organisation_id],
         [
            'prefix'          => $request->prefix,
            'number_sequence' => $request->number_sequence
         ]);

      return response()->json($settings, 200);
    }

There are many ways write code. The above maybe incorrect for some but, as we all say, "it works for me" 😁. I'm open for improvements as I haven't been professionally using Laravel for years.

In another post, I'll demonstrate how to increment the number_sequence on every invoice creation.

How I believe Xero pulled off implementing their Invoice Numbering System

Daveyon Mayne 😻 — Thu, 23 Apr 2020 14:35:40 +0000

During this lockdown, I thought I would learn accounting. I love accounting, or anything with numbers, but never fully get a chance to act on that thought.

Xero Central is my goto for anything accounting. You could pretty much read their entire documentation and API to get an understanding of how things work or accounting in general. This is what I did. I've decided to focus on the invoicing section. I also like their invoice interface that I made mine the similar (kids, do not copy 😈):

This post is about how I've done the invoice numbering. I know there should be a better way but I could only come up with this method. Using Rails 6 API, I'll show you how I've pulled it off.

The Invoice Settings

This model is responsible for validating your chosen invoice sequence ie INV-001. INV- is used as the prefix and 001 is used as a numeric sequence. Sequence can only be numeric. Should you try to enter an alpha-numeric value, it will fail. Note this has nothing to do with the actual invoice number. We'll get to that in a bit.

class InvoiceSetting < ApplicationRecord
  belongs_to :organisation
  validates  :invoice_number_sequence, :quote_number_sequence, :purchase_order_number_sequence, should_be_sequencialised: true
  validate   :check_for_duplicate_numbers

  private
  # TODO: Check for credit note for invoice number
    def check_for_duplicate_numbers
      exists = Invoice.exists?(['lower(invoice_number) = ? AND organisation_id = ?', "#{(invoice_prefix + invoice_number_sequence).downcase}", organisation_id])
      if exists
        errors.add(:invoice_number_sequence, "invoice number already exists.")
      end
    end
end

So what is should_be_sequencialised?

We use a Rails concerns to implement this logic. This logic ensures the sequence value is numeric:

# /models/concerns/should_be_sequencialised_validator.rb

class ShouldBeSequencialisedValidator < ActiveModel::EachValidator
  # The Client should also ensure users only enter numeric values ie 001, 1 etc.
  def validate_each(record, attribute, value)
    begin
      Integer(value)
    rescue StandardError => e
      record.errors.add(attribute, "Invalid number. Please use numeric numbers only")
    end
  end
end

validate_each accepts three arguments: model, model's column name and the incoming value to be checked. EachValidator will loop this method, in our example, 3 times. Later I'll refactor to only validate on invoice_number_sequence.

Integer will throw an exception so it should be wrapped in catch block. When there's an error, we add the error message back to our model for the front-end to display. Your data will be rolled back. A neat feature with Rails and other frameworks.

check_for_duplicate_numbers

Should the first validator succeeds, check_for_duplicate_numbers checks for existing invoice numbers already generated. Pretty easy to understand.

That takes care of the validation but how does an invoice number increments?

Jörg W Mittag on Stack overflow says:

Then it's not a number but rather an "invoice identifier object", and you model it as an InvoiceIdentifier

I've "Googled" what's an InvoiceIdentifier but nothing came up. I should have asked for him to explain but I never wanted to extend the post when I've already selected an answer, so I left it as is. If invoice_number is not a string then what is it? I've created a model called invoice with a string attribute as invoice_number. I've used string because I cannot find information regarding this InvoiceIdentifier.

Let's validate our invoice model to ensure invoice_number is unique. This is only unique for each of the user's organisation:

class Invoice < ApplicationRecord
  validates   :invoice_number, uniqueness: { case_sensitive: :false, scope: :organisation_id }
  [...] # Other validations and relationships etc
end

We'll now focus our attention over to invoice_controller.rb:

Invoice Controller

  # POST /organisations/:organisation_id/invoices
  def create
    invoice = @organisation.invoices.build(invoice_params)
    if invoice.save
      return render json: invoice
    end

    render json: {error: invoice.errors.messages}
  end

I won't explain what's going on here as this is not a beginners guide. At this point we should be able to create an invoice. If it fails then our invoice_number is not unique.

How and when does the invoice number auto increments?

The Wisper gem is a great tool for listening to events. We'd listen for two events: create and update (this example for focuses on create). This is when we would increment our invoice number or leave it as is. Let's look at this IncrementInvoiceNumber class:

# /lib/invoices/increment_invoice_number.rb
module Invoices
  class IncrementInvoiceNumber
    include Wisper::Publisher

    def create(invoice, organisation)
      if invoice.save
        puts "-----INVOICE CREATED------"
        increment_invoice_number(invoice.invoice_number, organisation)
        broadcast(:invoice_created, invoice)
      else
        puts "-----INVOICE FAILED------"
        broadcast(:invoice_failed, invoice)
      end
    end

    private
      def increment_invoice_number(inv_num, organisation)
        settings = organisation.invoice_setting
        invoice_setting_prefix = settings.invoice_prefix

        arr = inv_num.split(invoice_setting_prefix)
        if arr.count == 2
          # We have an untouched invoice number
          incremented_sequence = arr[1]

          # We need to test if it's a numeric value
          begin
            Integer(incremented_sequence)
            # We can safely increment and save
            incremented_sequence = incremented_sequence.next
            organisation.invoice_setting.update(invoice_number_sequence: incremented_sequence)
          rescue StandardError => e
            # We do nothing
          end
        end

        # At this point, we have not incremented the invoice number that came in as they've entered a custom invoice number.
      end
  end
end

Our create method is self-explanatory so let's look at increment_invoice_number.

We increment the invoice number only if the prefix is the same as when you're creating a new invoice. See main image, but we still need to check as a user could simply enter INV-foo. If so, we save the invoice as is and only increment if the sequence is of a numeric value. At this point, validation has passed and invoice number is unique.

foo.next will also increment to fop but our validation checks if that section is numeric with Integer(string).

Once you've install Wisper, our create method now becomes:

 # /controllers/invoice_controller.rb

 # POST /organisations/:organisation_id/invoices
  def create
    service = Invoices::IncrementInvoiceNumber.new
    service.on(:invoice_created) { |invoice| render json: invoice }
    service.on(:invoice_failed) { | invoice |render json: {error: invoice.errors.messages} }

    service.create(@organisation.invoices.build(invoice_params), @organisation)
  end

Incrementing an invoice number only runs after an invoice is created. Is there a better way? I would love to know. If you're a Xero dev, I'd love to hear your thoughts and it does not matter what programming language you guys are using.