FEATURE: added automatic notifications about accessing outdated or unreleased versions. (Fixes #6320)

code/DocumentationService.php

@@ -212,7 +212,7 @@ class DocumentationService {
 		}
 		
 		if($latest)
-			$output->setLatestVersion($version);
+			$output->setStableVersion($version);
 		
 		return $output;
 	}

code/controllers/DocumentationViewer.php

@@ -180,7 +180,7 @@ class DocumentationViewer extends Controller {
 		$entity = DocumentationService::is_registered_entity($this->entity, null, $this->getLang());
 
 		if($entity) {
-			$current = $entity->getLatestVersion();
+			$current = $entity->getStableVersion();
 			$version = $this->getVersion();
 			
 			if(!$version) {
@@ -254,7 +254,7 @@ class DocumentationViewer extends Controller {
 		if($this->version) return $this->version;
 		
 		if($entity = $this->getEntity()) {
-			$this->version = $entity->getLatestVersion();
+			$this->version = $entity->getStableVersion();
 			
 			return $this->version;
 		} 
@@ -316,7 +316,8 @@ class DocumentationViewer extends Controller {
 				$output->push(new ArrayData(array(
 					'Title' => $version,
 					'Link' => $this->Link(implode('/',$this->Remaining), $entity->getFolder(), $version),
-					'LinkingMode' => $linkingMode
+					'LinkingMode' => $linkingMode,
+					'Version' => $version // separate from title, we may want to make title nicer.
 				)));
 			}
 		}
@@ -778,4 +779,40 @@ class DocumentationViewer extends Controller {
 		
 		return $search->renderResults();
 	}
+	
+	/**
+	 * Check to see if the currently accessed version is out of date or
+	 * perhaps a future version rather than the stable edition
+	 *
+	 * @return false|ArrayData
+	 */
+	function VersionWarning() {
+		$version = $this->getVersion();
+		$entity = $this->getEntity();
+		
+		if($entity) {
+			$compare = $entity->compare($version);
+			$stable = $entity->getStableVersion();
+
+			// same
+			if($version == $stable) return false;
+			
+			// check for trunk, if trunk and not the same then it's future
+			// also run through compare
+			if($version == "trunk" || $compare > 0) {
+				return $this->customise(new ArrayData(array(
+					'FutureRelease' => true,
+					'StableVersion' => DBField::create('HTMLText', $stable)
+				)));				
+			}
+			else {
+				return $this->customise(new ArrayData(array(
+					'OutdatedRelease' => true,
+					'StableVersion' => DBField::create('HTMLText', $stable)
+				)));
+			}
+		}
+		
+		return false;
+	}
 }

code/models/DocumentationEntity.php

@@ -7,11 +7,13 @@
  * page. Individual pages are handled by {@link DocumentationPage}
  *
  * Each folder must have at least one language subfolder, which is automatically
- * determined through {@link addVersion()} and should not be included in the $path argument.
+ * determined through {@link addVersion()} and should not be included in the 
+ * $path argument.
  * 
  * Versions are assumed to be in numeric format (e.g. '2.4'),
  *
- * They're also parsed through version_compare() in {@link getLatestVersion()} which assumes a certain format. 
+ * They're also parsed through version_compare() in {@link getStableVersion()} 
+ * which assumes a certain format {@link http://php.net/manual/en/function.version-compare.php}
  *
  * @package sapphiredocs
  * @subpackage models
@@ -19,6 +21,9 @@
 
 class DocumentationEntity extends ViewableData {
 	
+	/**
+	 * @var array
+	 */
 	static $casting = array(
 		'Name' => 'Text'
 	);
@@ -41,7 +46,7 @@ class DocumentationEntity extends ViewableData {
 	/**
 	 * @var array
 	 */
-	private $latestVersion;
+	private $stableVersion;
 	
 	/**
 	 * @var Array $langs a list of available langauges
@@ -123,13 +128,13 @@ class DocumentationEntity extends ViewableData {
 	}
 	
 	/**
-	 * @return String|Boolean
+	 * @return string|boo
 	 */
-	public function getLatestVersion() {
+	public function getStableVersion() {
 		if(!$this->hasVersions()) return false;
 		
-		if($this->latestVersion) {
+		if($this->stableVersion) {
-			return $this->latestVersion;
+			return $this->stableVersion;
 		} else {
 			$sortedVersions = $this->getVersions();
 			usort($sortedVersions, create_function('$a,$b', 'return version_compare($a,$b);'));
@@ -141,9 +146,23 @@ class DocumentationEntity extends ViewableData {
 	/**
 	 * @param String $version
 	 */
-	public function setLatestVersion($version) {
+	public function setStableVersion($version) {
 		if(!$this->hasVersion($version)) throw new InvalidArgumentException(sprintf('Version "%s" does not exist', $version));
-		$this->latestVersion = $version;
+		$this->stableVersion = $version;
+	}
+	
+	/**
+	 * Returns an integer value based on if a given version is the latest 
+	 * version. Will return -1 for if the version is older, 0 if versions are 
+	 * the same and 1 if the version is greater than.
+	 *
+	 * @param string $version
+	 * @return int
+	 */
+	public function compare($version) {
+		$latest = $this->getStableVersion();
+		
+		return version_compare($version, $latest);
 	}
 	
 	/**
@@ -207,7 +226,7 @@ class DocumentationEntity extends ViewableData {
 	 * @return string
 	 */
 	public function getPath($version = false, $lang = false) {
-		if(!$version) $version = $this->getLatestVersion();
+		if(!$version) $version = $this->getStableVersion();
 		if(!$lang) $lang = 'en';
 		
 		if($this->hasVersion($version)) {
@@ -235,7 +254,7 @@ class DocumentationEntity extends ViewableData {
 	
 	function getRelativeLink($version = false, $lang = false) {
 		if(!$lang) $lang = 'en';
-		if($version == $this->getLatestVersion()) $version = false;
+		if($version == $this->getStableVersion()) $version = false;
 		
 		return Controller::join_links(
 			DocumentationViewer::get_link_base(), 

code/models/DocumentationPage.php

@@ -176,7 +176,7 @@ class DocumentationPage extends ViewableData {
 	}
 	
 	function getVersion() {
-		return $this->version ? $this->version : $this->entity->getLatestVersion();
+		return $this->version ? $this->version : $this->entity->getStableVersion();
 	}
 	
 	function setVersion($version) {

templates/Includes/DocumentationVersion_warning.ss

@@ -0,0 +1,13 @@
+<div class="warningBox" id="outdated-release">
+	<div class="warningBoxTop">
+		<% control VersionWarning %>
+			<% if OutdatedRelease %>
+				<p>This document contains information for an <strong>outdated</strong> version <% if Top.Version %>(<strong>$Top.Version</strong>)<% end_if %> and may not be maintained any more.</p>
+				<p>If some of your projects still use this version, consider upgrading as soon as possible.</p>
+			<% else_if FutureRelease %>
+				<p>This document contains information about a <strong>future</strong> release <% if StableVersion %>and not the current stable version (<strong>$StableVersion</strong>)<% end_if %>.</p>
+				<p>Be aware that information on this page may change and API's may not be stable for production use.</p>
+			<% end_if %>
+		<% end_control %>
+	</div>
+</div>

templates/Layout/DocumentationViewer.ss

@@ -1,3 +1,7 @@
+<% if VersionWarning %>
+	<% include DocumentationVersion_warning %>
+<% end_if %>
+
 <div id="documentation-page">
 	<div id="left-column">
 		$Content

templates/Layout/DocumentationViewer_folder.ss

@@ -1,3 +1,7 @@
+<% if VersionWarning %>
+	<% include DocumentationVersion_warning %>
+<% end_if %>
+
 <div id="module-home">
 	<div id="left-column">
 		<% if Content %>

tests/DocumentationEntityTest.php

@@ -19,15 +19,15 @@ class DocumentationEntityTest extends SapphireTest {
 		$this->assertFalse($entity->hasLanguage('fr'));
 	}
 	
-	function testgetLatestVersion() {
+	function testgetStableVersion() {
 		$entity = new DocumentationEntity('docs', '1.0', '../sapphiredocs/tests/docs/', 'My Test');
 		$entity->addVersion('1.1', '../sapphiredocs/tests/docs-v2.4/');
 		$entity->addVersion('0.0', '../sapphiredocs/tests/docs-v3.0/');
-		$this->assertEquals('1.1', $entity->getLatestVersion(), 'Automatic version sorting');
+		$this->assertEquals('1.1', $entity->getStableVersion(), 'Automatic version sorting');
 		
 		$entity = new DocumentationEntity('docs', '1.0', '../sapphiredocs/tests/docs/', 'My Test');
 		$entity->addVersion('1.1.', '../sapphiredocs/tests/docs-v2.4/');
-		$entity->setLatestVersion('1.0');
+		$entity->setStableVersion('1.0');
-		$this->assertEquals('1.0', $entity->getLatestVersion(), 'Manual setting');
+		$this->assertEquals('1.0', $entity->getStableVersion(), 'Manual setting');
 	}
 }

tests/DocumentationPageTest.php

@@ -34,7 +34,7 @@ class DocumentationPageTest extends SapphireTest {
 		// test with version.
 		$entity = DocumentationService::register("versionlinks", BASE_PATH . "/sapphiredocs/tests/docs-v2.4/", '1');
 		$entity->addVersion('2', BASE_PATH . "/sapphiredocs/tests/docs-v3.0/");
-		$entity->setLatestVersion('2');
+		$entity->setStableVersion('2');
 		
 		$page = new DocumentationPage();
 		$page->setRelativePath('test.md');

tests/DocumentationViewerTest.php

@@ -250,4 +250,26 @@ class DocumentationViewerTest extends FunctionalTest {
 			$this->assertStringEndsWith($expected, $page->Link);
 		}
 	}
+	
+	function testVersionWarning() {
+		$v = new DocumentationViewer();
+		
+		// the current version is set to 2.4, no notice should be shown on that page
+		$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/2.4'));
+		$this->assertFalse($v->VersionWarning());
+		
+		// 2.3 is an older release, hitting that should return us an outdated flag
+		$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/2.3'));
+		$warn = $v->VersionWarning();
+		
+		$this->assertTrue($warn->OutdatedRelease);
+		$this->assertNull($warn->FutureRelease);
+		
+		// 3.0 is a future release
+		$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/3.0'));
+		$warn = $v->VersionWarning();
+		
+		$this->assertNull($warn->OutdatedRelease);
+		$this->assertTrue($warn->FutureRelease);
+	}
 }