cloud_assets 0.0.2 → 0.0.3

data/README.md

@@ -1,8 +1,9 @@
+## cloud_assets
+
 cloud_assets enables a Rails app to make transparent use of
 assets on a remote server in an alternative technology.
 
-Principles and modes of operation
----------------------------------
+## Principles and modes of operation
 
 You can avoid incorporating static assets in your Rails
 app directly, if they exist somewhere else on the internet.
@@ -20,67 +21,128 @@ remote system, and rewrites URIs in such templates to
 point either to the local Rails system or a CDN, depending
 on configuration and utility.
 
-Installation
-------------
+## Installation
+
+Add cloud_assets to your Gemfile and bundle install, then
+define the necessary configuration in an initializer,
+e.g. config/initializers/cloud_assets.rb.
+
+If you don't define the initializer, all the important
+values will be read from the environment, which is extra
+handy if you are running on Heroku.
+
+This initializer will behave the same as no initializer;
+customize to your taste.
 
-1.
+```ruby
+CloudAssets.setup do |config|
 
-  Add cloud_assets to your Gemfile and bundle install, then
-  define the following in your environment.
+  # Required: origin URI for remote assets, e.g. http://yourhost.com
+  config.origin = ENV['CLOUD_ASSET_ORIGIN']
 
-  Required:
-  CLOUD_ASSET_ORIGIN - Origin URI for remote assets
+  # If needed: HTTP Basic user for remote assets
+  config.user = ENV['CLOUD_ASSET_USER']
 
-  Optional:
-  CLOUD_ASSET_CDN - Content delivery network, if any. This
-  is used to rewrite URIs for images and other large static
-  assets to the CDN instead of Rails.
+  # If needed: HTTP Basic user for remote password
+  config.password = ENV['CLOUD_ASSET_PASSWORD']
 
-  CLOUD_ASSET_USER, CLOUD_ASSET_PASSWORD - HTTP Basic
-  credentials which will be used when retrieving assets from
-  the cloud asset source.
+  # Rewrite URIs to use a CDN
+  config.cdn = ENV['CLOUD_ASSET_CDN']
 
-2.
+  # Activate verbose logging
+  config.verbose = false
 
-  Put a route at the bottom of your routes.rb:
+end
+```
 
-  match '*url' => 'cloud_assets#content'
+Put a route at the bottom of your routes.rb:
 
-  This will allow cloud_assets to handle anything Rails
-  doesn't recognize.
+```ruby
+match '*url' => 'cloud_assets#content'
+```
 
-3.
+This will allow cloud_assets to handle anything Rails
+doesn't recognize.
 
-  In application_controller.rb:
+In application_controller.rb:
 
-  include CloudAssets
+```ruby
+include CloudAssets
+```
 
-Additional Configuration
-------------------------
+## Additional Configuration
 
 If you are serving any non-trivial amount of remotely
 sourced assets out of your Rails system, you'll want a cache.
-cloud_assets likes memcached via dalli.
+FIXME: The cache currently uses dalli only. This should be
+and can be configured more flexibly in the initializer.
 
-To enable it, just define $hydra_cache somewhere in one of
+To enable it, just define $dalli_cache somewhere in one of
 your initializers.
 
-Usage
------
+## Usage
 
 Set a remote layout for an HTML view by defining the URI to
 the layout on the remote system, e.g.
 
-  set_remote_layout '/templates/foo.html'
+```ruby
+set_remote_layout '/templates/foo.html'
+```
 
 You can inject additional content into the elements of that
 template, or override the interior of its elements, using CSS
 selectors:
 
-  inject_into_remote_layout '#notice' => flash[:notice]
-  override_remote_layout 'body' => yield
+```ruby
+inject_into_remote_layout '#notice' => flash[:notice]
+override_remote_layout 'body' => yield
+replace_remote_layout '#unwanted_stuff' => 'wanted stuff'
+remove_remote_layout '.unwanted_classes'
+```
 
 Finally, obtain and show the result (complete with rewrites
 of CDN URLs and so on) with:
 
-  apply_remote_layout
+```ruby
+apply_remote_layout
+```
+
+So a complete application layout would look something like this (Haml):
+
+```
+- set_default_remote_layout '/about/'
+- inject_into_remote_layout 'head' => (render :partial => 'layouts/headers')
+- unless yield.empty?
+  - override_remote_layout '#content' => yield
+!= apply_remote_layout
+```
+
+This loads the HTML of the remote "about" page, rewrites references to
+localhost or the CDN as appropriate, injects Rails headers form the
+headers partial into the HTML head element, and replaces the interior
+of the element whose id is "content" -- say it's a div -- with the
+yield of the Rails view that uses this layout.
+
+## Fixups
+
+The remote site likely was not designed to have its HTML repurposed and
+rewritten on other sites. Sites following best practices *should* not
+need any manual fixups. However, any number of hacks might produce HTML
+that cloud_assets does not know how to rewrite. You have an opportunity
+to fix these by adding a monkey-patch to your initializer:
+
+```ruby
+module CloudAssets
+  def self.fixup_html(html)
+    html.gsub 'something bad', 'something good'
+  end
+end
+```
+
+This method is applied immediately before the HTML is delivered to the
+browser; you can do anything here that you like, but it should be
+regarded as a hack. If the uncorrectable code is standards-compliant
+and best practice, it would be good to submit a pull request so
+cloud_assets can handle it. If not, it would be ideal to fix the
+remote asset source -- e.g. remove hard-coded references or eliminate
+unwarranted assumptions.

data/lib/cloud_assets.rb

@@ -153,6 +153,17 @@ module CloudAssets
           @overrides.merge! hash
         end
 
+        def replace_remote_layout(hash)
+          if @replacements.nil?
+            @replacements = {}
+          end
+          @replacements.merge! hash
+        end
+
+        def remove_remote_layout(selector)
+          replace_remote_layout(selector => '')
+        end
+
         def set_remote_layout(layout)
           @remote_layout = layout
         end
@@ -177,6 +188,15 @@ module CloudAssets
             else
               doc = optimized_html_for @remote_layout
             end
+            unless @replacements.nil?
+              @replacements.each do |key, value|
+                begin
+                  doc.at_css(key).replace(value)
+                rescue
+                  puts "Failed to replace template element: #{key}"
+                end
+              end
+            end
             unless @overrides.nil?
               @overrides.each do |key, value|
                 begin
@@ -213,6 +233,8 @@ module CloudAssets
         include ControllerMethods
         helper_method :inject_into_remote_layout
         helper_method :override_remote_layout
+        helper_method :replace_remote_layout
+        helper_method :remove_remote_layout
         helper_method :set_remote_layout
         helper_method :set_default_remote_layout
         helper_method :apply_remote_layout

data/lib/cloud_assets/version.rb

@@ -1,3 +1,3 @@
 module CloudAssets
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloud_assets
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-26 00:00:00.000000000 Z
+date: 2012-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus
-  requirement: &70144157060340 !ruby/object:Gem::Requirement
+  requirement: &70170673604560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70144157060340
+  version_requirements: *70170673604560
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &70144157059580 !ruby/object:Gem::Requirement
+  requirement: &70170673603960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70144157059580
+  version_requirements: *70170673603960
 - !ruby/object:Gem::Dependency
   name: dalli
-  requirement: &70144157058760 !ruby/object:Gem::Requirement
+  requirement: &70170673602980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70144157058760
+  version_requirements: *70170673602980
 description: ! "\n    This gem is in use in some production sites to provide\n    backing
   for a Rails app using content from WordPress and\n    PostLaunch (a Java based CMS),
   and has specific\n    dependencies on Typhoeus, Nokogiri, and dalli, favorites\n