Browse files

FEATURE: added automatic notifications about accessing outdated or un…

…released versions. (Fixes #6320)
  • Loading branch information...
1 parent 96ac20a commit 959cb165349007eba54732f4f05b4c323890c9e3 @wilr wilr committed Jul 8, 2011
View
2 code/DocumentationService.php
@@ -212,7 +212,7 @@ public static function register($entity, $path, $version = '', $title = false, $
}
if($latest)
- $output->setLatestVersion($version);
+ $output->setStableVersion($version);
return $output;
}
View
43 code/controllers/DocumentationViewer.php
@@ -180,7 +180,7 @@ public function handleRequest(SS_HTTPRequest $request) {
$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 @@ function getVersion() {
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 @@ function getVersions($entity = false) {
$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 @@ function results($data, $form = false) {
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;
+ }
}
View
41 code/models/DocumentationEntity.php
@@ -7,18 +7,23 @@
* 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
*/
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 @@ public function getVersions() {
}
/**
- * @return String|Boolean
+ * @return string|boo
*/
- public function getLatestVersion() {
+ public function getStableVersion() {
if(!$this->hasVersions()) return false;
- if($this->latestVersion) {
- return $this->latestVersion;
+ if($this->stableVersion) {
+ return $this->stableVersion;
} else {
$sortedVersions = $this->getVersions();
usort($sortedVersions, create_function('$a,$b', 'return version_compare($a,$b);'));
@@ -141,9 +146,23 @@ public function getLatestVersion() {
/**
* @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 @@ public function removeVersion($version = '') {
* @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 @@ public function Link($version = false, $lang = false) {
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(),
View
2 code/models/DocumentationPage.php
@@ -176,7 +176,7 @@ function setLang($lang) {
}
function getVersion() {
- return $this->version ? $this->version : $this->entity->getLatestVersion();
+ return $this->version ? $this->version : $this->entity->getStableVersion();
}
function setVersion($version) {
View
13 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>
View
4 templates/Layout/DocumentationViewer.ss
@@ -1,3 +1,7 @@
+<% if VersionWarning %>
+ <% include DocumentationVersion_warning %>
+<% end_if %>
+
<div id="documentation-page">
<div id="left-column">
$Content
View
4 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 %>
View
8 tests/DocumentationEntityTest.php
@@ -19,15 +19,15 @@ function testDocumentationEntityAccessing() {
$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');
- $this->assertEquals('1.0', $entity->getLatestVersion(), 'Manual setting');
+ $entity->setStableVersion('1.0');
+ $this->assertEquals('1.0', $entity->getStableVersion(), 'Manual setting');
}
}
View
2 tests/DocumentationPageTest.php
@@ -34,7 +34,7 @@ function testGetLink() {
// 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');
View
22 tests/DocumentationViewerTest.php
@@ -250,4 +250,26 @@ function testGetEntities() {
$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);
+ }
}

0 comments on commit 959cb16

Please sign in to comment.