tonyair/silverstripe-docsviewer
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-docsviewer synced 2024-10-22 11:05:56 +02:00
Code Issues Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Will Rossiter 2011-07-08 14:42:52 +12:00
parent 96ac20a15c
commit 959cb16534
10 changed files with 120 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
code/DocumentationService.php
View File

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

43
code/controllers/DocumentationViewer.php
View File

@ -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;
}
}

41
code/models/DocumentationEntity.php
View File

@ -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) {
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 @@ 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(),

2
code/models/DocumentationPage.php
View File

@ -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) {

13
templates/Includes/DocumentationVersion_warning.ss Normal file
View File

@ -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>

4
templates/Layout/DocumentationViewer.ss
View File

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

4
templates/Layout/DocumentationViewer_folder.ss
View File

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

8
tests/DocumentationEntityTest.php
View File

@ -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');
$this->assertEquals('1.0', $entity->getLatestVersion(), 'Manual setting');
$entity->setStableVersion('1.0');
$this->assertEquals('1.0', $entity->getStableVersion(), 'Manual setting');
}
}

2
tests/DocumentationPageTest.php
View File

@ -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');

22
tests/DocumentationViewerTest.php
View File

@ -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);
}
}