Class yii\apidoc\templates\bootstrap\GuideRenderer

All Classes | Properties | Methods | Constants

Inheritance	yii\apidoc\templates\bootstrap\GuideRenderer » yii\apidoc\templates\html\GuideRenderer » yii\apidoc\renderers\GuideRenderer » yii\apidoc\renderers\BaseRenderer » yii\base\Component
Uses Traits	yii\apidoc\templates\bootstrap\RendererTrait
Available since extension's version	2.0
Source Code	https://github.com/yiisoft/yii2-apidoc/blob/master/templates/bootstrap/GuideRenderer.php

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
$apiContext	yii\apidoc\models\Context	The yii\apidoc\models\Context currently being rendered.	yii\apidoc\renderers\BaseRenderer
$apiUrl			yii\apidoc\renderers\BaseRenderer
$controller	\yii\console\Controller	The apidoc controller instance.	yii\apidoc\renderers\BaseRenderer
$extensions	array	Official Yii extensions	yii\apidoc\templates\bootstrap\RendererTrait
$guidePrefix			yii\apidoc\renderers\BaseRenderer
$guideUrl			yii\apidoc\renderers\BaseRenderer
$layout			yii\apidoc\templates\bootstrap\GuideRenderer
$pageTitle	string	String to use as the title of the generated page.	yii\apidoc\renderers\BaseRenderer
$view	\yii\web\View	The view instance.	yii\apidoc\templates\html\GuideRenderer

Public Methods

Hide inherited methods

Method	Description	Defined By
createSubjectLink()	Creates a link to a subject	yii\apidoc\renderers\BaseRenderer
createTypeLink()	Creates a link to a type (class, interface or trait)	yii\apidoc\renderers\BaseRenderer
generateApiUrl()	Generate an url to a type in apidocs	yii\apidoc\templates\html\GuideRenderer
generateGuideUrl()	Generate an url to a guide page	yii\apidoc\renderers\BaseRenderer
getGuideReferences()		yii\apidoc\templates\html\GuideRenderer
getNavTypes()	Returns nav TypeDocs	yii\apidoc\templates\bootstrap\RendererTrait
getView()		yii\apidoc\templates\html\GuideRenderer
init()		yii\apidoc\templates\html\GuideRenderer
render()	Renders a set of files given into target directory.	yii\apidoc\templates\bootstrap\GuideRenderer

Protected Methods

Hide inherited methods

Method	Description	Defined By
afterMarkdownProcess()	Callback that is called after markdown is processed.	yii\apidoc\templates\html\GuideRenderer
filterTypes()	Returns types of a given class	yii\apidoc\templates\bootstrap\RendererTrait
fixMarkdownLinks()	Adds guide name to link URLs in markdown	yii\apidoc\templates\html\GuideRenderer
generateGuideFileName()	Given markdown file name generates resulting html file name	yii\apidoc\templates\html\GuideRenderer
generateLink()	Generate link markup	yii\apidoc\templates\html\GuideRenderer
getTypeCategory()	Returns category of TypeDoc	yii\apidoc\templates\bootstrap\RendererTrait
loadGuideStructure()	Loads guide structure from a set of files	yii\apidoc\renderers\GuideRenderer

Constants

Hide inherited constants

Constant	Value	Description	Defined By
GUIDE_PREFIX	'guide-'	Deprecated since 2.0.1 use $guidePrefix instead which allows configuring this options	yii\apidoc\renderers\BaseRenderer

Property Details

Hide inherited properties

$layout public property

public $layout = '@yii/apidoc/templates/bootstrap/layouts/guide.php'

Method Details

Hide inherited methods

afterMarkdownProcess() protected method (available since version 2.0.5)

Defined in: yii\apidoc\templates\html\GuideRenderer::afterMarkdownProcess()

Callback that is called after markdown is processed.

You may override it to do some post processing. The default implementation fixes some markdown links using fixMarkdownLinks() on the output.

protected string afterMarkdownProcess ( $file, $output, $renderer )
$file	string	The file that has been processed.
$output	string	The rendered HTML output.
$renderer	yii\apidoc\helpers\ApiMarkdown	The renderer instance.

Source code

                protected function afterMarkdownProcess($file, $output, $renderer)
{
    return $this->fixMarkdownLinks($output);
}

createSubjectLink() public method

Defined in: yii\apidoc\renderers\BaseRenderer::createSubjectLink()

Creates a link to a subject

public string createSubjectLink ( $subject, $title = null, $options = [] )
$subject	yii\apidoc\models\PropertyDoc\|yii\apidoc\models\MethodDoc\|yii\apidoc\models\ConstDoc\|yii\apidoc\models\EventDoc
$title	string
$options	array	Additional HTML attributes for the link.

Source code

                public function createSubjectLink($subject, $title = null, $options = [])
{
    if ($title === null) {
        if ($subject instanceof MethodDoc) {
            $title = $subject->name . '()';
        } else {
            $title = $subject->name;
        }
    }
    if (($type = $this->apiContext->getType($subject->definedBy)) === null) {
        return $subject->name;
    } else {
        $link = $this->generateApiUrl($type->name);
        if ($subject instanceof MethodDoc) {
            $link .= '#' . $subject->name . '()';
        } else {
            $link .= '#' . $subject->name;
        }
        $link .= '-detail';
        return $this->generateLink($title, $link, $options);
    }
}

createTypeLink() public method

Defined in: yii\apidoc\renderers\BaseRenderer::createTypeLink()

Creates a link to a type (class, interface or trait)

public string createTypeLink ( $types, $context = null, $title = null, $options = [] )
$types	yii\apidoc\models\ClassDoc\|yii\apidoc\models\InterfaceDoc\|yii\apidoc\models\TraitDoc\|yii\apidoc\models\ClassDoc[]\|yii\apidoc\models\InterfaceDoc[]\|yii\apidoc\models\TraitDoc[]\|string\|string[]
$context	yii\apidoc\models\BaseDoc
$title	string	A title to be used for the link TODO check whether [[yii...\|Class]] is supported
$options	array	Additional HTML attributes for the link.

Source code

                public function createTypeLink($types, $context = null, $title = null, $options = [])
{
    if (!is_array($types)) {
        $types = [$types];
    }
    if (count($types) > 1) {
        $title = null;
    }
    $links = [];
    foreach ($types as $type) {
        $postfix = '';
        if (is_string($type)) {
            if (!empty($type) && substr_compare($type, '[]', -2, 2) === 0) {
                $postfix = '[]';
                $type = substr($type, 0, -2);
            }
            if ($type === '$this' && $context instanceof TypeDoc) {
                $title = '$this';
                $type = $context;
            } elseif (($t = $this->apiContext->getType(ltrim($type, '\\'))) !== null) {
                $type = $t;
            } elseif (!empty($type) && $type[0] !== '\\' && ($t = $this->apiContext->getType($this->resolveNamespace($context) . '\\' . ltrim($type, '\\'))) !== null) {
                $type = $t;
            } else {
                ltrim($type, '\\');
            }
        }
        if (is_string($type)) {
            $linkText = ltrim($type, '\\');
            if ($title !== null) {
                $linkText = $title;
                $title = null;
            }
            $phpTypes = [
                'callable',
                'array',
                'string',
                'boolean',
                'bool',
                'integer',
                'int',
                'float',
                'object',
                'resource',
                'null',
                'false',
                'true',
            ];
            $phpTypeAliases = [
                'true' => 'boolean',
                'false' => 'boolean',
                'bool' => 'boolean',
                'int' => 'integer',
            ];
            $phpTypeDisplayAliases = [
                'bool' => 'boolean',
                'int' => 'integer',
            ];
            // check if it is PHP internal class
            if (((class_exists($type, false) || interface_exists($type, false) || trait_exists($type, false)) &&
                ($reflection = new \ReflectionClass($type)) && $reflection->isInternal())) {
                $links[] = $this->generateLink($linkText, 'http://www.php.net/class.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
            } elseif (in_array($type, $phpTypes)) {
                if (isset($phpTypeDisplayAliases[$type])) {
                    $linkText = $phpTypeDisplayAliases[$type];
                }
                if (isset($phpTypeAliases[$type])) {
                    $type = $phpTypeAliases[$type];
                }
                $links[] = $this->generateLink($linkText, 'http://www.php.net/language.types.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
            } else {
                $links[] = $type . $postfix;
            }
        } elseif ($type instanceof BaseDoc) {
            $linkText = $type->name;
            if ($title !== null) {
                $linkText = $title;
                $title = null;
            }
            $links[] = $this->generateLink($linkText, $this->generateApiUrl($type->name), $options) . $postfix;
        }
    }
    return implode('|', $links);
}

filterTypes() protected method

Defined in: yii\apidoc\templates\bootstrap\RendererTrait::filterTypes()

Returns types of a given class

protected array filterTypes ( $types, $navClasses )
$types	yii\apidoc\models\TypeDoc[]
$navClasses	string

Source code

                protected function filterTypes($types, $navClasses)
{
    switch ($navClasses) {
        case 'app':
            $types = array_filter($types, function ($val) {
                return strncmp($val->name, 'yii\\', 4) !== 0;
            });
            break;
        case 'yii':
            $self = $this;
            $types = array_filter($types, function ($val) use ($self) {
                if ($val->name == 'Yii' || $val->name == 'YiiRequirementChecker') {
                    return true;
                }
                if (strlen($val->name) < 5) {
                    return false;
                }
                $subName = substr($val->name, 4, strpos($val->name, '\\', 5) - 4);
                return strncmp($val->name, 'yii\\', 4) === 0 && !in_array($subName, $self->extensions);
            });
            break;
        default:
            $types = array_filter($types, function ($val) use ($navClasses) {
                return strncmp($val->name, "yii\\$navClasses\\", strlen("yii\\$navClasses\\")) === 0;
            });
    }
    return $types;
}

fixMarkdownLinks() protected method

Defined in: yii\apidoc\templates\html\GuideRenderer::fixMarkdownLinks()

Adds guide name to link URLs in markdown

protected string fixMarkdownLinks ( $content )
$content	string

Source code

                protected function fixMarkdownLinks($content)
{
    $content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="' . $this->guidePrefix . '\1.html\2"', $content);
    return $content;
}

generateApiUrl() public method

Defined in: yii\apidoc\templates\html\GuideRenderer::generateApiUrl()

Generate an url to a type in apidocs

public mixed generateApiUrl ( $typeName )
$typeName	mixed

Source code

                public function generateApiUrl($typeName)
{
    return rtrim($this->apiUrl, '/') . '/' . strtolower(str_replace('\\', '-', $typeName)) . '.html';
}

generateGuideFileName() protected method

Defined in: yii\apidoc\templates\html\GuideRenderer::generateGuideFileName()

Given markdown file name generates resulting html file name

protected string generateGuideFileName ( $file )
$file	string	Markdown file name

Source code

                protected function generateGuideFileName($file)
{
    return $this->guidePrefix . basename($file, '.md') . '.html';
}

generateGuideUrl() public method

Defined in: yii\apidoc\renderers\BaseRenderer::generateGuideUrl()

Generate an url to a guide page

public string generateGuideUrl ( $file )
$file	string

Source code

                public function generateGuideUrl($file)
{
    //skip parsing external url
    if ( (strpos($file, 'https://') !== false) || (strpos($file, 'http://') !== false) ) {
        return $file;
    }
    $hash = '';
    if (($pos = strpos($file, '#')) !== false) {
        $hash = substr($file, $pos);
        $file = substr($file, 0, $pos);
    }
    return rtrim($this->guideUrl, '/') . '/' . $this->guidePrefix . basename($file, '.md') . '.html' . $hash;
}

generateLink() protected method

Defined in: yii\apidoc\templates\html\GuideRenderer::generateLink()

Generate link markup

protected mixed generateLink ( $text, $href, $options = [] )
$text	mixed
$href	mixed
$options	array	Additional HTML attributes for the link.

Source code

                protected function generateLink($text, $href, $options = [])
{
    $options['href'] = $href;
    return Html::a($text, null, $options);
}

getGuideReferences() public method

Defined in: yii\apidoc\templates\html\GuideRenderer::getGuideReferences()

public void getGuideReferences ( )

Source code

                public function getGuideReferences()
{
    // TODO implement for api docs
$refs = [];
foreach ($this->markDownFiles as $file) {
	$refName = 'guide-' . basename($file, '.md');
	$refs[$refName] = ['url' => $this->generateGuideFileName($file)];
}
return $refs;
}

getNavTypes() public method

Defined in: yii\apidoc\templates\bootstrap\RendererTrait::getNavTypes()

Returns nav TypeDocs

public array getNavTypes ( $type, $types )
$type	yii\apidoc\models\TypeDoc	Typedoc to take category from
$types	yii\apidoc\models\TypeDoc[]	TypeDocs to filter

Source code

                public function getNavTypes($type, $types)
{
    if ($type === null) {
        return $types;
    }
    return $this->filterTypes($types, $this->getTypeCategory($type));
}

getTypeCategory() protected method

Defined in: yii\apidoc\templates\bootstrap\RendererTrait::getTypeCategory()

Returns category of TypeDoc

protected string getTypeCategory ( $type )
$type	yii\apidoc\models\TypeDoc

Source code

                protected function getTypeCategory($type)
{
    $extensions = $this->extensions;
    $navClasses = 'app';
    if (isset($type)) {
        if ($type->name == 'Yii' || $type->name == 'YiiRequirementChecker') {
            $navClasses = 'yii';
        } elseif (strncmp($type->name, 'yii\\', 4) == 0) {
            $navClasses = 'yii';
            $subName = substr($type->name, 4);
            if (($pos = strpos($subName, '\\')) !== false) {
                $subNamespace = substr($subName, 0, $pos);
                if (in_array($subNamespace, $extensions)) {
                    $navClasses = $subNamespace;
                }
            }
        }
    }
    return $navClasses;
}

getView() public method

Defined in: yii\apidoc\templates\html\GuideRenderer::getView()

public \yii\web\View getView ( )
return	\yii\web\View	The view instance

Source code

                public function getView()
{
    if ($this->_view === null) {
        $this->_view = new View();
        $assetPath = Yii::getAlias($this->_targetDir) . '/assets';
        if (!is_dir($assetPath)) {
            mkdir($assetPath);
        }
        $this->_view->assetManager = new AssetManager([
            'basePath' => $assetPath,
            'baseUrl' => './assets',
        ]);
    }
    return $this->_view;
}

init() public method

Defined in: yii\apidoc\templates\html\GuideRenderer::init()

public void init ( )

Source code

                public function init()
{
    parent::init();
    if ($this->pageTitle === null) {
        $this->pageTitle = 'The Definitive Guide to Yii 2.0';
    }
}

loadGuideStructure() protected method

Defined in: yii\apidoc\renderers\GuideRenderer::loadGuideStructure()

Loads guide structure from a set of files

protected array loadGuideStructure ( $files )
$files	array

Source code

                protected function loadGuideStructure($files)
{
    $chapters = [];
    foreach ($files as $file) {
        $contents = file_get_contents($file);
        if (basename($file) == 'README.md') {
            $indexAnalyzer = new IndexFileAnalyzer();
            $chapters = $indexAnalyzer->analyze($contents);
            break;
        }
        if (preg_match("/^(.*)\n=+/", $contents, $matches)) {
            $headlines[$file] = $matches[1];
        } else {
            $headlines[$file] = basename($file);
        }
    }
    return $chapters;
}

render() public method

Renders a set of files given into target directory.

public void render ( $files, $targetDir )
$files	array
$targetDir	string

Source code

                public function render($files, $targetDir)
{
    $types = array_merge($this->apiContext->classes, $this->apiContext->interfaces, $this->apiContext->traits);
    $extTypes = [];
    foreach ($this->extensions as $k => $ext) {
        $extType = $this->filterTypes($types, $ext);
        if (empty($extType)) {
            unset($this->extensions[$k]);
            continue;
        }
        $extTypes[$ext] = $extType;
    }
    parent::render($files, $targetDir);
    if ($this->controller !== null) {
        $this->controller->stdout('generating search index...');
    }
    $indexer = new ApiIndexer();
    $indexer->indexFiles(FileHelper::findFiles($targetDir, ['only' => ['*.html']]), $targetDir);
    $js = $indexer->exportJs();
    file_put_contents($targetDir . '/jssearch.index.js', $js);
    if ($this->controller !== null) {
        $this->controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    }
}