embeddable_asset 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b5120c3314583be75281cc62054f77f76bbea5d7
+  data.tar.gz: 69606f45626053b2a0d7ef94888817f18af7ceef
+SHA512:
+  metadata.gz: c2e2a2dbe43db7025eed4a74e9cb1e8d2f1423fcf8cee93300c5aad30c84c85cc31a45ca4afcf64aadb007b49dc53afaaba95e84112bdd3538e0621bd8f01e82
+  data.tar.gz: e070c7736526f2c4c6e6e7c88d2ee113460eb15dff552f60b3f9b91fb7bbe85bec9b84e43577899d31391f02512067505bc646340c553adf2b784d64a0f8ca60

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.DS_Store
+public/assets/application-52db830a003d76c5163da6d690b3ac62761c513e294a93423ccf8c559af41422.js
+public/assets/balls-1d82a2d4da0d21ed2882c4837bce5b0441ff2c4b77e2e4ee2ee42441b623d148.jpg
+public/assets/dog-d5dff91846dc9416d270582a3e16a071b42528e9325378fad6a268567c2e477c.jpg
+public/assets/duck-e5ff3efc549760da99a32215af55003c2358d7cb2f2b69464becfcf677362b84.jpg

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.3.0

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in embeddable_asset.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 John McCormack
+
+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,163 @@
+# EmbeddableAsset Gem
+ - Supports Rails 3 and 4
+ - Supports both Sass and CSS
+ - Dynamically embed your assets into your Stylesheets
+ - Generate Stylesheets completely indepedent of external assets!
+
+
+This is a simple gem that makes embedding your assets directly in your CSS very easy!
+The goal is to generate stylesheets completely independent of all external asset resources.
+This is achieved through CSS data-uri (i.e. encoding an asset's data directly into the file in base64).
+This gem packages up some already existing Rails helpers meant for generating data-uris via the asset pipeline.
+On top of those rails helpers is a wrapper that allows for conditionally embedding or not embedding (unembedding) your assets via Rake tasks.
+In otherwords, precompile assets as normal, unless you specifically want them to be embedded. Hence the duality of the gem name "Embeddable",
+denoting that a given asset may or may not be embedded depending on how you run it.
+
+
+## Why would I use this?
+Most of the time you want the rails asset pipeline to behave normally when deploying to production (i.e. linking to assets instead of embedding them).
+However there are situations when you might want to package your stylesheet and the external assets it links to (like images, fonts, etc.) into
+a single application.css file that does not have any dependencies. For example, if you want to have a completely static "down page"
+that is served by a proxy in the event your main production server goes down, you might want to serve a single static html file that has all of the
+styles, JS, images, fonts, etc. embedded inside of it. Yes, the embedding makes the file size signigicantly larger, however you would only use this for
+special situations like this. Another usage example, might be a simple and convienant way to package up a page you are building or want to show someone non-technical.
+You could simply compile that page into a single file, assets and all, and send it in an email. Then the receiver doesn't need a server or a bunch of files to make it work.
+They can simply open a single file in their browser and interact with it.
+
+
+
+## Installation (STEP 1/3)
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'embeddable_asset'
+```
+
+And then execute:
+
+    $ bundle
+
+## Using the embeddable helpers (STEP 2/3)
+**Specify which assets should be embedded**
+
+#### Via CSS
+You must use the *css.erb extension in files you wish to use the helpers in:
+
+```css
+@font-face {
+  font-family: myFirstFont;
+  src: <%= embeddable_asset('chopin_script.ttf') %>;
+}
+
+h2 {
+  font-family: myFirstFont;
+  padding: 12px;
+  background-image: <%= embeddable_image(asset_path 'duck.jpg') %>;
+}
+```
+
+
+#### Via Sass
+Import the helper file in application.scss:
+
+```css
+@import 'embeddable_asset';
+/* now other Sass and imports below it can use helper functions */
+...
+```
+
+Now you can call Sass helper functions
+```css
+...
+@font-face {
+  src: embeddable-asset('chopin_script.ttf');
+  font-family: myFirstFont;
+}
+
+h2 {
+  font-family: myFirstFont;
+  padding: 12px;
+  background-image: embeddable-image('duck.jpg');
+}
+```
+
+## Running the Rake Tasks (STEP 3/3)
+Only use the embeddable helpers on assets you want to be embedded.
+This is an opt-in helper so you can limit which assets get embedded.
+
+
+#### Precompile with embedded assets
+
+    $ bundle exec rake assets:precompile:embed
+
+```css
+/* Will turn this... */
+h2 {
+	background-image: embeddable-asset('duck.jpg')
+}
+
+/* ...Into this */
+h2 {
+	background-image: url(data:image/jpeg;base64,%2F9j%2F2wBBAQEBAQEBAQ...)
+}
+```
+
+#### Precompile with unembedded assets
+NOTE: Because the asset pipeline caches precompiled assets, rerunning any kind of additional precompile rake task on its own would normally not force a recompile if the assets haven't been changed.
+It would simply just reuse the same assets. So running "rake assets:precompile:embed" followed by "rake assets:precompile"
+would simply reuse the precompiled-embedded assets from the first command.
+
+To ensure assets do not get embedded after running the embed command, you can use:
+
+	$ bundle exec rake assets:precompile:unembed
+
+This is essentially the equivalent of "rake assets:precompile", however it will make sure to ignore any previously cached assets.
+
+```css
+/* Will turn this... */
+h2 {
+	background-image: embeddable-asset('duck.jpg')
+}
+
+/* ...Into this */
+h2 {
+	background-image: url(/assets/duck-e5ff3efc549760d.jpg)
+}
+```
+
+
+
+## Troubleshooting
+#### "WARNING: Unable to initialize EmbeddableAsset helpers."
+You will see this warning in the terminal output or logs when
+the current RAILS_ENV (i.e. test, development, production) has the
+asset pipeline compilation disabled. Make sure the config file for the environment you are trying to run the rake task in has this setting
+enabled like so:
+
+```ruby
+config.assets.compile = true
+```
+
+#### Why aren't my precompiled assets being minified?
+This also has to do with environment specific config options as explained above. In order to ensure assets are minified, set the appropriate config options in the config file corresponding with the RAILS_ENV you are trying to run the rake task in. These config options will be different depending on if you are using CSS or Sass / Rails 3 or 4. You will want to look up the config options specific to your use case. The production environment config file usually has the desired minification settings specific to your project, so you could alternatively run the rake task like so:
+
+    $ RAILS_ENV=production rake assets:precompile:embed
+
+
+## Running the tests
+This Gem is tested by utilizing two seperate nested dummy projects in order
+to best simulate the environments this gem will be used in.
+One project is using Sass via Rails 4.2, and the second is using CSS via Rails 3.2.
+In order to run the tests, you must clone this project and "cd" into the appropriate sub-dummy-project and run:
+
+	$ cd path/to/sub-dummy-project
+    $ bundle exec rspec
+
+
+## Contributing
+Bug reports and pull requests are welcome!
+
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+Dir.glob('lib/tasks/*.rake').each { |r| import r }

data/app/assets/stylesheets/_embeddable_asset.scss.erb

@@ -0,0 +1,11 @@
+@function embeddable-asset($asset) {
+  <% if embed_assets? %>
+    @return asset-data-url($asset)
+  <% else %>
+    @return url(asset-path($asset) + "#iefix")
+  <% end %>
+}
+
+@function embeddable-image($image) {
+  @return embeddable-asset($image)
+}

data/config/initializers/expose_asset_pipeline_embeddable_helpers.rb

@@ -0,0 +1,21 @@
+require 'embeddable_asset/asset_pipeline_helper'
+
+Rails.application.config.after_initialize do
+  if Rails.application.assets
+    extend_pipeline_with_embeddable_helpers
+  else
+    print_failed_initialization_msg
+  end
+end
+
+def extend_pipeline_with_embeddable_helpers
+  Rails.application.assets.context_class.class_eval do
+    include AssetPipelineHelper
+  end
+end
+
+def print_failed_initialization_msg
+  puts "\nWARNING: Unable to initialize EmbeddableAsset helpers. "\
+       "'Rails.application.assets' is not defined. "\
+       "Ensure 'config.assets.compile = true' for your current RAILS_ENV\n\n"
+end

data/embeddable_asset.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'embeddable_asset/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "embeddable_asset"
+  spec.version       = EmbeddableAsset::VERSION
+  spec.authors       = ["John McCormack"]
+  spec.email         = ["mccormjt@gmail.com"]
+
+  spec.summary       = %q{Dynamically embed your assets into your Stylesheets}
+  spec.description   = %q{Simple Gem that provides CSS and Sass helpers
+                            to conditionally embed or unembed your assets via rake tasks.}
+  spec.homepage      = "https://github.com/enova/embeddable_asset"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/embeddable_asset.rb

@@ -0,0 +1,2 @@
+require 'embeddable_asset/version'
+require 'embeddable_asset/rails/engine'

data/lib/embeddable_asset/asset_pipeline_helper.rb

@@ -0,0 +1,16 @@
+module AssetPipelineHelper
+  def embed_assets?
+    ENV['EMBED_ASSETS'] == 'yes'
+  end
+
+  def embeddable_asset(asset_name)
+    if embed_assets?
+      data_uri = asset_data_uri(asset_name)
+      "url(#{data_uri})"
+    else
+      path = asset_path(asset_name)
+      "url(#{path}#iefix)"
+    end
+  end
+  alias_method :embeddable_image, :embeddable_asset
+end

data/lib/embeddable_asset/rails/engine.rb

@@ -0,0 +1,6 @@
+module EmbeddableAsset
+  module Rails
+    class Engine < ::Rails::Engine
+    end
+  end
+end

data/lib/embeddable_asset/test/embeddable_rake_task_examples.rb

@@ -0,0 +1,144 @@
+require "rails_helper"
+
+# This file will be included in the nested "dummy" projects under spec/dummy_* in
+# order to test this Gem in realistic app environments
+
+RSpec.shared_examples 'Embeddable Rake Tasks' do
+  OPTIONAL_WHITESPACE       = '\s?'
+  WILDCARD                  = '.*?'
+  PROP_DELIMETER            = ';'
+  EMBEDDED_DATA_URL_PREFIX  = 'url(data:'
+
+  def precompile_assets!(embed:)
+    action = embed ? 'embed' : 'unembed'
+    `rake assets:precompile:#{action}`
+  end
+
+  def regex_range(leading: '', start:, stop:)
+    escaped_leading = Regexp.quote(leading)
+    escaped_start   = Regexp.quote(start)
+    escaped_stop    = Regexp.quote(stop)
+
+    raw_regex_range = "#{escaped_leading}"\
+                      "#{OPTIONAL_WHITESPACE}"\
+                      "#{escaped_start}"\
+                      "#{WILDCARD}"\
+                      "#{escaped_stop}"
+
+    Regexp.new(raw_regex_range, Regexp::MULTILINE | Regexp::IGNORECASE)
+  end
+
+  def get_css_rules(selector)
+    selector_regexp = regex_range(leading: selector, start: '{', stop: '}')
+    application_css.match(selector_regexp).try(:[], 0)
+  end
+
+  def get_css_property(selector, property)
+    rules = get_css_rules(selector)
+    return unless rules
+    property_regex = regex_range(start: property, stop: PROP_DELIMETER)
+    rules.match(property_regex).try(:[], 0)
+  end
+
+  def get_css_property_value(selector, property)
+    property = get_css_property(selector, property)
+    return unless property
+    property.partition(/:/).last.chomp(PROP_DELIMETER).strip
+  end
+
+  def embedded_data_url?(url)
+    url.start_with?(EMBEDDED_DATA_URL_PREFIX)
+  end
+
+  def asset_regex(asset)
+    parts     = asset.partition('.')
+    name      = parts.first
+    extension = parts.second + parts.last
+    regex_range(start: name, stop: extension)
+  end
+
+  def application_asset(extension)
+    search_path = Rails.root.join('public', 'assets', "application*.#{extension}")
+    file_path = Dir.glob(search_path).first
+    File.read(file_path) if file_path
+  end
+
+  def application_css
+    application_asset('css')
+  end
+
+  def application_js
+    application_asset('js')
+  end
+
+  after do
+    `rake assets:remove`
+    `rake tmp:cache:clear`
+  end
+
+  shared_examples_for 'embedded css asset' do |selector:, property:, asset:|
+    it "embedds asset: '#{asset}', via selector: '#{selector}', in property: #{property}" do
+      prop_url = get_css_property_value(selector, property)
+      expect(embedded_data_url?(prop_url)).to be true
+      expect(prop_url).not_to match(asset_regex(asset))
+    end
+  end
+
+  shared_examples_for 'unembedded css asset' do |selector:, property:, asset:|
+    it "does not embed asset: '#{asset}', via selector: '#{selector}', in property: #{property}" do
+      prop_url = get_css_property_value(selector, property)
+      expect(embedded_data_url?(prop_url)).to be false
+      expect(prop_url).to match(asset_regex(asset))
+    end
+  end
+
+  shared_examples_for 'precompiled assets' do |embed:|
+    action = embed ? 'embedded' : 'unembedded'
+
+    it 'compiles JavaScript and CSS' do
+      expect(application_css).to include('h2')
+      expect(application_js).to include('doAwesomeStuff')
+    end
+
+    context 'pipeline assets not using embeddable gem' do
+      it_behaves_like 'unembedded css asset',
+        selector: 'h2',
+        property: 'background-image',
+        asset:    'duck.jpg'
+    end
+
+    context '#embeddable-asset' do
+      it_behaves_like "#{action} css asset",
+        selector: '@font-face',
+        property: 'src',
+        asset:    'chopin_script.ttf'
+    end
+
+    context '#embeddable-image' do
+      it_behaves_like "#{action} css asset",
+        selector: 'html',
+        property: 'background-image',
+        asset:    'dog.jpg'
+    end
+  end
+
+  describe 'rake assets:precompile:embed' do
+    before { precompile_assets!(embed: true) }
+    it_behaves_like 'precompiled assets', embed: true
+
+    context 'recompiling with unembedded assets' do
+      before { precompile_assets!(embed: false) }
+      it_behaves_like 'precompiled assets', embed: false
+    end
+  end
+
+  describe 'rake assets:precompile:unembed' do
+    before { precompile_assets!(embed: false) }
+    it_behaves_like 'precompiled assets', embed: false
+
+    context 'recompiling with embedded assets' do
+      before { precompile_assets!(embed: true) }
+      it_behaves_like 'precompiled assets', embed: true
+    end
+  end
+end

data/lib/embeddable_asset/version.rb

@@ -0,0 +1,3 @@
+module EmbeddableAsset
+  VERSION = "1.0.0"
+end

data/lib/tasks/precompile_embeddable_assets.rake

@@ -0,0 +1,27 @@
+namespace :assets do
+  desc 'precompile assets while embedding assets designated with ENV["EMBED_ASSETS"]=yes'
+  task 'precompile:embed' => :environment do
+    compile_assets_as(embed: 'yes')
+  end
+
+  desc 'precompile assets without embedding assets'
+  task 'precompile:unembed' => :environment do
+    compile_assets_as(embed: nil)
+  end
+
+  desc 'completely remove compiled assets'
+  task 'remove' => :environment do
+    if Rake::Task.task_defined?('assets:clobber')
+      Rake::Task['assets:clobber'].execute
+    else
+      Rake::Task['assets:clean'].execute
+    end
+  end
+
+  def compile_assets_as(options={})
+    ENV['EMBED_ASSETS'] = options[:embed]
+    Rake::Task['assets:remove'].execute
+    Rake::Task['tmp:cache:clear'].execute
+    Rake::Task['assets:precompile'].execute
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: embeddable_asset
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- John McCormack
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-03-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |-
+  Simple Gem that provides CSS and Sass helpers
+                              to conditionally embed or unembed your assets via rake tasks.
+email:
+- mccormjt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/stylesheets/_embeddable_asset.scss.erb
+- config/initializers/expose_asset_pipeline_embeddable_helpers.rb
+- embeddable_asset.gemspec
+- lib/embeddable_asset.rb
+- lib/embeddable_asset/asset_pipeline_helper.rb
+- lib/embeddable_asset/rails/engine.rb
+- lib/embeddable_asset/test/embeddable_rake_task_examples.rb
+- lib/embeddable_asset/version.rb
+- lib/tasks/precompile_embeddable_assets.rake
+homepage: https://github.com/enova/embeddable_asset
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Dynamically embed your assets into your Stylesheets
+test_files: []