%META:TOPICINFO{author="TWikiContributor" date="1139389084" format="1.1" version="1.1"}%
<!--

   PLEASE DO NOT EDIT THIS TOPIC

   It is automatically generated from the subversion repository, and any changes
   you make will simply be overwritten the next time a release is generated.

   Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author.
-->
---+!! <nop>%TOPIC%
%TOC%

This is the supplemental plugin for the BlogUp <nop>TWikiApplication.
It bundles some of the features found in common blogging applications 
that are very hard or even impossible to implement using <nop>TWikiML. 
Note, that most of the tags are tightly related to the
data model of BlogUp, i.e. it relies on its <nop>TopicType and <nop>TWikiForm 
definitions. 

Shortcut: want to create a blog ... use the BlogFactory.

---++ Syntax Rules

---+++ CITEBLOG
Format a link to another <nop>BlogEntry displaying its headline and date.

*Syntax:*

| *%<nop>CITEBLOG{"&lt;topic>"}%* ||
| ="&lt;topic>"= | name of a <nop>BlogEntry topic, e.g. <nop>BlogEntry0 |

*Example:*

=%<nop>CITEBLOG{"_BlogPlugin.BlogEntry0"}%=

%CITEBLOG{"_BlogPlugin.BlogEntry0"}%


---+++ COUNTCOMMENTS
Count the <nop>BlogComments that refer to a given topic recursively, that is
the number of <nop>BlogComment topics that refer to a given <nop>BlogEntry and 
each <nop>BlogComment referring to the <nop>BlogComment found so far. Reference
is expressed by the <nop>BlogRef formfield in the <nop>BlogCommentForm.

*Syntax:*
| *%<nop>COUNTCOMMENTS{"&lt;topic>" ... }%* ||
| ="&lt;topic>"= \
| name of a <nop>BlogEntry or <nop>BlogComment topic, e.g. <nop>BlogEntry0 |
| =web="..."= \
| web where to search for references; defaults to the \
  web specified as part of the "topic" parameter or the current one |
| =format="..."= \
| format string used to display the count; \
  the variable $count is replaced by the calculated references; \
  defaults to "$count" |
| =single="..."= \
| format string used to display a single hit; \
  defaults to the "format" value (see above) |
| =null="..."= \
| format string used to display a zero hit; defaults to "0" |
| =hidenull="on,off"= \
| if set to "on" nohting is displayed if no references where found; \
  defaults to "off" |
| =offset="..."= \
| add an "offset" to the computed number of hits; so if offset="9" and \
  11 references where found the $count is set to 20 |

Following variables are expanded in format strings:
   * $percnt: % sign
   * $dollar: $ sign
   * $n: newline
   * $t: tab
   * $nop: "empty string"
   * $count: the calculated number of references (plus an optional offset)


---+++ PREVDOC, NEXTDOC
Display the previous/next topic in an ordered set.
These tags can be used to establish a navigation within a set of related topics
paging to the preceding or succeeding one. A set of related topics is defined
using a "where" and an "order" clause which the given topic is supposed to be part of.

*Syntax:*
| *%<nop>PREVDOC{"&lt;topic" where="..." ...}%, %<nop>NEXTDOC{"&lt;topic" where="..." ...}%* ||
| ="&lt;topic>"= | topic which we search the predecessor/successor of |
| =web="..."= | web where to search for related topics; \
  defaults to the web given with the &lt;topic> parameter or the current one |
| =where="..."= \
| search clause, see documentation of the DBCacheContrib |
| =order="..."= \
| document property used to sort the hit set; defaults to "created" |
| =reverse="on,off"= \
| if set to on the sorting will be reversed, that is the logic of PREV and NEXT is inverted |


---+++ RECENTCOMMENTS
Display an ordered list of most recent <nop>BlogComments, grouped by the
referred <nop>BlogEntry.

*Syntax:*
| *%<nop>RECENTCOMMENTS{"&lt;format>" ...}%* ||
| ="&lt;format>"= | format string used to display the hit results; \
  each hit is displayed using the given format |
| =header="..."= | format string to prepended to the list of hits being displayed |
| =footer="..."= | format string to appended to the list of hits being displayed |
| =separator="..."= | format string used to separate hits; \
  defaults top "$n"; the special separator "none" disables separation |
| =limit="..."= | restrict the number of hits being displayed; \
  defaults to "-1" which means unlimited |
| =age="..."= | restrict the age of comments being displayed; \
  values must be given in epoch seconds, e.g. 5184000 being ca. 2 months; \
  defaults to "0" which means unlimited |
| =category="..."= \
| pattern that limits comments to those whose <nop>BlogEntries match the \
  <nop>SubjectCategory; defaults to ".*" |
| =author="..."= \
| pattern that limits comments to those on <nop>BlogEntries from the given author \
  defaults to ".*" |

(Each <nop>BlogEntry that is found given the above search parameters and limits
is called a hit.)

Following variables are expanded in format strings:
   * $percnt: % sign
   * $dollar: $ sign
   * $n: newline
   * $t: tab
   * $nop: "empty string"
   * $count: the number of comments on the given <nop>BlogEntry
   * $topic: the topic name of the referring <nop>BlogEntry, e.g. <nop>BlogEntry0
   * $web: the web where the hit was found
   * $headline: the headline of the referring <nop>BlogEntry 
   * $commenter: a list of links to the comments in the format \
      [<nop>[BlogEntry0#BlogComment1][&lt;author>]],... (author: name of
      commenter)
   * $date: date of the most recent comment on the current hit.

See also the interface <nop>TopicFunction "RenderRecentComments". 

---+++ RELATEDENTRIES
Display a list of <nop>BlogEntries related to a given one. The Relationship
is manually encoded in the data model using the "Related" formfield. The
relation is computed transitively and reflexively ('til a configurable depth).
That is, two <nop>BlogEntries A and B are related if A points to B or vice versa
or A and B are connected by a series of related postings C1,...CN, where A is related 
to C1 and B CN is related to B.

*Syntax:*
| *%<nop>RELATEDENTRIES{"&lt;topic>" ...}%* ||
| ="&lt;topic>"= | topic name of a <nop>BlogEntry related once are search for |
| =web="..."= | web where to search for related topics; \
  defaults to the web given with the &lt;topic> parameter or the current one |
| =format="..."= | format string to display a hit;\
  defaults to "$topic" |
| =header="..."= | format string to prepended to the list of hits |
| =footer="..."= | format string to appended to the list of hits |
| =separator="..."= | format string used to separate hits; \
  defaults to "$n"; the special separator "none" disables separation |
| =depth="..."= | depth of recursion (the number of hops from posting A to posting B); \
  defaults to "2"; |

Note, that large "depth" values will very soon include your complete blog archive.
The hit set also depends on the amount of direct relationships that you add to your
<nop>BlogEntries. So either use a low "depth" value and add more direct relations based on
your own judgment, or just specify one related entry and use a "depth" value of up to
3 for good results.

Following variables are expanded in format strings:
   * $percnt: % sign
   * $dollar: $ sign
   * $n: newline
   * $t: tab
   * $topic: topic name of a hit
   * $web: web name where the hit was found
   * $depth: distance to the given &lt;topic> (depth in which this topic was found)
   * $headline: headline of the related <nop>BlogEntry

The relatedness feature here is a very na&iuml;ve and purely manual one.
We'd like to semi-automate this task using some automatic classificator
on document similarities. Making use of weights following links is an option too to
improve the hit set quality.

Read
   * Wikipedia:Latent_semantic_analysis 
   * [[http://mitpress.mit.edu/catalog/item/default.asp?ttype=2&tid=3391][Foundations of Statistical Natural Language Processing]]
   * [[http://www.perl.com/pub/a/2003/02/19/engine.html][Building a Vector Space Search Engine in Perl]]
   * [[http://search.cpan.org/~mceglows/Search-VectorSpace-0.02/][Search-VectorSpace]]
And send me a patch if you've coded that into TWiki ;).

---++ Plugin Installation Instructions

   * [[http://twiki.org/p/pub/Plugins/%TOPIC%/%TOPIC%.zip][Download]] and install 
     all additionally required plugins listed in the
     [[#Plugin_Info][dependencies information]] below
   * Download the BlogPlugin ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | plugin topic |
     | ==data/_BlogPlugin/*.txt== | blog template web |
     | ==data/Main/BlogAdminGroup.txt== | blog admin group |
     | ==data/Main/BlogAuthorGroup.txt== | blog author group |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | plugin perl module |
     | ==lib/TWiki/Plugins/%TOPIC%/Core.pm== | plugin core module |
     | ==lib/TWiki/Plugins/%TOPIC%/Factory.pm== | rest interface for the <nop>BlogFactory |
     | ==lib/TWiki/Plugins/%TOPIC%/WebDB.pm== | <nop>WebDB implementation for the <nop>DBCachePlugin |
   * Open the TWiki [[%SCRIPTURL{"configure"}%][configuration]] dialog,
     enable the plugin and change the <nop>PluginsOrder to 
     _<nop>GluePlugin, <nop>SpreadSheetPlugin, <nop>IfDefinedPlugin, <nop>AliasPlugin_
   * Create a new Blog web using the _BlogPlugin template web
   * Edit the Main.BlogAdminGroup and the Main.BlogAuthorGroup to match your needs.
   * Optionally, run ==%TOPIC%_installer.pl== to automatically check and
     install other TWiki modules that this module depends on. You can also do
     this step manually.
   * Alternatively, manually make sure the dependencies listed in the table
     below are resolved.
     <table border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">TWiki::Plugins</td><td align="left">&gt;=1.1</td><td align="left">TWiki Dakar release.</td></tr><tr><td align="left">TWiki::Plugins::AliasPlugin</td><td align="left">&gt;=1.2</td><td align="left">Required; download from TWiki:Plugins/AliasPlugin </td></tr><tr><td align="left">TWiki::Plugins::DBCachePlugin</td><td align="left">&gt;=1.20</td><td align="left">Required; download from TWiki:Plugins/DBCachePlugin </td></tr><tr><td align="left">TWiki::Plugins::ExtendedSelectPlugin</td><td align="left">&gt;=1.10</td><td align="left">Required; download from TWiki:Plugins/ExtendedSelectPlugin </td></tr><tr><td align="left">TWiki::Plugins::FilterPlugin</td><td align="left">&gt;=0.94</td><td align="left">Required; download from TWiki:Plugins/FilterPlugin </td></tr><tr><td align="left">TWiki::Plugins::GluePlugin</td><td align="left">&gt;=1.5</td><td align="left">Required; download from TWiki:Plugins/GluePlugin </td></tr><tr><td align="left">TWiki::Plugins::HeadlinesPlugin</td><td align="left">&gt;=1.91</td><td align="left">Required; download from TWiki:Plugins/HeadlinesPlugin </td></tr><tr><td align="left">TWiki::Plugins::IfDefinedPlugin</td><td align="left">&gt;0.93</td><td align="left">Required; download from TWiki:Plugins/IfDefinedPlugin </td></tr><tr><td align="left">TWiki::Plugins::RedDotPlugin</td><td align="left">&gt;=1.35</td><td align="left">Required; download from TWiki:Plugins/RedDotPlugin </td></tr><tr><td align="left">TWiki::Plugins::SpreadSheetPlugin</td><td align="left">&gt;=1.001</td><td align="left">Required; download from TWiki:Plugins/SpreadSheetPlugin </td></tr><tr><td align="left">TWiki::Plugins::TagCloudPlugin</td><td align="left">&gt;=0.20</td><td align="left">Required; download from TWiki:Plugins/TagCloudPlugin </td></tr><tr><td align="left">TWiki::Plugins::TimeSincePlugin</td><td align="left">&gt;=0.99</td><td align="left">Required; download from TWiki:Plugins/TimeSincePlugin </td></tr><tr><td align="left">TWiki::Plugins::TwistyPlugin</td><td align="left"></td><td align="left">Required; download from TWiki:Plugins/TwistyPlugin </td></tr><tr><td align="left">TWiki::Plugins::UserInfoPlugin</td><td align="left">&gt;=1.5</td><td align="left">Optional; download from TWiki:Plugins/UserInfoPlugin </td></tr><tr><td align="left">TWiki::Plugins::NatSkin</td><td align="left">&gt;=2.9998</td><td align="left">Recommended; download from TWiki:Plugins/NatSkin </td></tr><tr><td align="left">TWiki::Plugins::ImagePlugin</td><td align="left">&gt;=0.3</td><td align="left">Recommended; download from TWiki:Plugins/ImagePlugin </td></tr></table>

---++ Plugin Info
<!-- provided for compatibility only
   * Set SHORTDESCRIPTION = Basic blogging features used to implement the BlogUp <nop>TWikiApplication
-->
|  Plugin Author: | TWiki:Main.MichaelDaum |
|  Copyright &copy;: | 2006, MichaelDaum@WikiRing.com |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Version: | v0.99 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  31 Aug 2006: | added NO_PREFS_IN_TOPIC;\
                  added TWiki:Plugins/ImagePlugin support; \
		  fixed <nop>BlogArchive not to compute terms _before_ calling the tagcloud; \
		  removed whitespaces from <nop>WebPreferences to prevent insecure eval warnings (strange); \
		  fixed use of <nop>NatSkin's IFSKINSTATE as it glues no more |
|  21 Aug 2006: | fixed error in RECENTCOMMENTS checking the posting's status; \
                  some css fixes; \
                  added default meta data keywords |
|  15 Aug 2006: | making use of new feature of the <nop>IfDefinedPlugin to speed up certain things; \
                  improved way to render meta data and pagetitle; \
		  generating relative urls instead of absolute where possible now |
|  28 Jul 2006: | hiding the breadcrumbs in the blog introduced in the recent <nop>NatSkin version; \
                  reordered sidebar section to "make more sense"; \
		  minor docu changes; \
		  added recommendation to use the <nop>BlogPlugin in combination with the \
		  TWiki:Plugins/NatSkin because some features will work with it only |
|  23 Jul 2006: | added view templates specific to <nop>PatternSkin; \
                  improved the blog's sidebar for <nop>PatternSkin; \
		  added standard <nop>WebSearch topics; \
		  improved <nop>PatternSkin css support; \
		  fixed rendering postings without a <nop>SubjectCategory; \
		  usability improvements in <nop>RenderAddComment; \
                  fighting back sprinkling &lt;p />; \
		  small improvements to the <nop>BlogFactory; \
		  *Upgrade warning*: blogentries created with older versions of this plugin \
		  need to be editted to replace %BR%\
		  =%META:FIELD{name="State" ... value="enabled"}%= \
		  with %BR% \
		  =%META:FIELD{name="State" ... value="published"}%=; %BR%\
		  replace =disabled= with =unpublised= respectively |
|  15 June 2006: | added <nop>BlogFactory to ease creation of blogs; \
                   fixed <nop>BlogImages feature introduced recently; \
		   added docu to to blog's <nop>WebPreferences; \
		   moved some hard-coded values to <nop>WebPreferences so that they can be set\
		   by the <nop>BlogFactory |
|  09 June 2006: | added last.fm support to display the 10 most recent tracks you listened to in the sidebar; \
                  simplified uploading/managing images using a new "Upload Image" button; \
		  cleaned up technorati sidebar functionality;\
		  minor fixes in the blog archive; \
		  added ENABLEPINGBACK to blog postings so that they can receive pings once that plugin is ready;\
		  added TAG parameter to <nop>TopicFunctions that extract blog entries; \
		  fixed error in <nop>RenderGoogleAdsense; \
		  displaying recent visitors within the last week (was today's visitors only) ;\
                  added a customized "page not found"; \
		  added support to render your blog's license in the sidebar, defaults to a \
		  creative common license for wiki |
|  24 May 2006: | added <nop>BlogImages: centralize all image resources; \
                  added affiliations to the sidebar; \
		  cleaned up code to detect multi-authored blog; \
		  cleaned up forms with singleton formfields ;\
		  removed all mandatory flags from formfields that are not auto-filled; \
		  improved rss and atom feeds to generate better titles for comments; \
		  added TAGCLOUDFADE to <nop>WebPreferences to make the archive's tagcloud customizable \
		  (was hardcoded before); \
		  fixed issue with rss feed icon in sidebar; \
		  added notion to register first before replying; \
		  added GOOGLE_*COLOR preference values to <nop>WebPreferences to make \
		  adsens customizable; \
		  added accesskeys 1-5 for the <nop>WebButtons; \
		  multiple css issues, more classes; \
		  fixed rss feed validation error due to symbolic html chars instead of numeric \
		  (hellip = #8230 etc) |
|  05 May 2006: | added views for all models: \
                  all <nop>BlogenTries, <nop>SubjectCategories etc only set a specific <nop>TopicView; \
		  this reduces redundancy, hides implementation and fixes a pagination error using URLPARAM in \
		  <nop>TopicTemplates, e.g. <nop>SubjectCategories pages couldn't be run over; \
                  separated BlogUp ring from blogroll using new NOCAT parameter of <nop>RenderBlogRoll; \
		  added <nop>TopicViews twisty to <nop>AdminTools;\
		  page through <nop>BlogLinks of the same category |
|  30 Mar 2006: | moved the createdate field in the <nop>WebDB into the <nop>DBCachePlugin; \
                  overriding it using a Date formfield if there is one;\
		  this means you need <nop>DBCachePlugin > 1.2;\
		  added <nop>RenderGoogleAdsense; \
		  fixed inconsequent parameter naming of categories (was sometimes NAME sometimes CAT)\
		  NOTE: you will need to correct preexisting <nop>SubjectCategory topics by hand if you upgrade\
		  (sorry again);\
		  fixed html in <nop>RenderBlogComments; |
|  27 Mar 2006: | fixed rendering of scroll helpers; \
                  using template comments instead of templateonly sections in <nop>TopicViews; \
		  initialize email fields of comment with USERINFO |
|  12 Mar 2006: | better separation of multiple authors: each <nop>BlogAuthor page \
                  renders a dedicated About info now taken from the new <nop>BlogAuthorForm; \
		  the sidebar renders the items that belong to the author only using \
		  the new Author section in <nop>RenderSideBar; \
		  unpublished postings are listed per author only; \
		  added <nop>RenderAuthors to the sidebar - disabled on a single-author blog;\
		  added <nop>BlogAuthor to <nop>BlogLinks so that every author can have \
		  his own sidebar as well as share parts with other authors; \
		  added AUTHOR to a couple of <nop>TopicTunctions to make them author-aware; \
		  added HOME parameter to <nop>RenderBlogEntriesOfAuthor link to a \
		  different topic than the default <nop>Main.AuthorName one; \
                  added author argument to RECENTCOMMENTS |
|  11 Mar 2006: | css fixes to catch up with the recent changes to the PatternSkin; \
                  replaced css based way to hide topic forms with VIEW_TEMPLATEs; \
		  added comments field to <nop>SubjectCategories; \
		  replaced CALF{IF(EXACT())} with new IFDEFINED{"" as=""}; \
		  hide postings for guests if they are not published yet; \
		  browsing postings coming from a <nop>SubjectCategory frontpage will \
		  propagate down the category so that pagination will be restricted to \
		  that category only; added mechanisms to propagate urlparams; \
		  componentized the <nop>BlogArchive: no need for CALC variables anymore; \
		  listing unpublished/unfinished postings in the sidebar for authors; \
		  packaging using the <nop>BuildContrib; \
		  CAUTION on upgrade: you need to add "Set VIEW_TEMPLATE = <nop>HiddenViewTemplate \
		  in your previous postings, links and categories (sorry) |
|  03 Mar 2006: | added easy way to add/remove tags in the <nop>BlogEntryForm; \
                  tags are displayed using a mini-tag cloud on the blog entry pages to \
		  sort them by weight and name (btw. you can weight each tag like =mytag:2=) |
|  01 Mar 2006: | grand rework of the <nop>BlogArchive; \
                  added <nop>BlogTags for <nop>BlogEntries; \
                  added dependency on TWiki:Plugins/TagCloudPlugin; \
		  added rel="tag" to links to tags and categories to make technorati happy; \
		  reworked category and archive in sidebar using the new DBSTATS tag of the \
		  recent <nop>DBCachePlugin resulting in a drastic speed improvement on the front pages; \
                  removed unused <nop>TopicFunctions |
|  22 Feb 2006: | tighter control of alias substitution; \
                  removed % in <nop>RenderBlogEntryButton; |
|  21 Feb 2006: | removed dependency on the <nop>NatSkin; \
                  added dependency on the <nop>IfDefinedPlugin; \
		  added PatternSkin specific styles for the blog web; \
		  lots of minor <nop>TopicFunction tweaks |
|  14 Feb 2006: | added and diverse rss and atom feeds; \
		  added comment syndication per blog entry; \
		  added <nop>TopicTypes <nop>BlogPage and <nop>TWikiTopic; \
		  added descriptive tooltips to all links; \
                  added =reverse= argument to PREVDOC, NEXTDOC; \
	          added =header=, =footer= arguments to COUNTCOMMENTS; \
		  renamed RELATEDENTRIES to RELATEDTOPICS to handle <nop>BlogPages \
		  with it too; \
		  added a =filter= argument to RELATEDTOPICS for more flexibility; \
                  preliminary <nop>BlogUp documentation and screenshots; \
		  reworked sidebar generation by removing <nop>BlogSideBar and adding; \
		  a proper <nop>RenderSideBar <nop>TopicFunction for it; \
		  added <nop>WebButtons to navigate inside the blog application;\
		  added nice rss feed icons everywhere; \
		  added scroll helper to blog entries (need more); \
		  moved most of the descriptive text in <nop>BlogAbout into a \
		  <nop>BlogHelpText and reuse the <nop>BlogAbout for a free-form \
		  "About" page that is added to the <nop>WebButtons; \
		  speed improvements rendering the front page by simplifying the \
		  navigation renderer; \
		  added a dedicated <nop>TopicFunction to render http-equivs, \
		  i.e. to list the feeds; \
		  added w3c validation button to the <nop>TWikiWorkbench; \
		  added example <nop>WebAggregation by rendering own feeds using \
		  the HeadlinesPlugin; \
		  added dependency to TWiki:Plugins/FilterPlugin for the FORMATLIST tag; \
		  unified redundant navigation renderer; \
		  improved admin tools using twisties; \
		  postings are owned by the author by default now; \
                  fixed print view to popup the print dialogue |
|  30 Jan 2006: | replaced NOPs with STARSECTIONs; \
                  fixed customized search view |
|  27 Jan 2006: | added permalink tooltips ;\
                  nicer autor and admin buttons; \
		  renamed SECTIONs to STARTSECTIONs; \
		  highlight current <nop>TopicFunction in sidebar list; \
		  added button to easily w3c validate a <nop>TopicFunction; \
		  lots of w3c fixes, mostly superfluous &lt;p>s in the wrong place; \
		  css improvements |
|  24 Jan 2006: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  Perl Version: | 5.8 |
|  [[TWiki:Plugins/Benchmark][Benchmarks]]: | %TWIKIWEB%.GoodStyle nn%, %TWIKIWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |
|  Appraisal: | TWiki:Plugins/%TOPIC%Appraisal |

-- TWiki:Main.MichaelDaum - 31 Aug 2006
