模块

Controller_Userguide
继承自 Controller_Template
继承自 Controller

BootPHP user guide and api browser.

package
BootPHP/Userguide
category
Controllers
author
Tinsh

该类在 MODPATH/userguide/classes/controller/userguide.php 第 10 行声明。

属性

public boolean $auto_render

自动渲染模板

public Request $request

创建控制器的请求

public Response $response

从控制器返回的响应

public $template

protected $api

protected $guide

protected $media

方法

public action_api( ) (在 Controller_Userguide 中定义)

源代码

public function action_api()
{
	// Enable the missing class autoloader. If a class cannot be found a
	// fake class will be created that extends Bootdoc_Missing
	spl_autoload_register(array('Bootdoc_Missing', 'create_class'));
	// Get the class from the request
	$class = $this->request->param('class');
	// If no class was passed to the url, display the API index page
	if ( !$class )
	{
		$this->template->title = 'Table of Contents';
		$this->template->content = View::factory('userguide/api/toc')
			->set('classes', Bootdoc::class_methods())
			->set('route', $this->request->route());
	}
	else
	{
		// Create the Bootdoc_Class version of this class.
		$_class = Bootdoc_Class::factory($class);
		// If the class requested and the actual class name are different
		// (different case, orm vs ORM, auth vs Auth) redirect
		if ( $_class->class->name != $class )
		{
			$this->request->redirect($this->request->route()->uri(array('class' => $_class->class->name)));
		}
		// If this classes immediate parent is Bootdoc_Missing, then it should 404
		if ( $_class->class->getParentClass() && $_class->class->getParentClass()->name == 'Bootdoc_Missing' )
			return $this->error('That class was not found. Check your url and make sure that the module with that class is enabled.');
		// If this classes package has been disabled via the config, 404
		if ( !Bootdoc::show_class($_class) )
			return $this->error('That class is in package that is hidden. Check the <code>api_packages</code> config setting.');
		// Everything is fine, display the class.
		$this->template->title = $class;
		$this->template->content = View::factory('userguide/api/class')
			->set('doc', Bootdoc::factory($class))
			->set('route', $this->request->route());
	}
	// Attach the menu to the template
	$this->template->menu = Bootdoc::menu();
	// Bind the breadcrumb
	$this->template->bind('breadcrumb', $breadcrumb);
	// Get the docs URI
	$guide = Route::get('docs/guide');
	// Add the breadcrumb
	$breadcrumb = array();
	$breadcrumb[$this->guide->uri(array('page' => NULL))] = 'User Guide';
	$breadcrumb[$this->request->route()->uri()] = 'API Browser';
	$breadcrumb[] = $this->template->title;
}

public action_docs( ) (在 Controller_Userguide 中定义)

源代码

public function action_docs()
{
	$module = $this->request->param('module');
	$page = $this->request->param('page');
	// Trim trailing slash
	$page = rtrim($page, '/');
	// If no module provided in the url, show the user guide index page, which lists the modules.
	if ( !$module )
	{
		return $this->index();
	}
	// If this module's userguide pages are disabled, show the error page
	if ( !BootPHP::$config->load('userguide.modules.' . $module . '.enabled') )
	{
		return $this->error('That module doesn\'t exist, or has userguide pages disabled.');
	}
	// Prevent "guide/module" and "guide/module/index" from having duplicate content
	if ( $page == 'index' )
	{
		return $this->error('Userguide page not found');
	}
	// If a module is set, but no page was provided in the url, show the index page
	if ( !$page )
	{
		$page = 'index';
	}
	// Find the markdown file for this page
	$file = $this->file($module . '/' . $page);
	// If it's not found, show the error page
	if ( !$file )
	{
		return $this->error('Userguide page not found');
	}
	// Namespace the markdown parser
	Bootdoc_Markdown::$base_url = URL::site($this->guide->uri()) . '/' . $module . '/';
	Bootdoc_Markdown::$image_url = URL::site($this->media->uri()) . '/' . $module . '/';
	// Set the page title
	$this->template->title = $page == 'index' ? BootPHP::$config->load('userguide.modules.' . $module . '.name') : $this->title($page);
	// Parse the page contents into the template
	Bootdoc_Markdown::$show_toc = true;
	$this->template->content = Bootdoc_Markdown::markdown(file_get_contents($file));
	Bootdoc_Markdown::$show_toc = false;
	// Attach this module's menu to the template
	$this->template->menu = Bootdoc_Markdown::markdown($this->_get_all_menu_markdown());
	// Bind the breadcrumb
	$this->template->bind('breadcrumb', $breadcrumb);
	// Bind the copyright
	$this->template->copyright = BootPHP::$config->load('userguide.modules.' . $module . '.copyright');
	// Add the breadcrumb trail
	$breadcrumb = array();
	$breadcrumb[$this->guide->uri()] = 'User Guide';
	$breadcrumb[$this->guide->uri(array('module' => $module))] = BootPHP::$config->load('userguide.modules.' . $module . '.name');
	// TODO try and get parent category names (from menu). Regex magic or javascript dom stuff perhaps?
	// Only add the current page title to breadcrumbs if it isn't the index, otherwise we get repeats.
	if ( $page != 'index' )
	{
		$breadcrumb[] = $this->template->title;
	}
}

public action_media( ) (在 Controller_Userguide 中定义)

源代码

public function action_media()
{
	// Get the file path from the request
	$file = $this->request->param('file');
	// Find the file extension
	$ext = pathinfo($file, PATHINFO_EXTENSION);
	// Remove the extension from the filename
	$file = substr($file, 0, -(strlen($ext) + 1));
	if ( $file = BootPHP::find_file('media/guide', $file, $ext) )
	{
		// Check if the browser sent an "if-none-match: <etag>" header, and tell if the file hasn't changed
		$this->response->check_cache(sha1($this->request->uri()) . filemtime($file), $this->request);
		// Send the file content as the response
		$this->response->body(file_get_contents($file));
		// Set the proper headers to allow caching
		$this->response->headers('content-type', File::mime_by_ext($ext));
		$this->response->headers('last-modified', date('r', filemtime($file)));
	}
	else
	{
		// Return a 404 status
		$this->response->status(404);
	}
}

public after( ) (在 Controller_Userguide 中定义)

分配模板 View 作为请求的响应。

源代码

public function after()
{
	if ( $this->auto_render )
	{
		// Get the media route
		$media = Route::get('docs/media');
		// Add styles
		$this->template->styles = array(
			$media->uri(array('file' => 'css/screen.css')) => 'screen',
			$media->uri(array('file' => 'css/bootdoc.css')) => 'screen',
			$media->uri(array('file' => 'css/shCore.css')) => 'screen',
			$media->uri(array('file' => 'css/shTheme.css')) => 'screen',
		);
		// Add scripts
		$this->template->scripts = array(
			$media->uri(array('file' => 'js/jquery.min.js')),
			$media->uri(array('file' => 'js/bootdoc.js')),
			// Syntax Highlighter
			$media->uri(array('file' => 'js/shCore.js')),
			$media->uri(array('file' => 'js/shBrushPhp.js')),
		);
		// Add languages
		$this->template->translations = BootPHP::message('userguide', 'translations');
	}
	return parent::after();
}

public before( ) (在 Controller_Userguide 中定义)

加载模板 View 对象。

源代码

public function before()
{
	parent::before();
	if ( $this->request->action() === 'media' )
	{
		// Do not template media files
		$this->auto_render = false;
	}
	else
	{
		// Grab the necessary routes
		$this->media = Route::get('docs/media');
		$this->guide = Route::get('docs/guide');
		// Set the base URL for links and images
		Bootdoc_Markdown::$base_url = URL::site($this->guide->uri()) . '/';
		Bootdoc_Markdown::$image_url = URL::site($this->media->uri()) . '/';
	}
}

public error( ) (在 Controller_Userguide 中定义)

源代码

public function error($message)
{
	$this->response->status(404);
	$this->template->title = '用户指南 - 错误';
	$this->template->content = View::factory('userguide/error', array('message' => $message));
	// If we are in a module and that module has a menu, show that
	if ( $module = $this->request->param('module') && $menu = $this->file($module . '/menu') && BootPHP::$config->load('userguide.modules.' . $module . '.enabled') )
	{
		// Namespace the markdown parser
		Bootdoc_Markdown::$base_url = URL::site($this->guide->uri()) . '/' . $module . '/';
		Bootdoc_Markdown::$image_url = URL::site($this->media->uri()) . '/' . $module . '/';
		$this->template->menu = Bootdoc_Markdown::markdown($this->_get_all_menu_markdown());
		$this->template->breadcrumb = array(
			$this->guide->uri() => 'User Guide',
			$this->guide->uri(array('module' => $module)) => BootPHP::$config->load('userguide.modules.' . $module . '.name'),
			'Error'
		);
	}
	// If we are in the api browser, show the menu and show the api browser in the breadcrumbs
	else if ( Route::name($this->request->route()) == 'docs/api' )
	{
		$this->template->menu = Bootdoc::menu();
		// Bind the breadcrumb
		$this->template->breadcrumb = array(
			$this->guide->uri(array('page' => NULL)) => 'User Guide',
			$this->request->route()->uri() => 'API Browser',
			'Error'
		);
	}
	// Otherwise, show the userguide module menu on the side
	else
	{
		$this->template->menu = View::factory('userguide/menu', array('modules' => $this->_modules()));
		$this->template->breadcrumb = array($this->request->route()->uri() => 'User Guide',
			'Error');
	}
}

public file( string $page ) (在 Controller_Userguide 中定义)

Locates the appropriate markdown file for a given guide page. Page URLS can be specified in one of three forms:

  • userguide/adding
  • userguide/adding.md
  • userguide/adding.markdown

In every case, the userguide will search the cascading file system paths for the file guide/userguide/adding.md.

参数

  • string $page required - The relative URL of the guide page

返回值

  • string

源代码

public function file($page)
{
	// Strip optional .md or .markdown suffix from the passed filename
	$info = pathinfo($page);
	if ( isset($info['extension']) && ( ($info['extension'] === 'md') || ($info['extension'] === 'markdown') ) )
	{
		$page = $info['dirname'] . DIRECTORY_SEPARATOR . $info['filename'];
	}
	return BootPHP::find_file('guide', $page, 'md');
}

public index( ) (在 Controller_Userguide 中定义)

源代码

public function index()
{
	$this->template->title = '用户指南';
	$this->template->breadcrumb = array('用户指南');
	$this->template->content = View::factory('userguide/index', array('modules' => $this->_modules()));
	$this->template->menu = View::factory('userguide/menu', array('modules' => $this->_modules()));
}

public section( ) (在 Controller_Userguide 中定义)

源代码

public function section($page)
{
	$markdown = $this->_get_all_menu_markdown();
	if ( preg_match('~\*{2}(.+?)\*{2}[^*]+\[[^\]]+\]\(' . preg_quote($page) . '\)~mu', $markdown, $matches) )
	{
		return $matches[1];
	}
	return $page;
}

public title( ) (在 Controller_Userguide 中定义)

源代码

public function title($page)
{
	$markdown = $this->_get_all_menu_markdown();
	if ( preg_match('~\[([^\]]+)\]\(' . preg_quote($page) . '\)~mu', $markdown, $matches) )
	{
		// Found a title for this link
		return $matches[1];
	}
	return $page;
}

public __construct( Request $request , Response $response ) (在 Controller 中定义)

创建一个新的控制器实例。每个控制器必须由创建它的请求对象来构造。

参数

  • Request $request required - 创建控制器的请求
  • Response $response required - 请求的响应

返回值

  • void

源代码

public function __construct(Request $request, Response $response)
{
	// 将请求分配给控制器
	$this->request = $request;
	// 将响应分配给控制器
	$this->response = $response;
}

protected _get_all_menu_markdown( ) (在 Controller_Userguide 中定义)

源代码

protected function _get_all_menu_markdown()
{
	// Only do this once per request...
	static $markdown = '';
	if ( empty($markdown) )
	{
		// Get menu items
		$file = $this->file($this->request->param('module') . '/menu');
		if ( $file && $text = file_get_contents($file) )
		{
			// Add spans around non-link categories. This is a terrible hack.
			//echo Debug::vars($text);
			//$text = preg_replace('/(\s*[\-\*\+]\s*)(.*)/','$1<span>$2</span>',$text);
			$text = preg_replace('/^(\s*[\-\*\+]\s*)([^\[\]]+)$/m', '$1<span>$2</span>', $text);
			//echo Debug::vars($text);
			$markdown .= $text;
		}
	}
	return $markdown;
}

protected _modules( ) (在 Controller_Userguide 中定义)

源代码

protected function _modules()
{
	$modules = array_reverse(BootPHP::$config->load('userguide.modules'));
	if ( isset($modules['bootphp']) )
	{
		$bootphp = $modules['bootphp'];
		unset($modules['bootphp']);
		$modules = array_merge(array('bootphp' => $bootphp), $modules);
	}
	// Remove modules that have been disabled via config
	foreach( $modules as $key => $value )
	{
		if ( !BootPHP::$config->load('userguide.modules.' . $key . '.enabled') )
		{
			unset($modules[$key]);
		}
	}
	return $modules;
}