Recent Changes - Search:
BlogIt /

DeveloperDocs

« Return to BlogIt

Developer Docs

This documentation refers to version 0.0.2, an older version of BlogIt, so may not totally reflect the code from the current version.

Principles

  • Ability to change layout without changing content.
  • Provide basic blog features out-of-the-box (blog entry, blog management, comments, comment management).
  • Encourage use of existing cookbooks to extend blog features; minimize duplication with other cookbooks.
  • Ease of use for: author, skin developer, developer.

Overview

  • Each blog entry is stored as a single PmWiki page.
  • Use PmForms as basis for entering blog entries, storing entry elements as PTVs.
  • Rather than having many separate wiki pages with all the elements required, use a single file BlogIt-CoreTemplate. A new markup includesection is used to allow specific sections of CoreTemplate to be used. The is used widely through out BlogIt.
  • Since blog entry pages only contain PTV variables, they would normally appear to be empty when browsing. Thus, when action=browse, pages with pagetype of 'blog' have the GroupHeaderFmt set to include #single-entry, simulating a normal browse.
  • Skin support is provided by allowing skins to override specific sections found within CoreTemplate. That lets skins move blog elements around (like comment counts, author, edit links, etc).
  • The primary processing is performed in the section commented "Main Processing". Here we provide some setup before PmForms kicks in after a POST event (when a new blog entry is saved for example).

Blog Entries

Blog Entry Browsing

  • In order to allow authors use of (:...:...:) markup within the blog entry, the PTVs entrybody, entrytitle, and entrytags are stored in an added PageTextVarPatterns (::...:...::). Performed using ROSPatterns on post of PmForm.
  • Include SkinTempate#single-entry-view
  • Blog entry PTVs:
    • Entry Type (entrytype): A hidden PTV used to indicate the page is a blog entry. This list ($bi_PageType) can be extended allowing additional page types to be defined. This feature might be used to select alternate display templates, and possibly alternate features.
    • BlogID (blogid): Defaults to 'blog1', a hidden form field. Admins can optionaly set to a list of blogs ($bi_BlogList), in which case blogitMH_select shows a select list for authors to choose.
    • Entry URL (entryurl): The name of the PmWiki page storing the blog entry. Allows the pagename (url) to be different to the Title. This field is not stored in the blog page, and is only used for user entry. If blank (or simply a Group), the Url will be inherited from title, and will include the group from Url or the default group.
    • Status (entrystatus): Draft or Publish, a simple way to differentiate works-in-progess ($bi_StatusType).
    • Comments (entrycomments): Determines how comments are used on this blog entry: Open (read and post), Read Only, or None. Comments can be enabled/disabled globally with $bi_CommentsEnabled.
    • Tags (entrytags): Stored in format, with markup expression 'bi_StripTags' applied to display in simple comma separated format. Category tags are automatically collected from the blog entry body, and combined with those entered here by the author (refer saveTags()).
    • Date (entrydate): Stored as a Unix timestamp, displayed to the user in $bi_DateDisplayFormat. Used in entry forms with the $bi_DateEntryFormat. CURRENTLY validation is not performed.
    • Title (entrytitle): Title of the entry. Stored as PmWiki markup (:title: ...:)@], but displayed to the user with markup stripped. Markup is stripped using a markup expression 'bi_StripMarkup' from SkinTemplate#blog-form. If title is blank it is derived from url.
    • Entry Body (entrybody): Uses (::...:...::) format to allow use of PmWiki markup (:...:...:). This *must* be the last field in the list: this field can contain arbitary (:...:) markup; the only way to determine the terminating :) for entrybody is to search from the end of file; otherwise we end up grabbing other markup terminators.

Blog Entry Editing

  • If action==blogitedit, then display page with PmForm, and convert entrytime from Unix to EntryDateFormat.

Blog Entry PmForms

  • Do not set markup definition for (::...:...::). If we do then embedded (:...:) tags are not processed.
  • Define ROS patterns to change (:...:...:) into (::...:...::) for entrybody and entrytags. Note, entrybody searches for the ::) at the end of file since there's no way to know whether we have ending :) or end of markup :).
  • saveTags: Combine all entrybody category markup "", with comma separated entrytags "tag1, tag2" into a single category list. Storing PmWiki category links means backlinks work.
  • Perform pre-PmForm processing on fields:
    • Convert dates to Unix timestamps.
    • Convert entrytitle to (:title ...:).
    • If no entryurl entered, then default to entrytitle.

Comments

  • Each comment is stored as a separate page, stored in $bi_CommentGroup group. Each page is named based on the originating blog name, and a date/time stamp: {$Group}-{$Name}-' .date('Ymd\THms')
  • Use PmForms as basis for entering blog entries, storing entry elements as PTVs.
  • Form fields are used to store Name, Website, Email, Comment.
  • Comments are not displayed to non Admin users unless then have been approved by an Admin.
  • A PmForm field is used to store Approval Status (commentstatus). Field is set to 'false' in blogit.php to prevent spoofing of hidden field.
  • An Approval link is shown on unapproved comments (for CondAuth Admin). Link has action=blogitapprove, handled by blogit_ApproveComment(). Sets PTV commentapproved='true'.
  • An Edit link is shown (for CondAuth Admin). When the Admin Saves the comment, they are automatically redirected to the originating blog entry. This is done by performing a Redirect whenever a Admin is browsing in the commment group (ie, after Save).

Comment Entry PmForms

  • Remove the Edit password to allow anonymous comment posting.
  • Set commentapproved='false' in blogit.php for all new comments -- prevent spoofing of hidden status field.
  • Basic validation is done on the email address.
  • Input is stripped of markup.

BlogIt-CoreTemplate

The mother of all templates...

Skins

  • Skin support is provided by allowing skins to override specific sections found within CoreTemplate.

Categories and Tags

  • Use standard PmWiki categories.
  • Sets $AutoCreate['/^' .$bi_CategoryGroup .'\./'] = array('ctime' => $Now);

Searching

  • Use SearchPatterns in order to restrict searches to blog entries: 
$SearchPatterns['blogit'][] = '!\.(All)?Recent(Changes|Uploads|Comments)$!';
$SearchPatterns['blogit'][] = '!\.Group(Print)?(Header|Footer|Attributes)$!';
$SearchPatterns['blogit'][] = '!^('. $SiteGroup .'|' .$SiteAdminGroup .'|PmWiki)\.!';
$SearchPatterns['blogit'][] = FmtPageName('!^$FullName$!', $pagename);

Security

  • Expectation is that the wiki is locked down for Editing.
  • Actions 'source' and 'diff' are restricted to Edit users, to prevent viewing of PTV variables, like commentemail.
  • Edit password is temporarily removed for the current action/session when posting a comment, to allow commenting without having to login.