@@ -1,4 +1,7 @@ module Gluttonberg + # This module allows custom controllers to be registered wtih Gluttonberg’s + # administration. Typically, these controllers will be registered in the + # application’s before_app_loads block. module Components @@components = {} @@routes = {} @@ -6,23 +9,26 @@ module Gluttonberg @@registered = nil Component = Struct.new(:name, :label) - # Components.register(:forum, :label => "Forum", :admin_url => url) do |scope| - # scope.resources(:posts) - # scope.resources(:threads) - # end + # Registers a controller — or set of controllers — based on the URLs + # specified in the routes. + # + # Components.register(:forum, :label => "Forum", :admin_url => url) do |scope| + # scope.resources(:posts) + # scope.resources(:threads) + # end def self.register(name, opts = {}, &routes) @@components[name] = opts @@routes[name] = routes if block_given? end + # Returns a hash of the registered components, keyed to their label. def self.registered @@registered ||= @@components.collect {|k, v| Component.new(k.to_s, v[:label])} end - def self.routes - @@routes - end - + # Returns an array of components that have been given a nav_label — + # the label implicitly registers them as nav entries. Components without + # a label won’t turn up. def self.nav_entries @@nav_entries ||= @@components.collect do |k, v| url = if v[:admin_url] gluttonberg/lib/gluttonberg/components.rb @@ -7,7 +7,11 @@ require content / "content" / "textilized" require content / "content" / "text_filters" require content / "content" / "publishable" require content / "content" / "workflow" + module Gluttonberg + # The content module contains a whole bunch classes and mixins related to the + # pages, localizations, content models and helpers for rendering content + # inside of views. module Content @@content_associations = nil @@non_localized_associations = nil @@ -38,14 +42,21 @@ module Gluttonberg @@content_associations = content_classes.collect { |k| k.association_name } end + # This is used inside of the Content::Block mixin. When that mixin is + # included in a class, the mixin registers it automatically via this method. def self.register_as_content(klass) @@content_classes << klass unless @@content_classes.include? klass end + # Returns an array of classes that have been declared as "content". def self.content_classes @@content_classes end + # For each content class that is registered, a corresponding association is + # declared against the Page model. We need to keep track of these, which + # is what this method does. It just returns an array of the association + # names. def self.non_localized_associations @@non_localized_associations ||= begin non_localized = @@content_classes.select {|c| !c.localized? } @@ -53,18 +64,24 @@ module Gluttonberg end end + # Return the collection of content association names. def self.content_associations @@content_associations end + # If a content class has the is_localized declaration, this method is used + # to register it so we can keep track of all localized content. def self.register_localization(assoc_name, klass) @@localizations[assoc_name] = klass end + # Returns a hash of content classes that are localized, keyed to the + # association name. def self.localizations @@localizations end + # Returns an array of the localization association names. def self.localization_associations @@localization_associations end gluttonberg/lib/gluttonberg/content.rb @@ -2,8 +2,10 @@ module Gluttonberg module Content # This module can be mixed into a class to make it behave like a content # block. A content block is a class that can be associated with a section - # on a page. + # on in a page description. module Block + # This included hook is used to declare the various properties and class + # ivars we need. def self.included(klass) klass.class_eval do extend Block::ClassMethods @@ -36,8 +38,11 @@ module Gluttonberg end module ClassMethods - # TODO: Have this create an alias between the parent and localization's - # properties. Maybe use the Delegate model. + # This declaration is used to create properties on a model which need + # to be localized. It does this by generating a localized class and + # association. + # + # It also registers the class as being localized. def is_localized(&blk) self.localized = true @@ -84,14 +89,19 @@ module Gluttonberg end module InstanceMethods + # Returns the section this content instance is associated with. It does + # this by looking at the associated page, it’s description then the + # matching section. def section @section ||= page.description.sections[section_name.to_sym] end + # Checks to see if this content class has localized properties. def localized? self.class.localized? end + # The name of the generated association. This is the association that def association_name self.class.association_name end @@ -104,7 +114,8 @@ module Gluttonberg section[:label] end - # Just delegates to the class. + # Content type is simply the inflected version of the content class + # name, e.g. FooContent becomes :foo_content def content_type self.class.content_type end gluttonberg/lib/gluttonberg/content/block.rb @@ -1,5 +1,10 @@ module Gluttonberg module Content + # The mixin used when generating a localization for content classes. It + # adds the base properties — e.g. id — and associations. It also comes with + # some convenience methods for accessing the associated section in a page. + # + # These just defer to the parent class. module BlockLocalization def self.included(klass) klass.class_eval do @@ -30,4 +35,4 @@ module Gluttonberg end end end -end \ No newline at end of file +end gluttonberg/lib/gluttonberg/content/block_localization.rb @@ -1,6 +1,11 @@ module Gluttonberg module Content + # A mixin with allows for any arbitrary model to be localized. It will + # generate the localization models and add methods for creating and + # retrieving localized versions of a record. module Localization + # The included hook is used to create a bunch of class ivars we need to + # store various bits of configuration. def self.included(klass) klass.class_eval do extend Model::ClassMethods gluttonberg/lib/gluttonberg/content/localization.rb @@ -1,40 +1,52 @@ module Gluttonberg module Content + # A mixin that will add simple publishing functionality to any arbitrary + # model. This includes finders for retrieving published records and + # instance methods for quickly changing the state. module Publishable - + # Add the class and instance methods, declare the property we store the + # published state in. def self.included(klass) klass.class_eval do - property :published, DataMapper::Types::Boolean, :default => false - extend ClassMethods - include InstanceMethods - end + extend ClassMethods + include InstanceMethods + + property :published, DataMapper::Types::Boolean, :default => false + end end module ClassMethods - def published(options = {}) - options[:published] = true - first(options) - end - def all_published(options = {}) - options[:published] = true - all(options) - end + # Returns the first matching record that is published. May be called + # with additional conditions. + def published(options = {}) + options[:published] = true + first(options) + end + + # Returns all matching records that are published. May be called + # with additional conditions. + def all_published(options = {}) + options[:published] = true + all(options) + end end module InstanceMethods - - def publish! - update_attributes(:published=>true) - end - def unpublish! - update_attributes(:published=>false) - end - def published? - @published - end + # Change the publish state to true and save the record. + def publish! + update_attributes(:published=>true) + end + + # Change the publish state to false and save the record. + def unpublish! + update_attributes(:published=>false) + end + + # Check to see if this record has been published. + def published? + @published + end end - - - end - end -end \ No newline at end of file + end # Publishable + end # Content +end # Gluttonberg gluttonberg/lib/gluttonberg/content/publishable.rb @@ -1,21 +1,37 @@ module Gluttonberg module Content + # The text filters module is used to extend Textile in a sneaky way. Within + # any textual content in the site, users can use custom syntax for inserting + # additional content. Typically this is used with textile, but will work + # inside of any text. + # + # The actual filters themselves are implemented as Merb parts. This gives + # them access to all the lovely filtering and rendering found in controllers. + # + # Parts can be turned into a filter by including the module + # Gluttonberg::TextFilters::PartMixin and then calling the is_text_filter + # declaration. module TextFilters @@filters = {} + # Returns all registered filters as a hash, keyed to the filter name. def self.all @@filters.values end + # Get a specific filter by name. def self.get(name) @@filters[name.to_sym] end + # Register a part controller as a filter. Generally doesn’t need to be + # called, since the is_text_filter declaration calls this under the hood. def self.register(name, klass) @@filters[name.to_sym] = klass end module PartMixin + # A declaration for defining this part controller as a text filter. def is_text_filter(name) Gluttonberg::Content::TextFilters.register(name, self) end gluttonberg/lib/gluttonberg/content/text_filters.rb @@ -1,16 +1,25 @@ module Gluttonberg module Content + # A module for adding textile formatting to models. Just include this + # module, then for each field that you would like to textilize, just + # include it in the is_textilized declaration. Like so: + # + # is_textilized, :summary, :body + # module Textilized + # The hook that adds the ivars, then includes/extends with the _real_ + # modules. def self.included(klass) klass.class_eval do class << self; attr_accessor :textilized_fields end extend ClassMethods include InstanceMethods end - end module ClassMethods + # The declaration for adding a field to the list of those to be + # formatted. def is_textilized(*fields) self.textilized_fields = {} fields.each do |field| @@ -23,7 +32,9 @@ module Gluttonberg module InstanceMethods private - + # The before filter called on save. This does the actual + # convertoranting of the textile to markup and stores it in the + # generated property. def convert_textile_text_to_html self.class.textilized_fields.each do |field, formatted_field| if attribute_dirty?(field) || (attribute_get(field) && attribute_get(formatted_field).nil?) @@ -32,6 +43,6 @@ module Gluttonberg end end end - end - end -end + end # Textilized + end # Content +end # Gluttonberg gluttonberg/lib/gluttonberg/content/textilized.rb @@ -1,51 +1,66 @@ module Gluttonberg module Content + # A mixin which provides a super simple publish/approve workflow for a + # model. A state machine this is not. + # + # The states are :in_progress, :pending, :approved, :rejected + # + # For each state there is an instance method for setting and saving that + # state. There are some additional class methods for retrieving the pending + # or rejected records. module Workflow - def self.included(klass) - klass.class_eval do - property :state, DataMapper::Types::Enum[:in_progress, :pending, :rejected , :approved], :default => :in_progress - extend ClassMethods - include InstanceMethods - end - + extend ClassMethods + include InstanceMethods + + property :state, DataMapper::Types::Enum[:in_progress, :pending, :rejected , :approved], :default => :in_progress + end end module ClassMethods + # Returns all records with the pending state. May take additional + # conditions. + def all_pending(options = {}) + options[:state] = :pending + all(options) + end - def all_pending(options = {}) - options[:state] = :pending - all(options) - end + # Returns all records with the rejected state. May take additional + # conditions. + def all_rejected(options = {}) + options[:state] = :rejected + all(options) + end - def all_rejected(options = {}) - options[:state] = :rejected - all(options) - end - - def all_approved_and_published(options = {}) - options.merge!( :state => :approved , :published => true ) - all(options) - end + # Returns all records with the approved state and additionally with the + # publish flag set. The publish flag is managed by the Publishable mixin, + # so obviously it need to be included in the model for this method to + # work. + # + # Extra conditions can also be passed in. + def all_approved_and_published(options = {}) + options.merge!(:state => :approved , :published => true) + all(options) + end end module InstanceMethods - - def submit! - update_attributes(:state=>:pending) - end - - def approve! - update_attributes(:state=>:approved) - end - - def reject! - update_attributes(:state=>:rejected) - end + # Sets the state to :pending and saves the record. + def submit! + update_attributes(:state => :pending) + end + + # Sets the state to :approved and saves the record. + def approve! + update_attributes(:state=>:approved) + end + + # Sets the state to :rejected and saves the record. + def reject! + update_attributes(:state=>:rejected) + end end - - - end - end -end \ No newline at end of file + end # Workflow + end # Content +end # Gluttonberg gluttonberg/lib/gluttonberg/content/workflow.rb 6afff16ea158df1a755ff2ed2f2353f29d1a7218 Luke Sutton luke@freerangefuture.com http://github.com/FreerangeFuture/gluttonberg/commit/6c803d98eb53e7e1c73df43efe3728c4e3130ea7 6c803d98eb53e7e1c73df43efe3728c4e3130ea7 2009-05-26T23:47:18-07:00 2009-05-26T23:47:18-07:00 Bunch of documentation for the content modules and classes. adaa5058548701ee523b3447c97b29376f3cd6e8 Luke Sutton luke@freerangefuture.com