fragmentary 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9495373cf7b72c44963e4bedd39960bf08d81d90
-  data.tar.gz: 85c2c4605899af9dd9a9907f395c3eb70685fdc5
+  metadata.gz: ce71afcd11d78930295c8839ee9519b2bb504f40
+  data.tar.gz: 354eee986e23c365e958807f3024ebb571e6b7e8
 SHA512:
-  metadata.gz: bec32e4de3fbc9427d359c93872f4edf964d1d43dc96d160f38067d15fe2288e84034eaedef54f06d5986c80672dc2d645c819c4149806b36d45a4f1b0966480
-  data.tar.gz: cb92de732842410aa5a1126214ff3feb9ccf19a377cbf4f9ef4fb5abc6c2b886efa660796cb0b1d99f0244a3c2d697783a582287fb038009f43b6e19277847f9
+  metadata.gz: cecfed68ceed46c1d174c5f967769ae4c6bc9608f09675e3d693958c931be25e8adaf58c497755197549e83959756a14e67e4cf50fd52cd58ac9b1e5cfe31c6e
+  data.tar.gz: fb4fca48abf783d5fd7faa24147b4c55164444341c21bdf936107562cf112fef55a183f34855bf42076bf8bc3a747ece32f1d61d818bd3e507b7411610163d3c

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+### 0.2.1
+- Fixes a syntax bug in validating a fragment's root_id
+- Adds README documentation on the use of methods for explicitly retreving user-dependent fragments.
+- Adds README documentation on the needs_user_id declaration
+- Deprecates the :template parameter in FragmentsHelper#fragment_builder
+- Adds minor performance enhancements
+
 ### 0.2.0
 - Makes the following configurable:
   - current_user_method - called on current template to obtain the current authenticated user.

data/README.md

@@ -110,7 +110,7 @@ class Product < ActiveRecord::Base
 end
 ```
 
-Create a Fragment subclass (e.g. in app/models/fragments.rb or elsewhere) for each distinct fragment type that your views contain. If a particular fragment type needs to be unique by the id of some application data record, specify the class of the application model as shown in the example below.
+Create a `Fragment` subclass (e.g. in app/models/fragments.rb or elsewhere) for each distinct fragment type that your views contain. If a particular fragment type needs to be unique by the id of some application data record, specify the class of the application model as shown in the example below.
 ```
 class ProductTemplate < Fragment
   needs_record_id :type => 'Product'
@@ -122,7 +122,7 @@ Here `needs_record_id` indicates that there is a separate `ProductTemplate` frag
 
 We've used this, for example, for fragment types representing different kinds of list items that have certain generic characteristics but are used in different contexts to represent different kinds of content.
 
-Within the body of the fragment class definition, for each application model whose records the content of the fragment depends upon, use the `subscribe_to` method with a block containing method definitions to handle create, update and destroy events on your application data, typically to touch the fragment records affected by the application data change. The names of these methods follow the form used in the wisper-activerecord gem, i.e. `create_<model_name>_successful`, `update_<model_name>_successful` and `destroy_<model_name>_successful`, each taking a single argument representing the application data record that has changed.
+Within the body of the fragment subclass definition, for each application model whose records the content of the fragment depends upon, use the `subscribe_to` method with a block containing method definitions to handle create, update and destroy events on your application data, typically to touch the fragment records affected by the application data change. The names of these methods follow the form used in the wisper-activerecord gem, i.e. `create_<model_name>_successful`, `update_<model_name>_successful` and `destroy_<model_name>_successful`, each taking a single argument representing the application data record that has changed.
 
 Within the body of each method you define within the `subscribe_to` block, you can retrieve and touch the fragment records affected by the change in application data. The method `touch_fragments_for_record` can be used for convenience. That method takes an individual application data record or record_id or an array of either. So, for example, if product listings include the names of all the categories the products belong to, with those categories being represented by a separate ActiveRecord model, and the wording of a category name changes, you could handle that as follows.
 ```
@@ -140,7 +140,7 @@ The effect of this will be to expire the product template fragment for every pro
 
 When implementing the method definitions within the `subscribe_to` block, note that the block will be executed against an instance of a separate `Fragmentary::Subscriber` class that acts on behalf of the particular `Fragment` subclass we are defining (so the methods we define within the block are actually defined on that subscriber object). However, _all other_ methods called on the `Subscriber` object, including those called from within the methods we define in the block, are delegated by `method_missing` to the fragment subclass. So in the example, `touch_fragments_for_record` called from within `update_product_category_successful` represents `ProductTemplate.touch_fragments_for_record`. This method is defined by the `Fragment` class, so is available to all fragment subclasses.
 
-Note also that for fragment subclasses that declare `needs_record_id`, there is no need define a `destroy_<model_name>_successful` method simply to remove a fragment whose `record_id` matches the `id` of a <model_name> application record that is destroyed, e.g. to destroy a `ProductTemplate` whose `record_id` matches the `id` of a destroyed `Product` object. Fragmentary handles this clean-up automatically. This is not to say, however, that 'destroy' handlers are never needed at all. The destruction of an application data record will often require other fragments to be touched.
+Note also that for fragment subclasses that declare `needs_record_id`, there is no need to define a `destroy_<model_name>_successful` method simply to remove a fragment whose `record_id` matches the `id` of a <model_name> application record that is destroyed, e.g. to destroy a `ProductTemplate` whose `record_id` matches the `id` of a destroyed `Product` object. Fragmentary handles this clean-up automatically. This is not to say, however, that 'destroy' handlers are never needed at all. The destruction of an application data record will often require other fragments to be touched.
 
 ### View Setup
 
@@ -157,7 +157,7 @@ A 'root' fragment is one that has no parent. In the template in which a root fra
 
 #### Nested Fragments
 
-The variable `fragment` that is yielded to the block above is an object of class `Fragmentary::FragmentsHelper::CacheBuilder`, which contains both the actual ActiveRecord fragment record found or created by `cache_fragment` *and* the current template as instance variables. Apart from its constructor and accessors, the class has one instance method, `cache_child` which can be used to define a child fragment nested within the first. The method is used _within_ a block of content defined by `cache_fragment` and much like `cache_fragment` it takes a hash of options that uniquely identify the child fragment. Also like `cache_fragment` it yields another `CacheBuilder` object and wraps a block containing the content of the child fragment to be cached.
+The variable `fragment` that is yielded to the block above is an object of class `Fragmentary::FragmentsHelper::CacheBuilder`, which contains both the actual ActiveRecord fragment record found or created by `cache_fragment` *and* the current template as instance variables. The class has one public instance method defined, `cache_child`, which can be used to define a child fragment nested within the first. The method is used _within_ a block of content defined by `cache_fragment` and much like `cache_fragment` it takes a hash of options that uniquely identify the child fragment. Also like `cache_fragment` it yields another `CacheBuilder` object and wraps a block containing the content of the child fragment to be cached.
 ```
 <% cache_fragment :type => 'ProductTemplate', :record_id => @product.id do |fragment| %>
   <% fragment.cache_child :type => 'StoresAvailable' do |child_fragment| %>
@@ -310,9 +310,16 @@ Whether you specify the user type mapping in Fragmentary's configuration or in a
 
 
 #### Per-User Customization
-While storing different versions of fragments is a workable solution for different groups of users, sometimes content needs to be customized for individual users. Doing this at any realistic scale would likely introduce significant cost and performance challenges. To address this we provide a way for user-specific content (in general any content) to be inserted into a cached fragment _after_ it has been retrieved from the cache through the use of a special placeholder string in a view template.
+While storing different versions of fragments is a workable solution for different groups of users, sometimes content needs to be customized for individual users. It is _possible_ to accomplish this by defining a fragment subclass with the declaration `needs_user_id`:
+```
+class MyFragment < Fragment
+  needs_user_id
+  ...
+end
+```
+You will also need to include a `user_id` column in the migration used to create your fragments database table. The `needs_user_id` declaration will result in separate fragments being created for each individual user. As in the case of `needs_user_type`, the `user_id` parameter is automatically extracted from your configured (or default) `current_user_method`.
 
-To accomplish this, two classes are defined, `Fragmentary::Widget` and a subclass `Fragmentary::UserWidget`. Instances of these classes represent chunks of content that will be inserted into a fragment after it has been either rendered and stored or retrieved from the cache. For each type of insertable content you wish your application to support, define a specific subclass of one of these classes (`UserWidget` is preferred if the content is to be user-specific) with two instance methods:
+However this approach is _not_ generally recommended as doing so at any realistic scale is likely to introduce significant cost and performance challenges. Instead, we provide a way for user-specific content (in general any content) to be inserted into a cached fragment _after_ it has been retrieved from the cache through the use of a special placeholder string in a view template. To accomplish this, two classes are defined, `Fragmentary::Widget` and a subclass `Fragmentary::UserWidget`. Instances of these classes represent chunks of content that will be inserted into a fragment after it has been either rendered and stored or retrieved from the cache. For each type of insertable content you wish your application to support, define a specific subclass of one of these classes (`UserWidget` is preferred if the content is to be user-specific) with two instance methods:
 - `pattern`, which returns a `Regexp` that will be used to detect a placeholder you will use in your template at the point where you wish the inserted content to be placed. The placeholder consists of a string matching the regular expression you specify wrapped in special delimiter characters `%{...}`.
 - `content`, which returns the string that will be inserted in place of the placeholder.
 
@@ -412,7 +419,15 @@ Of course if you have to render the content in order to determine whether it nee
 <% end %>
 ```
 
-Note the use above of the method `Fragment.root` to retrieve the fragment after caching has occurred. The method takes the same parameters as `cache_fragment` and returns a matching fragment (calling the method after caching guarantees that it will exist since caching instantiates the fragment if it doesn't already exist). We have to retrieve the fragment explicitly since the variable `fragment` is local to the block to which it is yielded. Also note that although `fragment` is actually a `CacheBuilder` object, that class uses `method_missing` to pass any methods, such as `update_attribute`, to the underlying fragment.
+Note that we update the fragment's `memo` attribute by calling `update_attribute` on the `fragment` object. Although this is actually a `CacheBuilder` object, that class passes any methods such as `update_attribute` to the underlying fragment.
+
+Also note the use above of the method `Fragment.root` to retrieve the fragment matching the supplied parameters after caching has occurred. We have to retrieve the fragment explicitly since the variable `fragment` is local to the `cache_fragment` block to which it is yielded. The method takes the same parameters as `cache_fragment` with one exception: At present, if your fragment class declares `needs_user_type` or `needs_user_id`, you need to explicitly pass either the respective parameter or the current user object (this may change in a future release). e.g.
+
+```
+...
+<% root_fragment = Fragment.root(:type => 'ProductTemplate', :record_id => @product.id, :user => current_user).memo == required_memo_value %>
+...
+```
 
 The process for child fragments is similar, except that an instance method Fragment#child can be called on the parent fragment in order to retrieve the fragment to be tested. e.g.
 
@@ -430,7 +445,7 @@ The process for child fragments is similar, except that an instance method Fragm
 <% end %>
 ```
 
-In both of these examples, the fragment to be tested is retrieved after caching. If relying on side-effects doesn't make you too queasy, you can alternatively retrieve it before caching, in which case the fragment can be passed to `cache_fragment` or `cache_child` as appropriate instead of the set of fragment attributes we used before. This avoids the need for `cache_fragment` or `cache_child` to retrieve the fragment internally. e.g.
+In both of these examples, the fragment to be tested is retrieved after caching. If relying on side-effects doesn't make you too queasy, you can alternatively retrieve it before caching, in which case the retrieved fragment can be passed to `cache_fragment` or `cache_child` as appropriate instead of the set of fragment attributes we used before. This avoids the need for `cache_fragment` or `cache_child` to retrieve the fragment themselves internally, e.g.
 ```
 <% root_fragment = Fragment.root(:type => 'ProductTemplate', :record_id => @product.id) %>
 <% conditional_content = capture do  %>
@@ -456,7 +471,7 @@ Note that both `Fragment.root` and `Fragment#child` will instantiate a matching
   <% end %>
 
   <% if child.memo == required_memo_value %>
-  <%= conditional_content %>
+    <%= conditional_content %>
   <% end %>
 
 <% else %>
@@ -471,7 +486,7 @@ Note that both `Fragment.root` and `Fragment#child` will instantiate a matching
 
 When application data that a cached fragment depends upon changes, i.e. as a result of a POST, PATCH or DELETE request, the `subscribe_to` declarations in your `Fragment` subclass definitions ensure that the `updated_at` attribute of any existing fragment records affected will be updated. Then on subsequent browser requests, the cached content itself will be refreshed.
 
-As part of this process, new fragment records may be created as *children* of an existing fragment if the existing fragment contains newly added list items. A new *root* fragment, on the other hand, will be created for any root fragment class defined with `needs_record_id` if an application data record of the associated `record_type` is created, as soon as a browser request is made to the new page (or new content in the case of an AJAX request) containing that fragment.
+As part of this process, new fragment records may be created as *children* of an existing fragment if the existing fragment contains newly added list items. A new *root* fragment, on the other hand, will be created for any root fragment class defined with `needs_record_id` if an application data record of the associated `record_type` is created, as soon as a browser request is made for the new content (often a new page) containing that fragment.
 
 Sometimes, however, it is desirable to avoid having to wait for an explicit request from a user in order to update the cache or to create new cached content. To deal with this, Fragmentary provides a mechanism to automatically create or refresh cached content preemptively, essentially as soon as a change in application data occurs. Rails' `ActionDispatch::Integration::Session` [class](https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/testing/integration.rb) provides an interface that allows requests to be sent directly to the application programmatically, without generating any external network traffic. Fragmentary uses this interface to automatically send requests needed to update the cache whenever changes in application data occur.
 
@@ -487,7 +502,7 @@ end
 ```
 Since nested child fragments automatically touch their parent fragments when they themselves are updated, internal requests can be initiated by an update to application data that affects a fragment anywhere within a page. Only the root fragment needs to define the request path.
 
-The request that is generated will be sent to the application at the `request_path` specified, but it may also include additional request parameters and options. To send HTTP request parameters with the request, the Fragment subclass should define an additional instance method `request_parameters` that returns a hash of named parameters. To send an XMLHttpRequest, a class should define an instance method `request_options` that returns the hash `{:xhr => true}`.
+The request that is generated will be sent to the application at the `request_path` specified, but it may also include additional request parameters and options. To send HTTP request parameters with the request, the `Fragment` subclass should define an additional instance method `request_parameters` that returns a hash of named parameters. To send an XMLHttpRequest, a class should define an instance method `request_options` that returns the hash `{:xhr => true}`.
 
 In the case of a root fragment that *does not* yet exist, i.e. for a `Fragment` subclass defined with `needs_record_id` and an associated `record_type` when a new application record of that type is first created, a request will be generated in order to create the new fragment automatically if the subclass has a *class* method `request_path` defined that takes the `id` of the newly created application record and returns a string representing the path to which the request should be sent. For example:
 ```
@@ -515,7 +530,7 @@ The set of user types that an individual `Fragment` subclass is expected to supp
 
 Configuration of the `user_types` method is discussed in the next section. Fragmentary uses the types returned by this method to identify the request queues that each internal application request needs to be added to when instances of each particular `Fragment` subclass are updated. `Fragment` subclasses inherit both class and instance methods `request_queues` that return a hash of queues keyed by each of the specific user type strings that that specific subclass supports.
 
-The request queue for any given user type is shared across all Fragment subclasses within the application. So for example, a `ProductTemplate` fragment may have two different request queues, `ProductTemplate.request_queues["admin"]` and `ProductTemplate.request_queues["signed_in"]`. If a `StoreTemplate` fragment has one request queue `StoreTemplate.request_queues["signed_in"]`, the `"signed_in"` queues for both classes represent the same object.
+The request queue for any given user type is shared across all `Fragment` subclasses within the application. So for example, a `ProductTemplate` fragment may have two different request queues, `ProductTemplate.request_queues["admin"]` and `ProductTemplate.request_queues["signed_in"]`. If a `StoreTemplate` fragment has one request queue `StoreTemplate.request_queues["signed_in"]`, the `"signed_in"` queues for both classes represent the same object.
 
 #### Configuring Internal Request Users
 
@@ -591,7 +606,7 @@ MyFragment.queue_request(request)
 
 Off-loading internal application requests to an asynchronous process as noted in the previous section means they can occur without delaying the server's response to the user's initial external request. However, in a complex application there may also be some overhead just in the process of updating fragment records that is not critical in order to send a response back to the user. For example, some application data changes may require a large number of fragments to be updated on pages other than the one the user is going to be sent or redirected to right away. In this case, we may wish to offload the task of updating these fragments to an asynchronous process as well.
 
-Fragmentary accomplishes this by means of the `Fragmentary::Handler` class. An individual task you wish to be handled asynchronously is created by defining a subclass of `Fragmentary::Handler`, typically within the scope of the Fragment subclass in which you wish to use it. The `Handler` subclass you define requires a single instance method `call`, which defines the task to be performed.
+Fragmentary accomplishes this by means of the `Fragmentary::Handler` class. An individual task you wish to be handled asynchronously is created by defining a subclass of `Fragmentary::Handler`, typically within the scope of the `Fragment` subclass in which you wish to use it. The `Handler` subclass you define requires a single instance method `call`, which defines the task to be performed.
 
 To use the handler, typically within a fragment's `subscribe_to` declaration, call the inherited class method `create`, passing it a hash of named arguments. Those arguments can then be accessed within your `call` method as the instance variable `@args`. Consider our earlier example in which each product template contains a list of stores in which the product is available. Suppose an administrator fixes a typographical error in the name of a store. That correction needs to propagate to every `AvailableStore` fragment for every product that is available in that store. We can do this using a Handler as follows:
 ```
@@ -601,7 +616,7 @@ class AvailableStore < Fragment
   class UpdateStoreHandler < Fragmentary::Handler
     def call
       product_stores = ProductStore.where(:store_id => @args[:id])
-      touch_fragment_for_record(product_stores)
+      touch_fragments_for_record(product_stores)
     end
   end
 
@@ -649,7 +664,7 @@ end
 
 ### Updating Fragments Explicitly Within a Controller
 
-The typical usage scenario for Fragmentary is for fragment records to be updated by the methods defined in the `subscribe_to` blocks you create in your fragment subclasses, in response to user requests that modify the application data. This involves very little coupling between your application's controllers and models and the fragment caching process. Models need only include the `Fragmentary::Publisher` module to ensure that `Fragment` subclasses can subscribe to the application data events that trigger fragment updates. Your `ApplicationController` only needs to ensure that any queued internal requests and asynchronous fragment update tasks are dispatched (if you choose to use either of those features) before sending a response to the user's browser. Application models and controllers generally have no need to access the Fragment class API.
+The typical usage scenario for Fragmentary is for fragment records to be updated by the methods defined in the `subscribe_to` blocks you create in your fragment subclasses, in response to user requests that modify the application data. This involves very little coupling between your application's controllers and models and the fragment caching process. Models need only include the `Fragmentary::Publisher` module to ensure that `Fragment` subclasses can subscribe to the application data events that trigger fragment updates. Your `ApplicationController` only needs to ensure that any queued internal requests and asynchronous fragment update tasks are dispatched (if you choose to use either of those features) before sending a response to the user's browser. Application models and controllers generally have no need to access the `Fragment` class API.
 
 Ocassionally, however, a situation may arise in which it is useful to touch fragments directly from a controller. For example, an application data event may occur that requires fragments to be updated on a large number of different pages within your site. This is the kind of scenario in which you might choose to offload fragment updating to a `Fragmentary::Handler` and execute the task asynchronously as described in the previous section. However, it may also be that *one* of those pages is the one that is going to be sent back to the user's browser immediately in response to the current request. You can't put off touching the affected fragment on that one page until the asynchronous process executes because then the user won't see the updated content. In a scenario like this, you also can't detect within the `subscribe_to` block in your fragment subclass definition which one fragment needs to be touched immediately rather than asynchronously, since the fragment class has no knowledge of the internal state of the controller.
 
@@ -710,9 +725,9 @@ However, it's possible for the partial to contain a cached fragment that happens
   </ul>
 <% end %>
 ```
-In the Javascript case, however, since the template only renders the new list item and not the list as a whole, there is no `cache_fragment` method invoked in order to yield the `CacheBuilder` object, and so we have to construct it explicitly. To do this, Fragmentary provides a helper method `fragment_builder` that takes an options hash containing the parameters that define the fragment (the same ones passed to `cache_fragment`) plus the current template and returns the `CacheBuilder` object that the partial needs.
+In the Javascript case, however, since the template only renders the new list item and not the list as a whole, there is no `cache_fragment` method invoked in order to yield the `CacheBuilder` object, and so we have to construct it explicitly. To do this, Fragmentary provides a helper method `fragment_builder` that takes an options hash containing the parameters that define the fragment (the same ones passed to `cache_fragment`) and returns the `CacheBuilder` object that the partial needs.
 ```
-<% parent_fragment = fragment_builder(:type => 'ProductList', :template => self) %>
+<% parent_fragment = fragment_builder(:type => 'ProductList') %>
 $('ul.product_list').append('<%= j(render 'product/summary', :product => @product,
                                                              :parent_fragment => parent_fragment) %>')
 ```
@@ -723,7 +738,7 @@ The second challenge in dealing with child fragments rendered without the contex
 
 To address this, `cache_child` can take an additional boolean option, `:insert_widgets` that can be used to force the insertion of widgets into the child. Typically a local variable containing the value of this option would be passed to the partial in which `cache_child` appears. In the Javascript template:
 ```
-<% parent_fragment = fragment_builder(:type => 'ProductList', :template => self) %>
+<% parent_fragment = fragment_builder(:type => 'ProductList') %>
 $('ul.product_list').append('<%= j(render 'product/summary', :product => @product,
                                                              :parent_fragment => parent_fragment,
                                                              :insert_widgets => true) %>')

data/lib/fragmentary/fragment.rb

@@ -28,9 +28,9 @@ module Fragmentary
 
         attr_accessor :indexed_children
 
-        validate :root_id, :presence => true
+        validates :root_id, :presence => true
 
-        cache_timestamp_format = :usec  # Probably not needed for Rails 5, which uses :usec by default.
+        self.cache_timestamp_format = :usec  # Probably not needed for Rails 5, which uses :usec by default.
 
       end
 
@@ -49,9 +49,13 @@ module Fragmentary
     module ClassMethods
 
       def root(options)
-        klass, search_attributes, options = base_class.attributes(options)
-        fragment = klass.where(search_attributes).includes(:children).first_or_initialize(options); fragment.save if fragment.new_record?
-        fragment.set_indexed_children if fragment.child_search_key
+        if fragment = options[:fragment]
+          raise ArgumentError, "You passed Fragment #{fragment.id} to Fragment.root, but it's a child of Fragment #{fragment.parent_id}" if fragment.parent_id
+        else
+          klass, search_attributes, options = base_class.attributes(options)
+          fragment = klass.where(search_attributes).includes(:children).first_or_initialize(options); fragment.save if fragment.new_record?
+          fragment.set_indexed_children if fragment.child_search_key
+        end
         fragment
       end
 
@@ -90,16 +94,21 @@ module Fragmentary
         @@cache_store ||= Rails.application.config.action_controller.cache_store
       end
 
+      # ToDo: combine this with Fragment.root
       def existing(options)
-        options.merge!(:type => name) unless self == base_class
-        raise ArgumentError, "A 'type' attribute is needed in order to retrieve a fragment" unless options[:type]
-        klass, search_attributes, options = base_class.attributes(options)
-        # We merge options because it may include :record_id, which may be needed for uniqueness even
-        # for classes that don't 'need_record_id' if the parent_id isn't available.
-        fragment = klass.where(search_attributes.merge(options)).includes(:children).first
-        # Unlike Fragment.root and Fragment#child we don't instantiate a record if none is found,
-        # so fragment may be nil.
-        fragment.try :set_indexed_children if fragment.try :child_search_key
+        if fragment = options[:fragment]
+          raise ArgumentError, "You passed Fragment #{fragment.id} to Fragment.existing, but it's a child of Fragment #{fragment.parent_id}" if fragment.parent_id
+        else
+          options.merge!(:type => name) unless self == base_class
+          raise ArgumentError, "A 'type' attribute is needed in order to retrieve a fragment" unless options[:type]
+          klass, search_attributes, options = base_class.attributes(options)
+          # We merge options because it may include :record_id, which may be needed for uniqueness even
+          # for classes that don't 'need_record_id' if the parent_id isn't available.
+          fragment = klass.where(search_attributes.merge(options)).includes(:children).first
+          # Unlike Fragment.root and Fragment#child we don't instantiate a record if none is found,
+          # so fragment may be nil.
+          fragment.try :set_indexed_children if fragment.try :child_search_key
+        end
         fragment
       end
 
@@ -262,7 +271,7 @@ module Fragmentary
       # hasn't yet been requested, e.g. an assumption created on an article page won't necessarily have been rendered on the
       # opinion analysis page.
       def touch_fragments_for_record(record_id)
-        fragments_for_record(record_id).each(&:touch)
+        fragments_for_record(record_id).includes({:parent => :parent}).each(&:touch)
       end
 
       def fragments_for_record(record_id)
@@ -389,7 +398,10 @@ module Fragmentary
     # rendered on its own, e.g. inserted by ajax into a parent that is already on the page. In this case the
     # children won't have already been loaded or indexed.
     def child(options)
-      begin
+      if child = options[:child]
+        raise ArgumentError, "You passed a child fragment to a parent it's not a child of." unless child.parent_id == self.id
+        child
+      else
         existing = options.delete(:existing)
         # root_id and parent_id are passed from parent to child. For all except root fragments, root_id is stored explicitly.
         derived_options = {:root_id => root_id || id}
@@ -419,10 +431,7 @@ module Fragmentary
           fragment_children = fragment.children
           fragment.set_indexed_children if fragment.child_search_key
         end
-
         fragment
-      rescue => e
-        Rails.logger.error e.message + "\n " + e.backtrace.join("\n ")
       end
     end
 
@@ -466,10 +475,13 @@ module Fragmentary
       touch(:no_request => no_request) unless children.any?
     end
 
+    # Touch this fragment and all descendants that have entries in the cache. Destroy any that
+    # don't have cache entries.
     def touch_or_destroy
       puts "  touch_or_destroy #{self.class.name} #{id}"
       if cache_exist?
         children.each(&:touch_or_destroy)
+        # if there are children, this will be touched automatically once they are.
         touch(:no_request => true) unless children.any?
       else
         destroy  # will also destroy all children because of :dependent => :destroy

data/lib/fragmentary/fragments_helper.rb

@@ -2,56 +2,52 @@ module Fragmentary
 
   module FragmentsHelper
 
-    def cache_fragment(options)
-      no_cache = options.delete(:no_cache)
-      options.reverse_merge!(:user => Template.new(self).current_user)
-      fragment = options.delete(:fragment) || Fragmentary::Fragment.base_class.root(options)
-      builder = CacheBuilder.new(fragment, template = self)
-      unless no_cache
-        cache fragment, :skip_digest => true do
-          yield(builder)
-        end
-      else
-        yield(builder)
-      end
-      self.output_buffer = WidgetParser.new(self).parse_buffer
+    def cache_fragment(options, &block)
+      CacheBuilder.new(self).cache_fragment(options, &block)
     end
 
     def fragment_builder(options)
-      template = options.delete(:template)
+      # the template option is deprecated but avoids breaking prior usage
+      template = options.delete(:template) || self
       options.reverse_merge!(:user => Template.new(template).current_user)
-      CacheBuilder.new(Fragmentary::Fragment.base_class.existing(options), template)
+      CacheBuilder.new(template, Fragmentary::Fragment.base_class.existing(options))
     end
 
     class CacheBuilder
       include ::ActionView::Helpers::CacheHelper
       include ::ActionView::Helpers::TextHelper
 
-      attr_accessor :fragment, :template
+      attr_reader :fragment
 
-      def initialize(fragment, template)
+      def initialize(template, fragment = nil)
         @fragment = fragment
         @template = template
       end
 
-      def cache_child(options)
+      def cache_fragment(options, &block)
         no_cache = options.delete(:no_cache)
         insert_widgets = options.delete(:insert_widgets)
-        options.reverse_merge!(:user => Template.new(template).current_user)
-        child = options.delete(:child) || fragment.child(options)
-        builder = CacheBuilder.new(child, template)
+        options.reverse_merge!(:user => Template.new(@template).current_user)
+        # If the CacheBuilder was instantiated with an existing fragment, next_fragment is its child;
+        # otherwise it is the root fragment specified by the options provided.
+        next_fragment = @fragment.try(:child, options) || Fragmentary::Fragment.base_class.root(options)
+        builder = CacheBuilder.new(@template, next_fragment)
         unless no_cache
-          template.cache child, :skip_digest => true do
+          @template.cache next_fragment, :skip_digest => true do
             yield(builder)
           end
         else
           yield(builder)
         end
-        template.output_buffer = WidgetParser.new(template).parse_buffer if insert_widgets
+        @template.output_buffer = WidgetParser.new(@template).parse_buffer if (!@fragment || insert_widgets)
       end
 
+      alias cache_child cache_fragment
+
+      private
+
       def method_missing(method, *args)
-        fragment.send(method, *args)
+        @fragment.send(method, *args)
       end
 
     end
@@ -61,7 +57,6 @@ module Fragmentary
 
   # Just a wrapper to allow us to call a configurable current_user_method on the template
   class Template
-    attr_reader :template
 
     def initialize(template)
       @template = template
@@ -69,8 +64,8 @@ module Fragmentary
 
     def current_user
       return nil unless methd = Fragmentary.current_user_method
-      if template.respond_to? methd
-        template.send methd
+      if @template.respond_to? methd
+        @template.send methd
       else
         raise NoMethodError, "The current_user_method '#{methd.to_s}' specified doesn't exist"
       end

data/lib/fragmentary/publisher.rb

@@ -33,7 +33,7 @@ module Fragmentary
       end
 
       def after_update_broadcast
-        broadcast(:after_update, self)
+        broadcast(:after_update, self) if self.previous_changes.any?
       end
 
       def after_destroy_broadcast

data/lib/fragmentary/version.rb

@@ -1,3 +1,3 @@
 module Fragmentary
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/fragmentary/widget.rb

@@ -1,7 +1,7 @@
 module Fragmentary
 
   class Widget
-    attr_reader :template, :key, :match
+    attr_reader :template, :match
 
     def self.inherited subclass
       super if defined? super
@@ -18,7 +18,6 @@ module Fragmentary
 
     def initialize(template, key)
       @template = template
-      @key = key
       @match = key.match(pattern)
     end
 

data/lib/fragmentary/widget_parser.rb

@@ -31,7 +31,7 @@ module Fragmentary
             widget._content
           end
         else
-          "Oops! Widget not found."
+          "Oops! Widget for #{widget_key} not found."
         end
       end
       # The gsub replaces instances of '%' that aren't part of widget specifications with '%%', preventing

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fragmentary
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Mark Thomson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-01 00:00:00.000000000 Z
+date: 2020-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails