markup_attributes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 97c6b8cec1b64b794fac504e4893679db9449395
+  data.tar.gz: 20456a12c564af69e167736e4ffcf92422995b01
+SHA512:
+  metadata.gz: 654d8ed332adf3308ae8905defccaa7f7eb3f12d854bb1650f01af28c3c31c6c71aeb308cdaf61148d0b64623e0dba5551ef127285c2e6f9db4145633fd2f699
+  data.tar.gz: 732047395d4b1d68e81422482dcb235c396865441be46157d1073b4c279d953552f9651dde7b8a7f527fc828f494d80e5eb8bf0f4d1cb5f9499b69690159c425

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 James Adam
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# MarkupAttributes
+A simple Rails engine for cleanly handling Textile/Markdown markup in ActiveRecord attributes.
+
+Using this engine, we can define a particular attribute as containing markup, with constraints around
+which markup rules and tags we want to support, and then render that attribute value to HTML
+consistently throughout the rest of the application.
+
+Rather than adding any HTML generation into the model itself, this works by attaching metadata
+to the model, which can then be consumed by a helper when the attribute is used in views.
+
+In the future, this will expand to also handle Markdown, Github-Flavoured Markdown and potentially
+any other markup language; the underlying mechanism is markup-agnostic, and others can easily
+be added.
+
+## Usage
+Once you've added this gem to your application, you can enable it on a per-model basis by
+extending the model class with the {#MarkupAttributes} module, and then declaring one or more
+attributes as having textile:
+
+    class Post < ApplicationRecord
+      extend MarkupAttributes
+      
+      textile_attribute :title, :description
+    end
+    
+You can then deal with the model as with any other ActiveRecord subclass; the attributes
+can be treated as simple strings:
+
+    post = Post.create(title: 'My _cool_ post', description: 'A post about *stuff*')
+    post.title # => 'My _cool_ post'
+    post.description # => 'A post about *stuff*'
+
+When you want to render the markup in a view, use the `render_markup` helper method:
+
+    <h1><%= render_markup post.title %></h1>
+    <p><%= render_markup post.description %></p>
+
+which will produce the HTML
+
+    <h1>My <em>cool</em> post</h1>
+    <p>A post about <strong>stuff</strong></p>
+
+
+### Markup constraints
+
+The main benefit of this gem is that it allows you to define _constraints_ about what markup
+an attribute should support in a single place, and have those rules be applied consistently
+wherever the content is rendered. We do this using the `:allow` and `:deny` options to
+`textile_attribute`.
+
+    class Post < ApplicationRecord
+      extend MarkupAttributes
+      
+      textile_attribute :title, allow: :emphasis
+    end
+
+If any `:allow` options are set, anything missing from that option is assumed to be denied, and
+will be removed from the rendered markup. So, anywhere we try to render the title markup now,
+these rules will be respected:
+
+    <% post = Post.new(title: '"Link":http://example.com this _up_') %>
+    <%= render_markup post.title %>
+
+produces
+
+    Link this <em>up</em>
+
+Because we didn't allow links, that aspect of the markup is removed.
+
+We can include multiple allowed markup types:
+
+    textile_attribute :title, allow: [:emphasis, :links, :images]
+
+or, we can allow all markup and then explicitly deny certain types:
+
+    textile_attribute :title, deny: :images
+
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'markup_attributes'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install markup_attributes
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files   = ['app/**/*.rb', 'lib/**/*.rb', '-', 'README.md']
+  t.options = ['--no-private']
+end
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+if defined? RSpec
+  task(:spec).clear
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.verbose = false
+  end
+end
+
+task default: :spec

data/app/helpers/markup_attributes_helper.rb

@@ -0,0 +1,66 @@
+# The top-level Rails helper which enables consistent rendering of markup attributes.
+#
+# Rails will make this automatically available in your views; you may need to explicitly
+# include it in other places (like serializers).
+#
+# This helper exposes a single method: +render_markup+
+module MarkupAttributesHelper
+
+  # Given an attribute, returned an HTML-safe, rendered version of the content
+  # in that attribute, rendered according to the markup options defined in the model.
+  #
+  # If the passed attribute has not been configured as a markup attribute, it will be
+  # returned without performing any rendering at all. Th ft ft
+  #
+  # @param markup_attribute [String] the attribute to render. If this is an attribute that
+  #   has not been configured as a markup attribute, it will be returned without any rendering.
+  # @example rendering an attribute from a model
+  #    # Given this model exists somewhere, with `title` as a markup attribute:
+  #    # post = Post.new(title: '"This":http://example.com is _great_')
+  #
+  #    render_markup(post.title) # => '<a href="http://example.com" rel="nofollow">This</a> is <em>great</em>'
+  def render_markup(markup_attribute)
+    return markup_attribute if markup_attribute.blank?
+
+    if markup_attribute.respond_to?(:markup_options)
+      options = markup_attribute.markup_options
+
+      html = case options[:markup]
+      when :textile
+        require 'redcloth'
+        RedCloth.new(sanitize(markup_attribute), [:no_span_caps]).to_html
+      else
+        raise "unknown markup attribute type: #{options[:markup]}"
+      end
+
+      cleaned_html = clean_rendered_markup(html, options)
+      cleaned_html.html_safe
+    end
+  end
+
+  private
+
+  def clean_rendered_markup(html, options)
+    cleaned_html = if options[:allow] == [:all]
+      denied_tags = tags_from_tag_types(*options[:deny])
+      allowed_tags = Rails::Html::WhiteListSanitizer.allowed_tags.reject { |tag| denied_tags.include?(tag.to_s) }
+      whitelisted_html = Rails::Html::WhiteListSanitizer.new.sanitize(html, tags: allowed_tags).strip
+      whitelisted_html
+    else
+      allowed_tags = tags_from_tag_types(*options[:allow])
+      cleaned_html = Rails::Html::WhiteListSanitizer.new.sanitize(html, tags: allowed_tags).strip
+      cleaned_html = Loofah.scrub_fragment(cleaned_html, :nofollow).to_html if options[:allow].include?(:links)
+      cleaned_html
+    end
+
+    cleaned_html
+  end
+
+  def tags_from_tag_types(*tag_types)
+    tags = []
+    tags += %w(i em) if tag_types.include?(:emphasis)
+    tags += %w(a) if tag_types.include?(:links)
+    tags += %w(img) if tag_types.include?(:images)
+    tags
+  end
+end

data/lib/markup_attributes/engine.rb

@@ -0,0 +1,5 @@
+module MarkupAttributes
+  # @private
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/markup_attributes/version.rb

@@ -0,0 +1,3 @@
+module MarkupAttributes
+  VERSION = '0.1.0'
+end

data/lib/markup_attributes.rb

@@ -0,0 +1,137 @@
+require "markup_attributes/engine"
+
+# The main behaviour for defining markup attributes
+#
+# To enable this for your models, either extend it directly into one or more models,
+# or extend it into `ApplicationRecord` to include it everywhere
+#
+# == Markup constraints
+# Markup content typically comes from users of the app, and as with any user-generated
+# content, we probably can't allow them to insert any old HTML into our rendered pages.
+#
+# The main benefit of this approach is that it allows us to declare constraints on
+# the types of markup we want to deal with in a single place, but without coupling
+# rendering logic into the model itself.
+#
+# Those constraints are grouped into certain types of elements:
+#
+# Emphasis (:emphasis)::  allow `i` and `em` tags.
+# Links (:links)::  allow `a` tags, but mark them as `nofollow` so that they are not useful
+#                   for spammers.
+# Images (:images):: allow `img` tags.
+#
+# == Automatic sanitisation
+#
+# All the HTML generated is automatically run through Rails' own sanitisation mechanism,
+# which means that things like `<script>alert();</script>` will automatically either
+# be sanitised into a non-running piece of content, or entirely removed, depending on
+# the options given.
+#
+# @example a simple model declaring textile attributes
+#   class Post < ApplicationRecord
+#     extend MarkupAttributes
+#
+#     textile_attribute :title, :description, allow: [:emphasis, :images]
+#
+#     # ...
+#   end
+module MarkupAttributes
+  # A subclass of string which the attributes are cast into by ActiveRecord
+  # @private
+  class MarkupString < String
+    attr_accessor :markup_options
+  end
+
+  # The type used by ActiveRecord's attributes API
+  # @private
+  class MarkupType < ActiveRecord::Type::String
+    def self.inspect
+      "<MarkupType [#{markup_options}]>"
+    end
+
+    def markup_options
+      self.class.markup_options
+    end
+
+    def cast(value)
+      if value.is_a?(String) || value.is_a?(MarkupString)
+        MarkupString.new(value).tap { |s| s.markup_options = self.markup_options }
+      else
+        super
+      end
+    end
+  end
+
+  ActiveRecord::Type.register(:markup, MarkupType)
+
+  # Declare one or more attributes as containing Textile markup.
+  # @param (see #markup_attribute)
+  # @example An attribute which only supports Textile emphasis and links
+  #    textile_attribute :title, allow: [:emphasis, :links]
+  # @example An attribute which supports everything except images
+  #    textile_attribute :title, deny: [:images]
+  def textile_attribute(*attribute_names, **options)
+    markup_attribute(*attribute_names, **options.merge(markup: :textile))
+  end
+
+  # Declare one or more attributes as containing Markdown markup.
+  # @param (see #markup_attribute)
+  def markdown_attribute(*attribute_names, **options)
+    markup_attribute(*attribute_names, **options.merge(markup: :markdown))
+  end
+
+  # Declare one or more attributes as containing markup content
+  #
+  # == Markup types
+  # The following types can be provided in either the +:allow+ or +:deny+ options:
+  # :emphasis:: +i+ and +em+ tags
+  # :links:: +a+ tags (will all have +rel=nofollow+ automatically set)
+  # :images:: +img+ tags
+  #
+  # @param attribute_names [Symbol, Array<Symbol>] One or more attribute names to mark as containing markup
+  # @param options [Hash<Symbol=>Symbol>, Hash<Symbol=>Array<Symbol>>]  Options to be used when rendering this/these attributes
+  # @option options [Symbol] :markup The markup engine to use, either +:textile+ or +:markdown+. If you use either of
+  #                                  +textile_attribute+ or +markdown_attribute+, wrapper methods, this will be set automatically.
+  # @option options [Symbol, Array<Symbol>] :allow Which types of markup to allow (any not included are implicity denied)
+  # @option options [Symbol, Array<symbol>] :deny Which types of markup to deny (any not included are implicity allowed)
+  def markup_attribute(*attribute_names, **options)
+    raise "must define :markup option" unless options[:markup]
+    options.deep_symbolize_keys!
+    options[:allow] = Array.wrap(options[:allow] || :all).map(&:to_sym)
+    options[:deny] = Array.wrap(options[:deny]).map(&:to_sym)
+    options.freeze
+
+    attribute_registry_type = get_type_for(options)
+
+    attribute_names.each do |attribute_name|
+      if respond_to?(:translates?) && translates? && translated_attribute_names.include?(attribute_name)
+        translation_class.attribute attribute_name, attribute_registry_type
+      else
+        attribute attribute_name, attribute_registry_type
+      end
+    end
+  end
+
+  private
+
+  MARKUP_TYPES_REGISTRY = {}
+
+  def get_type_for(options)
+    allow_keys = options[:allow].map { |x| "+#{x}" }
+    deny_keys = options[:deny].map { |x| "-#{x}" }
+    type_key = [options[:markup],(allow_keys + deny_keys).sort.join].join('=>').to_sym
+    MARKUP_TYPES_REGISTRY.fetch(type_key) do
+      klass = eval <<-TYPE_CLASS
+        Class.new(MarkupType) do
+          def self.markup_options
+            #{options.inspect}
+          end
+        end
+      TYPE_CLASS
+      ActiveRecord::Type.register(type_key, klass)
+      MARKUP_TYPES_REGISTRY[type_key] = klass
+      klass
+    end
+    type_key
+  end
+end

data/lib/tasks/markup_attributes_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :markup_attributes do
+#   # Task goes here
+# end

data/spec/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative 'config/application'
+
+Rails.application.load_tasks

data/spec/dummy/app/assets/config/manifest.js

@@ -0,0 +1,2 @@
+//= link_tree ../images
+//= link_directory ../stylesheets .css

data/spec/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,15 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or any plugin's vendor/assets/javascripts directory can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file. JavaScript code in this file should be added after the last require_* statement.
+//
+// Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require rails-ujs
+//= require activestorage
+//= require_tree .

data/spec/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/spec/dummy/app/channels/application_cable/channel.rb

@@ -0,0 +1,4 @@
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

data/spec/dummy/app/channels/application_cable/connection.rb

@@ -0,0 +1,4 @@
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+  end
+end

data/spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base
+end

data/spec/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/spec/dummy/app/jobs/application_job.rb

@@ -0,0 +1,2 @@
+class ApplicationJob < ActiveJob::Base
+end

data/spec/dummy/app/mailers/application_mailer.rb

@@ -0,0 +1,4 @@
+class ApplicationMailer < ActionMailer::Base
+  default from: 'from@example.com'
+  layout 'mailer'
+end

data/spec/dummy/app/models/application_record.rb

@@ -0,0 +1,3 @@
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+end

data/spec/dummy/app/models/basic_model.rb

@@ -0,0 +1,3 @@
+class BasicModel < ApplicationRecord
+  extend MarkupAttributes
+end

data/spec/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Dummy</title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= stylesheet_link_tag    'application', media: 'all' %>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/spec/dummy/app/views/layouts/mailer.html.erb

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <style>
+      /* Email styles need to be inline */
+    </style>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/spec/dummy/app/views/layouts/mailer.text.erb

@@ -0,0 +1 @@
+<%= yield %>

data/spec/dummy/bin/bundle

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+load Gem.bin_path('bundler', 'bundle')

data/spec/dummy/bin/rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+APP_PATH = File.expand_path('../config/application', __dir__)
+require_relative '../config/boot'
+require 'rails/commands'

data/spec/dummy/bin/rake

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative '../config/boot'
+require 'rake'
+Rake.application.run

data/spec/dummy/bin/setup

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+require 'fileutils'
+include FileUtils
+
+# path to your application root.
+APP_ROOT = File.expand_path('..', __dir__)
+
+def system!(*args)
+  system(*args) || abort("\n== Command #{args} failed ==")
+end
+
+chdir APP_ROOT do
+  # This script is a starting point to setup your application.
+  # Add necessary setup steps to this file.
+
+  puts '== Installing dependencies =='
+  system! 'gem install bundler --conservative'
+  system('bundle check') || system!('bundle install')
+
+  # puts "\n== Copying sample files =="
+  # unless File.exist?('config/database.yml')
+  #   cp 'config/database.yml.sample', 'config/database.yml'
+  # end
+
+  puts "\n== Preparing database =="
+  system! 'bin/rails db:setup'
+
+  puts "\n== Removing old logs and tempfiles =="
+  system! 'bin/rails log:clear tmp:clear'
+
+  puts "\n== Restarting application server =="
+  system! 'bin/rails restart'
+end

data/spec/dummy/bin/update

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+require 'fileutils'
+include FileUtils
+
+# path to your application root.
+APP_ROOT = File.expand_path('..', __dir__)
+
+def system!(*args)
+  system(*args) || abort("\n== Command #{args} failed ==")
+end
+
+chdir APP_ROOT do
+  # This script is a way to update your development environment automatically.
+  # Add necessary update steps to this file.
+
+  puts '== Installing dependencies =='
+  system! 'gem install bundler --conservative'
+  system('bundle check') || system!('bundle install')
+
+  puts "\n== Updating database =="
+  system! 'bin/rails db:migrate'
+
+  puts "\n== Removing old logs and tempfiles =="
+  system! 'bin/rails log:clear tmp:clear'
+
+  puts "\n== Restarting application server =="
+  system! 'bin/rails restart'
+end

data/spec/dummy/config/application.rb

@@ -0,0 +1,29 @@
+require_relative 'boot'
+
+require "rails"
+# Pick the frameworks you want:
+require "active_model/railtie"
+require "active_record/railtie"
+require "action_controller/railtie"
+require "action_view/railtie"
+
+Bundler.require(*Rails.groups)
+require "markup_attributes"
+require 'globalize'
+
+
+module Dummy
+  class Application < Rails::Application
+    # Initialize configuration defaults for originally generated Rails version.
+    config.load_defaults 5.2
+
+    config.i18n.available_locales = ['en-US', 'fr-FR']
+    config.i18n.default_locale = 'en-US'
+
+    # Settings in config/environments/* take precedence over those specified here.
+    # Application configuration can go into files in config/initializers
+    # -- all .rb files in that directory are automatically loaded after loading
+    # the framework and any gems in your application.
+  end
+end
+

data/spec/dummy/config/boot.rb

@@ -0,0 +1,5 @@
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../../Gemfile', __dir__)
+
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+$LOAD_PATH.unshift File.expand_path('../../../lib', __dir__)

data/spec/dummy/config/cable.yml

@@ -0,0 +1,10 @@
+development:
+  adapter: async
+
+test:
+  adapter: async
+
+production:
+  adapter: redis
+  url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
+  channel_prefix: dummy_production

data/spec/dummy/config/database.yml

@@ -0,0 +1,14 @@
+default: &default
+  adapter: sqlite3
+  encoding: unicode
+  # For details on connection pooling, see Rails configuration guide
+  # http://guides.rubyonrails.org/configuring.html#database-pooling
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+
+development:
+  <<: *default
+  database: db/dummy_development.sqlite3
+
+test:
+  <<: *default
+  database: db/dummy_test.sqlite3

data/spec/dummy/config/environment.rb

@@ -0,0 +1,5 @@
+# Load the Rails application.
+require_relative 'application'
+
+# Initialize the Rails application.
+Rails.application.initialize!