0byt3m1n1-V2

Path: /home/phangnga/administrator/components/com_attachments/views/help/ [ Home ]
File: helpview.php
<?php
/**
 * Attachments component
 *
 * @package		Attachments
 * @subpackage	Attachments_Component
 *
 * @author		Jonathan M. Cameron <jmcameron@jmcameron.net>
 * @copyright	Copyright (C) 2007-2016 Jonathan M. Cameron, All Rights Reserved
 * @license		http://www.gnu.org/licenses/gpl-3.0.html GNU/GPL
 * @link		http://joomlacode.org/gf/project/attachments/frs/
 */

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

/** Define the legacy classes, if necessary */
require_once JPATH_SITE . '/components/com_attachments/legacy/view.php';

/**
 * View for the help pages
 *
 * The goal is to provide a PHP programmatic interface to create a help page
 * using primarily PHP function calls in the view/template.	 The styling is
 * base on styling of Restructured Text documents rendered into HTML using
 * converion tools such as docutils.
 *
 * @package	 Attachments
 * @since	 3.1
 */
class HelpView extends JViewLegacy
{
	/**
	 * Data about each of the document section headers
	 *
	 * Should be initialized in the view or templage to contain an array of
	 * arrays of information about the sections like this:
	 *
	 * $this->sections = Array( 1  => Array( 'id' => 'introduction',
	 *						   'code' =>		   'SECTION_TITLE_1',
	 *						   'title' => JText::_('SECTION_TITLE_1'),
	 *						   ...
	 *						   ),
	 *
	 * where the 'SECTION_TITLE_1' is the language token for the title of
	 * section 1.
	 */
	protected $sections = null;

	/**
	 * Flag to show codes
	 *
	 */
	protected $show_codes = null;

	/**
	 * Constructor
	 *
	 * @param	array  $config	An optional associative array of configuration settings.
	 */
	public function __construct($config = array())
	{
		parent::__construct($config);

		// Save the plugin type
		$this->show_codes = JRequest::getCmd('show') == 'codes';
	}

	/**
	 * Add the information about a section to the $sections data
	 *
	 * @param	int		$sectnum  the section number (constant)
	 * @param	string	$id		  the section ID string (unique name to be used as anchor target)
	 * @param	string	$code	  the language code for this section title
	 *
	 * @return nothing
	 */
	protected function saveSectionInfo($sectnum, $id, $code)
	{
		$this->sections[$sectnum] = Array('id' => $id, 'code' => $code, 'title' => JText::_($code));
	}

	/**
	 * Construct a tooltip if tooltips are supposed to be shown
	 *
	 * @param	string	$code  Language code for the tooltip
	 *
	 * @return the tooltip to insert in the html
	 */
	protected function constructTooltip($code)
	{
		$tooltip = '';

		if ($this->show_codes)
		{
			$tooltip = " title=\"$code\"";
		}

		return $tooltip;
	}

	/**
	 * Construct the URL with show=codes toggled
	 *
	 * @return the URL
	 */
	protected function toggledURL()
	{
		$uri = JRequest::getURI();

		if ($this->show_codes)
		{
			$uri = str_replace('&show=codes', '', $uri);
		}
		else
		{
			$uri .= '&show=codes';
		}

		return $uri;
	}

	/**
	 * Add a link for the specified section
	 *
	 * @param	int	 $sect_num	The section number to link to
	 *
	 * @return string an html link for the specified section
	 */
	protected function sectionLink($sect_num)
	{
		$id = $this->sections[$sect_num]['id'];
		$title = $this->sections[$sect_num]['title'];

		return "<a class=\"reference internal\" href=\"#$id\">$title</a>";
	}

	/**
	 * Construct a link
	 *
	 * @param	string	$url		 The URL for the link
	 * @param	string	$label_code	 The code for the link label
	 * @param	string	$class		 The class for the link
	 *
	 * @return string an html link
	 */
	protected function link($url, $label_code, $class='')
	{
		$label = JText::_($label_code);

		return "<a $class href=\"$url\">$label</a>";
	}

	/**
	 * Replace a series of items from the html using an array of replacements
	 *
	 * For example:
	 *	  replace('<span>{TEST}-{NUM}</span>', Array('{TEST}' => 'MyTest', '{NUM}' => '23'))
	 * returns:
	 *	  <span>MyTest-23</span>
	 *
	 * @param	string	$html		   The original HTML string to be modified
	 * @param	array	$replacements  Array of textual replacments
	 *
	 * @return	string	the original HTML with the replacements performed
	 */
	protected function replace($html, $replacements)
	{
		if ( is_array($replacements) )
		{
			foreach ($replacements as $tag => $replace)
			{
				$html = str_replace($tag, $replace, $html);
			}
		}

		return $html;
	}

	/**
	 * Add a table of contents
	 *
	 * @param	string	$title_code	 The language code for the title of the table of contents
	 * @param	sting	$class		 The class for the table of contents (default: contents topic)
	 *
	 * @return nothing
	 */
	protected function tableOfContents($title_code, $class = 'contents topic')
	{
		$title = JText::_($title_code);
		$tooltip = $this->constructTooltip($title_code);

		$html  = "<div class=\"$class\" id=\"contents\">\n";
		$html .= "   <p class=\"topic-title first\" $tooltip>$title</p>\n";
		$html .= "   <ul class=\"$class\">\n";

		foreach ($this->sections as $sect_num => $sdata)
		{
			$html .= '      ' . $this->sectionTOC($sect_num);
		}

		$html .= "   </ul>\n";
		$html .= "</div> <!-- table of contents -->\n";
		echo $html;
	}

	/**
	 * Construct a section Table-of-contents line for a section
	 *
	 * @param	int	 $sect_num	The section number to echo (as a list element)
	 *
	 * @return string  the table-of-conents list item
	 */
	protected function sectionTOC($sect_num)
	{
		$sect_data = $this->sections[$sect_num];
		$id = $sect_data['id'];
		$title = $sect_data['title'];
		$tooltip = $this->constructTooltip($sect_data['code']);

		return "<li><a class=\"reference internal\" href=\"#$id\" id=\"id$sect_num\" $tooltip>$title</a></li>\n";
	}

	/**
	 * Add the start of a section (using <h1>)
	 *
	 * @param	int	 $sect_num	The desired section number
	 *
	 * @return nothing
	 */
	protected function startSection($sect_num)
	{
		$sect_data = $this->sections[$sect_num];
		$id = $sect_data['id'];
		$text_code = $sect_data['code'];
		$tooltip = $this->constructTooltip($sect_data['code']);
		$title = $sect_data['title'];
		$hclass = 'class="toc-backref"';
		$html = "<div class=\"section\" id=\"$id\">\n";
		$html .= "<h1><a $hclass href=\"#id$sect_num\" $tooltip>$title</a></h1>\n";
		echo $html;
	}

	/**
	 * Add the end of a section
	 *
	 * @param	int	 $sect_num	The desired section number
	 *
	 * @return nothing
	 */
	protected function endSection($sect_num)
	{
		echo "</div><?-- end of section $sect_num -->\n";
	}

	/**
	 * Add the start of a subsection (using <h2>)
	 *
	 * @param	array  $sect_data  An array of data for the subsection (providing 'id' and 'title')
	 *
	 * @return nothing
	 */
	protected function startSubSection($sect_data)
	{
		$id = $sect_data['id'];
		$code = $sect_data['code'];
		$title = JText::_($code);
		$tooltip = $this->constructTooltip($code);

		$html  = "<div class=\"section\" id=\"$id\">\n";
		$html .= "<h2 $tooltip>$title</h2>\n";
		echo $html;
	}

	/**
	 * Add the start of a subsection (using <h2>)
	 *
	 * @param	string	$title	The subsection title (should be same as in the start)
	 *
	 * @return nothing
	 */
	protected function endSubSection($title)
	{
		echo "</div><?-- end of subsection $title -->\n";
	}

	/**
	 * Construct an admonition (note, warning, hint, etc)
	 *
	 * @param	string	$type		   The type of admonition (hint, note, important, warning)
	 * @param	string	$type_code	   Language token for the name of the admonition (eg, $type)
	 * @param	array	$text_codes	   Array of Language tokens for the body text (as separate paragraphs in the admonition)
	 * @param	array	$replacements  Array of replacements to be applied to the body text (see replace functin)
	 * @param	bool	$terminate	   Whether to terminatate the <div> that contains the note
	 *
	 * @return nothing
	 */
	protected function addAdmonition($type, $type_code, $text_codes, $replacements = null, $terminate = true)
	{
		if (!is_array($text_codes))
		{
			$text_codes = Array($text_codes);
		}

		$title = JText::_($type_code);
		$tooltip = $this->constructTooltip($type_code);

		$html  = "<div class=\"$type\">\n";
		$html .= "   <p class=\"first admonition-title\" $tooltip>$title</p>\n";

		foreach ($text_codes as $text_code)
		{
			$text = $this->replace(JText::_($text_code), $replacements);
			$tooltip = $this->constructTooltip($text_code);
			$html .= "   <p class=\"last\" $tooltip>$text</p>\n";
		}

		if ( $terminate )
		{
			$html .= "</div>\n";
		}

		echo $html;
	}

	/**
	 * Add the end the admonition
	 *
	 * @return nothing
	 */
	protected function endAdmonition()
	{
		echo "</div>\n";
	}

	/**
	 * Add a 'hint' admonition
	 *
	 * @param	array  $text_codes	  Array of Language tokens for the body text (as separate paragraphs in the admonition)
	 * @param	array  $replacements  Array of replacements to be applied to the body text (see replace functin)
	 * @param	bool   $terminate	  Whether to terminatate the <div> that contains the note
	 *
	 * @return nothing
	 */
	protected function addHint($text_codes, $replacements = null, $terminate = true)
	{
		echo $this->addAdmonition('hint', 'ATTACH_HELP_HINT', $text_codes, $replacements, $terminate);
	}

	/**
	 * Add an 'important' admonition
	 *
	 * @param	array  $text_codes	  Array of Language tokens for the body text (as separate paragraphs in the admonition)
	 * @param	array  $replacements  Array of replacements to be applied to the body text (see replace functin)
	 * @param	bool   $terminate	  Whether to terminatate the <div> that contains the note
	 *
	 * @return nothing
	 */
	protected function addImportant($text_codes, $replacements = null, $terminate = true)
	{
		echo $this->addAdmonition('important', 'ATTACH_HELP_IMPORTANT', $text_codes, $replacements, $terminate);
	}

	/**
	 * Add a 'note' admonition
	 *
	 * @param	array  $text_codes	  Array of Language tokens for the body text (as separate paragraphs in the admonition)
	 * @param	array  $replacements  Array of replacements to be applied to the body text (see replace functin)
	 * @param	bool   $terminate	  Whether to terminatate the <div> that contains the note
	 *
	 * @return nothing
	 */
	protected function addNote($text_codes, $replacements = null, $terminate = true)
	{
		echo $this->addAdmonition('note', 'ATTACH_HELP_NOTE', $text_codes, $replacements, $terminate);
	}

	/**
	 * Add a 'warning' admonition
	 *
	 * @param	array  $text_codes	  Array of Language tokens for the body text (as separate paragraphs in the admonition)
	 * @param	array  $replacements  Array of replacements to be applied to the body text (see replace functin)
	 * @param	bool   $terminate	  Whether to terminatate the <div> that contains the note
	 *
	 * @return nothing
	 */
	protected function addWarning($text_codes, $replacements = null, $terminate = true)
	{
		echo $this->addAdmonition('warning', 'ATTACH_HELP_WARNING', $text_codes, $replacements, $terminate);
	}

	/**
	 * Add a paragraph
	 *
	 * @param	array	$text_codes	   Array of Language tokens for the body text (as separate paragraphs)
	 * @param	array	$replacements  Array of replacements to be applied to the text (see replace functin)
	 * @param	string	$pclass		   The class for the paragraph HTML <p> element
	 *
	 * @return nothing
	 */
	protected function addParagraph($text_codes, $replacements = null, $pclass = null)
	{
		if (!is_array($text_codes))
		{
			$text_codes = Array($text_codes);
		}

		$html = '';

		foreach ($text_codes as $text_code)
		{
			$text = $this->replace(JText::_($text_code), $replacements);
			$tooltip = $this->constructTooltip($text_code);

			if ($pclass)
			{
				$html .= "<p class=\"$pclass hasTip\" $tooltip>" . $text . "</p>\n";
			}
			else
			{
				$html .= "<p class=\"hasTip\" $tooltip>" . $text . "</p>\n";
			}
		}

		echo $html;
	}

	/**
	 * Add a preformatted block
	 *
	 * @param	string	$text	The raw string to print literally
	 * @param	string	$class	The class for the HTML <pre> block
	 *
	 * @return nothing
	 */
	protected function addPreBlock($text, $class='literal-block')
	{
		$html = "<pre class=\"$class\">\n";
		$html .= $text . "\n";
		$html .= "</pre>\n";
		echo $html;
	}

	/**
	 * Start an a list (unordered by default)
	 *
	 * @param	string	$type	The type of list (defaults to unordered <ul>)
	 * @param	string	$class	The class for the HTML <ul> or <ol> element
	 *
	 * @return nothing
	 */
	protected function startList($type = 'ul', $class='simple')
	{
		echo "<$type class=\"$class\">\n";
	}

	/**
	 * Add a list element
	 *
	 * @param	array  $text_codes	  Array of Language tokens for the body text (as separate paragraphs inside the list element)
	 * @param	array  $replacements  Array of replacements to be applied to the text (see replace function)
	 * @param	bool   $terminate	  Whether to terminatate the <li> that contains the text
	 *
	 * @return nothing
	 */
	protected function addListElement($text_codes, $replacements = null, $terminate = true)
	{
		$html = '<li>';

		if (!is_array($text_codes))
		{
			$text_codes = Array($text_codes);
		}
		foreach ($text_codes as $text_code)
		{
			$text = $this->replace(JText::_($text_code), $replacements);
			$tooltip = $this->constructTooltip($text_code);
			$html .= "<p class=\"hasTip\" $tooltip>$text</p>\n";
		}

		if ($terminate)
		{
			$html .= "</li>\n";
		}

		echo $html;
	}

	/**
	 * Add a list element for a definition for a term (a word or phrase)
	 *
	 * @param	array  $text_codes	  Array of Language tokens for the body text (as separate paragraphs inside the list element)
	 * @param	array  $replacements  Array of replacements to be applied to the text (see replace function)
	 * @param	bool   $terminate	  Whether to terminatate the <li> that contains the text
	 *
	 * @return nothing
	 */
	protected function addDefinitionListElement($term_code, $definition_codes,
												$replacements = null, $terminate = true)
	{
		// Set up the term
		$term_tooltip = $this->constructTooltip($term_code);
		if ($term_tooltip)
		{
			$term_tooltip = " class=\"hasTip\" ".$term_tooltip;
		}
		$html = "<li><strong $term_tooltip>".JText::_($term_code).':</strong> ';

		// Add the definition
		if (!is_array($definition_codes))
		{
			$definition_codes = Array($definition_codes);
		}
		foreach ($definition_codes as $text_code)
		{
			$text = $this->replace(JText::_($text_code), $replacements);
			$tooltip = $this->constructTooltip($text_code);
			$html .= "<p class=\"hasTip\" $tooltip>$text</p>\n";
		}

		if ($terminate)
		{
			$html .= "</li>\n";
		}

		echo $html;
	}

	/**
	 * Add the ending of a list element (use with unterminated list element)
	 *
	 * @return nothing
	 */
	protected function endListElement()
	{
		echo "</li>\n";
	}

	/**
	 * Add a link as a list element
	 *
	 * @param	string	$url		the URL of the link
	 * @param	string	$text_code	the language token for the text of the link
	 *
	 * @return nothing
	 */
	protected function addListElementLink($url, $text_code)
	{
		$text = $this->replace(JText::_($text_code), Array('{LINK}' => $url));
		$tooltip = $this->constructTooltip($text_code);
		echo "<li><a class=\"reference external\" $tooltip href=\"$url\">$text</a></li>\n";
	}

	/**
	 * Add a list elment with raw HTML
	 *
	 * @param	string	$html  The HTML to insert into the list element
	 *
	 * @return nothing
	 */
	protected function addListElementHtml($html)
	{
		echo "<li>$html</li>\n";
	}

	/**
	 * Add the end of a list
	 *
	 * @param	string	$type  The class for the HTML </ul> or </ol> element
	 *
	 * @return nothing
	 */
	protected function endList($type = 'ul')
	{
		echo "</$type>\n";
	}

	/**
	 * Add a line break
	 *
	 * @return nothing
	 */
	protected function addLineBreak()
	{
		echo "<br/>\n";
	}

	/**
	 * Add a figure: and image with an optional caption
	 *
	 * @param	string	$filename	   Filename for the image (full path)
	 * @param	string	$alt_code	   Language token for the text to be use for the 'alt' attribute
	 * @param	string	$caption_code  Language token for the text to use for the caption (OPTIONAL)
	 * @param	string	$dclass		   Class for the figure div
	 * @param	string	$img_attribs   attributes for the 'img' html tag
	 *
	 * @return nothing
	 */
	protected function addFigure($filename, $alt_code, $caption_code = null, $dclass = 'figure', $img_attribs=array())
	{
		$html = "<div class=\"$dclass\">\n";
		$html .= $this->image($filename, $alt_code, $img_attribs) . "\n";

		if ( $caption_code )
		{
			$html .= "<p class=\"caption\" title=\"$caption_code\">" . JText::_($caption_code) . "</p>\n";
		}

		$html .= '</div>';
		echo $html;
	}

	/**
	 * Return an image URL if the file is found
	 *
	 * @param	string	$filename  Filename for the image in the media folder (more below)
	 * @param	string	$alt_code  Language code for text to be inserted into the alt='text' attribute
	 * @param	array	$attribs   Attributes to be added to the image URL
	 *
	 * The file location uses the JHtml::image() function call which expects
	 * to find images in the [base]/media/com_attachments/images directory.
	 * This function has the necessary checks to add level of language folders
	 * (like the translation files).  For instance:
	 *
	 *	  For a file:
	 *		   [base]/media/com_attachments/images/en-GB/test1.png
	 *	  Use:
	 *		   $this->image('com_attachments/test1.png')
	 * 
	 * The language tag will be handled automatically.
	 *
	 * @return string image URL (or null if the image was not found)
	 */
	protected function image($filename, $alt_code, $attribs = Array())
	{
		$lcode = $this->lang->getTag();
		$alt = '';

		if ($alt_code)
		{
			$alt = JText::_($alt_code);
		}

		// First try the current language
		$found = JHtml::image('com_attachments/help/' . $lcode . '/' . $filename, $alt, $attribs, true, true);

		if ($found)
		{
			return JHtml::image('com_attachments/help/' . $lcode . '/' . $filename, $alt, $attribs, true);
		}

		// If that fails, return the English/en-GB image
		if ( $lcode != 'en-GB' )
		{
			return JHtml::image('com_attachments/help/en-GB/' . $filename, $alt, $attribs, true);
		}

		// The image was not found for either language so return nothing
		return null;
	}
}