You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
522 lines
20 KiB
522 lines
20 KiB
<?php
|
|
|
|
// (c) Copyright by authors of the Tiki Wiki CMS Groupware Project
|
|
//
|
|
// All Rights Reserved. See copyright.txt for details and a complete list of authors.
|
|
// Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details.
|
|
// $Id:
|
|
|
|
function wikiplugin_prefdoc_info()
|
|
{
|
|
return [
|
|
'name' => tra('Document Preferences'),
|
|
'documentation' => 'PluginPrefDoc',
|
|
'description' => tra('Generate documentation for Tiki preference tabs, mostly for use on the Tiki documentation website (doc.tiki.org).'),
|
|
'prefs' => [ 'wikiplugin_prefdoc' ],
|
|
'validate' => 'all',
|
|
'introduced' => 17,
|
|
'iconname' => 'th-list',
|
|
'tags' => [ 'advanced' ],
|
|
'params' => [
|
|
'tab' => [
|
|
'required' => false,
|
|
'name' => tra('Preference-Tab'),
|
|
'description' => tra('The name of the preference tab to display, or a list of available tabs upon invalid.'),
|
|
'filter' => 'text',
|
|
'since' => '17',
|
|
],
|
|
'img' => [
|
|
'required' => false,
|
|
'name' => tra('Images'),
|
|
'description' => tra('Show images at the top of each version of Tiki. Format: TikiVersion:FileGalleryID. Multiple images my be separated like so: TikiVersion1:FileGalleryID1|TikiVersion2:FileGalleryID2.'),
|
|
'since' => '17',
|
|
'filter' => 'text',
|
|
],
|
|
],
|
|
];
|
|
}
|
|
|
|
/**
|
|
*
|
|
* Generate, Display & Archive Tiki Pref Documentation
|
|
*
|
|
* @param $data string this is ignored
|
|
* @param $params array parameters to process
|
|
*
|
|
* @return string formatted pref table (wiki format) or list of preference tabs (with errors)
|
|
*/
|
|
|
|
function wikiplugin_prefdoc($data, $params)
|
|
{
|
|
|
|
$Doc = new PrefsDoc();
|
|
|
|
if (is_readable('storage/prefsdoc/state.json')) {
|
|
$Doc->state = json_decode(file_get_contents("storage/prefsdoc/state.json"));
|
|
}
|
|
if (! $Doc->genPrefsState()) {
|
|
return $Doc->error;
|
|
}
|
|
|
|
if (! isset($params['tab'])) { // if no tab specified, return a list of available tabs
|
|
return $Doc->genPrefCodes();
|
|
}
|
|
|
|
if (! $Doc->genPrefHistory($params['tab'], @$params['img'])) {
|
|
return $Doc->error;
|
|
}
|
|
return $Doc->error . $Doc->docTable;
|
|
}
|
|
|
|
|
|
/**
|
|
*
|
|
*
|
|
* Used for automatically generating preference documentation
|
|
* for use on doc.tiki.org. It takes the currently installed preferences
|
|
* and generates files in wiki-syntax
|
|
*
|
|
* Running this will overwrite any previously generated pref doc files
|
|
*
|
|
*
|
|
* Class PrefsDoc
|
|
*
|
|
* @var $docTable string The output to be sent to displayed, in wiki format
|
|
*
|
|
*/
|
|
class PrefsDoc extends TWVersion
|
|
{
|
|
|
|
public $docTable;
|
|
public $error;
|
|
public $state;
|
|
private $PrefVars;
|
|
private $prevFilePrefs;
|
|
private $fileCount;
|
|
private $prefCount;
|
|
private $prefDefault;
|
|
private $prefDefaultFull;
|
|
private $prefDescription;
|
|
private $prefName;
|
|
|
|
/**
|
|
*
|
|
* Populates $docTable with a string to display.
|
|
* The main function to generate version tabs etc.
|
|
*
|
|
* @param $tabName string The pref-tab name to create an output for
|
|
* @param $images string Images & Versions to display with a Version tab.
|
|
*
|
|
* @return bool true on success false on failure
|
|
*/
|
|
public function genPrefHistory($tabName, $images)
|
|
{
|
|
|
|
if (! isset($this->state->files->{$tabName})) {
|
|
$this->error .= "Error: <strong>Cant find $tabName</strong> you may choose from one of the following: \n" . $this->genPrefCodes();
|
|
return false;
|
|
}
|
|
|
|
$this->docTable = '{TABS(name="' . $tabName . '" tabs="Tiki Version ' . implode('|', $this->state->files->{$tabName}) . "\" toggle=\"n\")}";
|
|
$imageArray = [];
|
|
$images = explode('|', $images);
|
|
foreach ($images as $key => $image) {
|
|
$image = explode(':', $image);
|
|
$imageArray[$image[0]][0] = @$image[1];
|
|
$imageArray[$image[0]][1] = $image[0];
|
|
}
|
|
unset($images);
|
|
|
|
// carry over images from past versions of Tiki, if available.
|
|
foreach ($this->state->files->{$tabName} as $key => $version) {
|
|
$count = $version;
|
|
while ($version - $count < 5) { // If the image is older than 5 tiki versions, dont display it.
|
|
if (@$imageArray[$count][0]) {
|
|
$this->docTable .= '{img fileId="' . $imageArray[$count][0] . '" thumb="y" rel="box[g]" width="300" desc="Tiki ' . $imageArray[$count][1] . ' Preferences Image" alt="' . $tabName . '" align="center"}';
|
|
break;
|
|
}
|
|
$count--;
|
|
}
|
|
$this->genPrefVersion("storage/prefsdoc/$version-$tabName.json");
|
|
$key++;
|
|
if (isset($this->state->files->{$tabName}[$key])) {
|
|
$this->docTable .= '/////';
|
|
}
|
|
}
|
|
|
|
|
|
$this->docTable .= '{TABS}';
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
*
|
|
* Generates a list of valid pref codes when no preference page was specified
|
|
*
|
|
* @return string file-tab codes available for use.
|
|
*/
|
|
public function genPrefCodes()
|
|
{
|
|
|
|
$codes = '';
|
|
foreach ($this->state->files as $key => $value) {
|
|
$codes .= $key . '<br>';
|
|
}
|
|
|
|
return $codes;
|
|
}
|
|
|
|
/**
|
|
*
|
|
* Generates a wiki syntax table for a specific version of tiki
|
|
*
|
|
* @param string $fileName The file name to write to disk.
|
|
*
|
|
* @return bool false on error, true otherwise
|
|
*/
|
|
private function genPrefVersion($fileName)
|
|
{
|
|
if (! is_file($fileName)) {
|
|
$this->error .= "Cant read $fileName. ";
|
|
return false;
|
|
}
|
|
$this->docTable .= '{FANCYTABLE(head="Option | Description | Default" sortable="n")}';
|
|
$FilePrefs = json_decode(file_get_contents($fileName));
|
|
foreach ($FilePrefs->prefs as $prefName => &$pref) {
|
|
$this->prevFilePrefs;
|
|
|
|
// carry over missing information filled out in a newer version
|
|
if (empty($pref->description)) {
|
|
$pref->description = @$this->prevFilePrefs->$prefName->description;
|
|
}
|
|
if (empty($pref->detail)) {
|
|
$pref->detail = @$this->prevFilePrefs->$prefName->detail;
|
|
}
|
|
if (empty($pref->help)) {
|
|
$pref->help = @$this->prevFilePrefs->$prefName->help;
|
|
}
|
|
if (empty($pref->hint)) {
|
|
$pref->hint = @$this->prevFilePrefs->$prefName->hint;
|
|
}
|
|
if (empty($pref->shorthint)) {
|
|
$pref->shorthint = @$this->prevFilePrefs->$prefName->shorthint;
|
|
}
|
|
if (empty($pref->warning)) {
|
|
$pref->warning = @$this->prevFilePrefs->$prefName->warning;
|
|
}
|
|
$this->setParams($pref);
|
|
$this->docTable .= $this->prefName . '~|~' . $this->prefDescription . '~|~<span title="' . $this->prefDefaultFull . '">' . $this->prefDefault . "</span>\n";
|
|
}
|
|
$this->prevFilePrefs = $FilePrefs->prefs;
|
|
$this->docTable .= "{FANCYTABLE}";
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
*
|
|
* This sets an vars of an individual preference
|
|
*
|
|
* @param $param object the prefs to be processed into pretty & standardized output
|
|
*/
|
|
private function setParams($param)
|
|
{
|
|
$this->prefDefaultFull = '';
|
|
|
|
// set default
|
|
if (! empty($param->options) && isset($param->default) && $param->default !== '') {
|
|
$this->prefDefault = $param->options->{$param->default};
|
|
} elseif ($param->default === 'n') {
|
|
$this->prefDefault = 'Disabled';
|
|
} elseif ($param->default === 'y') {
|
|
$this->prefDefault = 'Enabled'; // Change default codes to human readable format
|
|
} elseif (is_array($param->default)) {
|
|
$this->prefDefault = implode(', ', $param->default);
|
|
} else {
|
|
$this->prefDefault = $param->default;
|
|
}
|
|
// end first processing the below should be applied to the above.... not a continuation (eg. empty array)
|
|
$this->prefDefault = trim($this->prefDefault);
|
|
if ($this->prefDefault == '') {
|
|
$this->prefDefault = '~~gray:None~~';
|
|
} elseif (! empty($param->units)) {
|
|
$this->prefDefault .= ' ' . $param->units;
|
|
} elseif (! preg_match('/\W/', $this->prefDefault)) { // if Pref is a singe word
|
|
$this->prefDefault = ucfirst($this->prefDefault); // then caps the first letter.
|
|
} else {
|
|
if (strlen($this->prefDefault) > 30) {
|
|
$this->prefDefaultFull = $this->wikiConvert($this->prefDefault, true);
|
|
$this->prefDefault = substr($this->prefDefault, 0, 27) . '...';
|
|
}
|
|
$this->prefDefault = $this->wikiConvert($this->prefDefault, true);
|
|
}
|
|
|
|
// set name
|
|
if ($param->help) {
|
|
$this->prefName = '<a href="' . $param->help . '">~np~' . $param->name . '~/np~</a>';
|
|
} else {
|
|
$this->prefName = '~np~' . $param->name . '~/np~';
|
|
}
|
|
$this->prefName = $this->wikiConvert($this->prefName);
|
|
|
|
// set description
|
|
$this->prefDescription = $param->description;
|
|
if ($param->detail) {
|
|
if ($this->prefDescription) { // new line if existing content
|
|
$this->prefDescription .= '<br>';
|
|
}
|
|
$this->prefDescription .= '<span class="fas fa-asterisk text-info" title="Detail"></span><i> ' . $param->detail . '</i>';
|
|
}
|
|
if ($param->hint) {
|
|
if ($this->prefDescription) { // new line if existing content
|
|
$this->prefDescription .= '<br>';
|
|
}
|
|
$this->prefDescription .= '<span class="far fa-hand-pointer text-info" title="Hint"></span><i> ' . $param->hint . '</i>';
|
|
}
|
|
if ($param->shorthint) {
|
|
if ($this->prefDescription) { // new line if existing content
|
|
$this->prefDescription .= '<br>';
|
|
}
|
|
$this->prefDescription .= '<span class="far fa-hand-pointer text-info" title="Short Hint"></span><i> ' . $param->shorthint . '</i>';
|
|
}
|
|
// if the pref is marked as deprecated, show as such and use the warning as the deprecated notice.
|
|
if (! empty($param->tags)) {
|
|
foreach ($param->tags as $tag) {
|
|
if ($tag === 'deprecated') {
|
|
if (! $param->warning) {
|
|
$param->warning = 'Will be removed in an upcoming version of Tiki.';
|
|
}
|
|
$this->prefDescription .= ' <span class="fas fa-broom text-warning" title="Deprecated: ' . $param->warning . '"></span>';
|
|
unset($param->warning);
|
|
}
|
|
}
|
|
}
|
|
|
|
if ($param->warning) {
|
|
if ($this->prefDescription) { // new line if existing content
|
|
$this->prefDescription .= '<br>';
|
|
}
|
|
$this->prefDescription .= '<span class="fas fa-exclamation-triangle text-warning" title="Warning"></span><i> ' . $param->warning . '</i>';
|
|
}
|
|
// display list of options
|
|
if (! empty($param->options)) {
|
|
$count = 0;
|
|
$options = '';
|
|
foreach ($param->options as $option) {
|
|
if ($count) {
|
|
$options .= ' | ';
|
|
}
|
|
$options .= $option;
|
|
$count++;
|
|
}
|
|
if ($count) { // If options exist, then add them
|
|
if ($this->prefDescription) { // new line if existing content
|
|
$this->prefDescription .= '<br>';
|
|
if (strlen($options) > 400) { // truncate options if they get too long
|
|
$options = substr($options, 0, 397) . '...';
|
|
}
|
|
}
|
|
$options = $this->wikiConvert($options, true); // sanitize special characters
|
|
$options = preg_replace('/\s+/', ' ', $options); // replace all excess whitespace characters with a single space.
|
|
$this->prefDescription .= '<span class="small text-muted"><span class="fas fa-list-ul" title="Options"></span> ' . $options . '</span>';
|
|
}
|
|
}
|
|
if (! empty($param->tags)) {
|
|
foreach ($param->tags as $tag) {
|
|
if ($tag === 'experimental') {
|
|
$this->prefDescription .= ' <span class="fas fa-flask text-danger" title="Experimental: may not work as intended"></span>';
|
|
}
|
|
}
|
|
}
|
|
$this->prefDescription = $this->wikiConvert($this->prefDescription);
|
|
}
|
|
|
|
/**
|
|
* Preps a string from tiki prefs for insertion into tiki-syntax land
|
|
*
|
|
* @param $string string to be parsed
|
|
*
|
|
* @param $escape bool if $string should be enclosed in tiki no-parse tags
|
|
*
|
|
*
|
|
* @return string parsed string sutable for wiki insertion
|
|
*
|
|
*/
|
|
private function wikiConvert($string, $escape = false)
|
|
{
|
|
$escapedString = '';
|
|
if ($string) {
|
|
if ($escape) {
|
|
$escapedString = ' ~np~';
|
|
}
|
|
$escapedString .= str_replace("\n", ' ', $string);
|
|
$escapedString = trim($escapedString);
|
|
if ($escape) {
|
|
$escapedString .= '~/np~';
|
|
}
|
|
}
|
|
|
|
return $escapedString;
|
|
}
|
|
|
|
/**
|
|
*
|
|
* Check if the prefs documentation is up to date.
|
|
* If its not up to date, then update it.
|
|
*
|
|
* Documentation is updated for every minor version change.
|
|
* A separate set of documentation is created for every major version.
|
|
* Only consecutive versions are supported (you cant skip a version)
|
|
*
|
|
* @return bool false on error, true on success.
|
|
*/
|
|
|
|
|
|
public function genPrefsState()
|
|
{
|
|
if ($this->state->version === $this->getBaseVersion()) {
|
|
return true;
|
|
}
|
|
|
|
if (! is_dir('storage/prefsdoc')) {
|
|
if (! mkdir('storage/prefsdoc')) { // create subdir for housing generated files, if it does not exist
|
|
$this->error .= "Cant create storage/prefsdoc directory.";
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// prepare to generate prefs doc
|
|
$this->fileCount = 0;
|
|
$this->prefCount = 0;
|
|
$this->getPrefs();
|
|
|
|
$docFiles = scandir('templates/admin'); // grab all the files that house prefs
|
|
foreach ($docFiles as $fileName) {
|
|
if (substr($fileName, 0, 8) === 'include_') { // filter out any file thats not a pref file
|
|
$FilePrefs = $this->getAdminUIPrefs($fileName);
|
|
foreach ($FilePrefs as $tabName => $tab) {
|
|
if (! $this->writeFile($tabName, $tab)) {
|
|
return false;
|
|
}
|
|
$this->prefCount++;
|
|
}
|
|
}
|
|
}
|
|
// record the state so its easy to figure out whats what next time.
|
|
$preState = (object)[];
|
|
$files = scandir('storage/prefsdoc/');
|
|
foreach ($files as $file) {
|
|
if (preg_match('/^([\d]+)-([a-z0-9-]+).json$/', $file, $matches)) { // return version number and tab name, filtering out non-matching files
|
|
$preState->{$matches[2]}[] = (int)$matches[1];
|
|
}
|
|
}
|
|
foreach ($preState as $key => $tabState) { // sort the versions from high to low
|
|
rsort($preState->$key);
|
|
}
|
|
|
|
$this->state = json_encode([
|
|
'version' => $this->getBaseVersion(),
|
|
'created' => time(),
|
|
'files' => $preState]);
|
|
file_put_contents('storage/prefsdoc/state.json', $this->state);
|
|
$this->state = json_decode($this->state);
|
|
|
|
$logslib = TikiLib::lib('logs');
|
|
$logslib->add_log('prefDoc', $this->fileCount . ' pref doc files generated/updated covering ' . $this->prefCount . ' prefs');
|
|
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* compiles a all prefs for the current tiki install and sets PrefVars with it
|
|
*/
|
|
private function getPrefs()
|
|
{
|
|
|
|
$prefs = [];
|
|
$docFiles = scandir('lib/prefs'); // grab all the files that house prefs
|
|
foreach ($docFiles as $fileName) {
|
|
if ($fileName !== 'index.php' && substr($fileName, -4) === '.php') { // filter out any file thats not a pref file
|
|
require_once('lib/prefs/' . $fileName);
|
|
$callVar = 'prefs_' . substr($fileName, 0, -4) . '_list';
|
|
$prefs = array_merge($prefs, $callVar()); // create one big var with all the pref info
|
|
}
|
|
}
|
|
// Sanitise specific output
|
|
$prefs['webcron_token']['default'] = 'Random Token';
|
|
|
|
$this->PrefVars = $prefs;
|
|
}
|
|
|
|
/**
|
|
*
|
|
* This generates a list of prefs in the order that they appear on the admin panel.
|
|
*
|
|
* @param string $fileName Name of file to scan
|
|
*
|
|
* @return array array of pref names, or false on failure
|
|
*
|
|
*/
|
|
private function getAdminUIPrefs($fileName)
|
|
{
|
|
$file = file_get_contents('templates/admin/' . $fileName);
|
|
$fileName = substr(substr($fileName, 8), 0, -4); // prepare the file name for further use
|
|
$count = preg_match_all('/{tab name="?\'?(?:{tr})?([\w\s]*)(?:{\/tr})?"?\'?.*?}([\w\W]*?){\/tab}/i', $file, $tabs);
|
|
if ($count) {
|
|
while ($count >= 1) {
|
|
$count--;
|
|
$prefs = [];
|
|
preg_match_all('/{preference.*name="?\'?(\w*)"?\'?.*}/i', $tabs[2][$count], $prefs); // Generate array of all the prefs
|
|
$tabs[1][$count] = mb_ereg_replace('\W', '', strtolower($tabs[1][$count])); // sanitize the tab name for disk
|
|
foreach ($prefs[1] as $pref) {
|
|
if ($this->PrefVars[$pref]['name']) { // dont save prefs that have no name
|
|
$tabPrefs[$fileName . '-' . $tabs[1][$count]][$pref] = $this->PrefVars[$pref]; // Add full pref info in right order
|
|
}
|
|
}
|
|
}
|
|
} elseif (preg_match_all('/{preference.*name="?\'?(\w*)"?\'?.*}/i', $file, $prefs)) {
|
|
foreach ($prefs[1] as $pref) {
|
|
$tabPrefs[$fileName][$pref] = $this->PrefVars[$pref]; // Add full pref info in right order
|
|
}
|
|
}
|
|
|
|
return $tabPrefs;
|
|
}
|
|
|
|
/**
|
|
*
|
|
* Writes a pref file to disk
|
|
*
|
|
* @param $tabName string name of tab or pref file to write
|
|
* @param $prefs array the prefs to write to file
|
|
*
|
|
* @return bool|string returns error message on failure, or false on success
|
|
*/
|
|
|
|
|
|
private function writeFile($tabName, $prefs)
|
|
{
|
|
$version = (int)$this->getBaseVersion();
|
|
|
|
$tabName = '-' . $tabName . '.json'; // Name of file to be written, minus prefex
|
|
|
|
$prefs = json_encode([
|
|
'prefs' => $prefs,
|
|
]);
|
|
|
|
if (is_file('storage/prefsdoc/' . $version . $tabName)) {
|
|
if (! unlink('storage/prefsdoc/' . $version . $tabName)) {
|
|
$this->error .= ("Cant overwrite existing $version-$tabName.json ");
|
|
|
|
return false;
|
|
}
|
|
}
|
|
|
|
if (! file_put_contents('storage/prefsdoc/' . $version . $tabName, $prefs)) {
|
|
// write one file for each pref page on control panel
|
|
$this->error .= ("Unable to write $version.$tabName");
|
|
return false;
|
|
}
|
|
$this->fileCount++;
|
|
return true;
|
|
}
|
|
}
|