h1. Automatic Summaries

Any class can register to be notified of changes to the wiki by:
<code>
@wiki.watch_for( :page_created ) { |event, page, revision| do whatever you want }
@wiki.watch_for( :page_revised ) { |event, page, revision| do whatever you want }
@wiki.watch_for( :page_deleted ) { |event, page, revision| do whatever you want }
</code>

These notifications are sent by a separate low priority thread from the one that is interacting with the user.   Using these notifications a class can make changes to the wiki by calling:
<code>
@wiki.revise( pagename, newcontent, author )
</code>

In soks-helpers.rb you will find some classes that make use of this api.  One particular one is the AutomaticSummary class.  This watches for changes to the wiki, and if the page that is changed matches a given regexp, adds it to a summary page.

It has quite a powerful set of settings, defaults are:
<code>
DEFAULT_SETTINGS = {
	 	:regexp_for_title => /.*/, # These three regexps act as an AND
		:regexp_for_author => nil, 
		:regexp_for_content => nil,
		:max_pages_to_show => nil,
		:pagename => 'Summary',
		:author => 'AutomaticSummary',
		:lines_to_include => nil, # If nil then justs puts a link, otherwise includes X number of lines from the page in the summary
		:only_new_pages => false, # Otherwise includes changes
		:sort_pages_by => :created_on, # Could be :revised_on or :score or :name or :name_for_index, or :author
		:reverse_sort => false,
		:include_metadata => false, # If true includes author and time in summary
		:summarise_revisions => false, # If true, then can contain several revisions for same page
		:remove_deleted_pages => true, # If false will keep references to deleted pages
	}
</code>

Two examples of its use, included in the soks-helpers.rb file, are the Site Index and the Recent Changes page:

<code>
AutomaticSummary.new( wiki, {
 	:regexp_for_title => /.*/ # Match all pages
        :pagename => 'Site Index',
	:author => 'Automatic Site Indexer',
	:only_new_pages => true,
	:sort_pages_by => :name_for_index,
} )
</code>

<code>
AutomaticSummary.new( wiki, { 
 	:regexp_for_title => /.*/ # Match all pages
        :pagename => 'Recent Changes',
	:author => 'Automatic Recent Changes',
	:only_new_pages => false,
	:sort_pages_by => :revised_on,
	:include_metadata => true,
	:summarise_revisions => true,
	:reverse_sort => true,
	:remove_deleted_pages => false,
})
</code>

You might also use it to construct a basic blog class:
<code>
AutomaticSummary.new( wiki, {
 	:regexp_for_title => /^Blog:.*/ # Match all pages starting with blog
        :pagename => 'Recent Blog Entries',
	:author => 'Automatic Blog Watcher',
        :max_pages_to_show => 10 # Only show the ten most recent blogs
        :lines_to_include => 20 # Show the first 20 lines of each blog entry
	:only_new_pages =>true,
	:sort_pages_by => :created_on,
	:include_metadata => true,
	:reverse_sort => true,
})
</code>

If you have any other ideas or examples, please add them here