1158 lines
35 KiB
PHP
1158 lines
35 KiB
PHP
<?php namespace ProcessWire;
|
||
|
||
/**
|
||
* ProcessWire Templates
|
||
*
|
||
* Manages and provides access to all the Template instances
|
||
*
|
||
* ProcessWire 3.x, Copyright 2022 by Ryan Cramer
|
||
* https://processwire.com
|
||
*
|
||
* #pw-summary Manages and provides access to all the Templates.
|
||
*
|
||
* @method TemplatesArray find($selector) Return the templates matching the the given selector query. #pw-internal
|
||
* @method bool save(Template $template) Save the given Template.
|
||
* @method bool delete() delete(Template $template) Delete the given Template. Note that this will throw a fatal error if the template is in use by any pages.
|
||
* @method bool|Saveable|Template clone(Saveable $item, $name = '') #pw-internal
|
||
* @method array getExportData(Template $template) Export Template data for external use. #pw-advanced
|
||
* @method array setImportData(Template $template, array $data) Given an array of Template export data, import it to the given Template. #pw-advanced
|
||
* @method void fileModified(Template $template) Hook called when a template detects that its file has been modified. #pw-hooker
|
||
* @method array getTags($getTemplateNames = false) Get tags for all templates (3.0.179+) #pw-advanced
|
||
*
|
||
*/
|
||
class Templates extends WireSaveableItems {
|
||
|
||
/**
|
||
* Reference to all the Fieldgroups
|
||
*
|
||
* @var Fieldgroups
|
||
*
|
||
*/
|
||
protected $fieldgroups = null;
|
||
|
||
/**
|
||
* WireArray of all Template instances
|
||
*
|
||
* @var TemplatesArray
|
||
*
|
||
*/
|
||
protected $templatesArray = null;
|
||
|
||
/**
|
||
* Templates that had changed files during this request
|
||
*
|
||
* @var array Array of Template objects indexed by id
|
||
*
|
||
*/
|
||
protected $fileModTemplates = array();
|
||
|
||
/**
|
||
* Cached template ID to page class names (for getPageClass method)
|
||
*
|
||
* @var array
|
||
*
|
||
*/
|
||
protected $pageClassNames = array();
|
||
|
||
/**
|
||
* Construct the Templates
|
||
*
|
||
* @param Fieldgroups $fieldgroups Reference to the Fieldgroups
|
||
*
|
||
*/
|
||
public function __construct(Fieldgroups $fieldgroups) {
|
||
parent::__construct();
|
||
$fieldgroups->wire($this);
|
||
$this->fieldgroups = $fieldgroups;
|
||
}
|
||
|
||
/**
|
||
* Initialize the TemplatesArray and populate
|
||
*
|
||
* #pw-internal
|
||
*
|
||
*/
|
||
public function init() {
|
||
$this->getWireArray();
|
||
}
|
||
|
||
/**
|
||
* Return the WireArray that this DAO stores it's items in
|
||
*
|
||
* #pw-internal
|
||
*
|
||
*/
|
||
public function getAll() {
|
||
if($this->useLazy()) $this->loadAllLazyItems();
|
||
return $this->getWireArray();
|
||
}
|
||
|
||
/**
|
||
* Get WireArray container that items are stored in
|
||
*
|
||
* #pw-internal
|
||
*
|
||
* @return WireArray|TemplatesArray
|
||
* @since 3.0.194
|
||
*
|
||
*/
|
||
public function getWireArray() {
|
||
if($this->templatesArray === null) {
|
||
$this->templatesArray = $this->wire(new TemplatesArray());
|
||
$this->load($this->templatesArray);
|
||
}
|
||
return $this->templatesArray;
|
||
}
|
||
|
||
/**
|
||
* Make an item and populate with given data
|
||
*
|
||
* #pw-internal
|
||
*
|
||
* @param array $a Associative array of data to populate
|
||
* @return Saveable|Wire|Template
|
||
* @since 3.0.146
|
||
*
|
||
*/
|
||
public function makeItem(array $a = array()) {
|
||
|
||
/** @var Template $template */
|
||
$template = $this->wire(new Template());
|
||
$template->loaded(false);
|
||
|
||
if(!empty($a['data'])) {
|
||
if(is_string($a['data'])) $a['data'] = $this->decodeData($a['data']);
|
||
} else {
|
||
unset($a['data']);
|
||
}
|
||
|
||
foreach(array('id', 'name', 'fieldgroups_id', 'flags', 'cache_time') as $key) {
|
||
if(!isset($a[$key])) continue;
|
||
$value = $key === 'name' ? $a[$key] : (int) $a[$key];
|
||
$template->setRaw($key, $value);
|
||
unset($a[$key]);
|
||
}
|
||
|
||
foreach($a as $key => $value) {
|
||
$template->set($key, $value);
|
||
}
|
||
|
||
$template->loaded(true);
|
||
$template->resetTrackChanges(true);
|
||
|
||
return $template;
|
||
}
|
||
|
||
/**
|
||
* Load all lazy items
|
||
*
|
||
* #pw-internal
|
||
*
|
||
* @since 3.0.194
|
||
*
|
||
*/
|
||
public function loadAllLazyItems() {
|
||
if(!$this->useLazy()) return;
|
||
$this->wire()->fieldgroups->loadAllLazyItems();
|
||
parent::loadAllLazyItems();
|
||
}
|
||
|
||
/**
|
||
* Return a new blank item
|
||
*
|
||
* @return Template
|
||
*
|
||
* #pw-internal
|
||
*
|
||
*/
|
||
public function makeBlankItem() {
|
||
return $this->wire(new Template());
|
||
}
|
||
|
||
/**
|
||
* Return the name of the table that this DAO stores item records in
|
||
*
|
||
* #pw-internal
|
||
*
|
||
*/
|
||
public function getTable() {
|
||
return 'templates';
|
||
}
|
||
|
||
/**
|
||
* Return the field name that fields should initially be sorted by
|
||
*
|
||
* #pw-internal
|
||
*
|
||
*/
|
||
public function getSort() {
|
||
return $this->getTable() . ".name";
|
||
}
|
||
|
||
/**
|
||
* Add and save new template (and fieldgroup) with given name and return it
|
||
*
|
||
* @param string $name
|
||
* @param array $properties Any additional properties to add to template
|
||
* @return Template
|
||
* @throws WireException if given invalid template name or template already exists
|
||
* @since 3.0.170
|
||
*
|
||
*/
|
||
public function add($name, array $properties = array()) {
|
||
|
||
if(!is_string($name)) {
|
||
throw new WireException("You must specify the template name to add");
|
||
}
|
||
|
||
$saniName = $this->wire()->sanitizer->templateName($name);
|
||
|
||
if(empty($saniName)) {
|
||
throw new WireException("Invalid template name: $name");
|
||
}
|
||
|
||
$name = $saniName;
|
||
$template = $this->get($name);
|
||
|
||
if($template) {
|
||
throw new WireException("Template '$name' cannot be added because it already exists");
|
||
}
|
||
|
||
$fieldgroups = $this->wire()->fieldgroups;
|
||
$fieldgroup = $fieldgroups->get($name);
|
||
|
||
if(!$fieldgroup) {
|
||
$fieldgroup = new Fieldgroup();
|
||
$this->wire($fieldgroup);
|
||
$fieldgroup->name = $name;
|
||
$fieldgroups->save($fieldgroup);
|
||
}
|
||
|
||
$template = new Template();
|
||
$this->wire($template);
|
||
$template->name = $name;
|
||
$template->fieldgroup = $fieldgroup;
|
||
foreach($properties as $key => $value) $template->set($key, $value);
|
||
$this->save($template);
|
||
|
||
return $template;
|
||
}
|
||
|
||
/**
|
||
* Get a template by name or ID
|
||
*
|
||
* Given a template ID or name, return the matching template or NULL if not found.
|
||
*
|
||
* @param string|int $key Template name or ID
|
||
* @return Template|null|string
|
||
*
|
||
*/
|
||
public function get($key) {
|
||
if($key === 'path') return $this->wire()->config->paths->templates;
|
||
return parent::get($key);
|
||
}
|
||
|
||
/**
|
||
* Save a Template
|
||
*
|
||
* ~~~~~
|
||
* $templates->save($template);
|
||
* ~~~~~
|
||
*
|
||
* @param Saveable|Template $item Template to save
|
||
* @return bool True on success, false on failure
|
||
* @throws WireException
|
||
*
|
||
*/
|
||
public function ___save(Saveable $item) {
|
||
|
||
// If the template's fieldgroup has changed, then we delete data that's no longer applicable to the new fieldgroup.
|
||
|
||
$isNew = $item->id < 1;
|
||
|
||
if(!$item->fieldgroup) {
|
||
throw new WireException("Template '$item' cannot be saved because it has no fieldgroup assigned");
|
||
}
|
||
if(!$item->fieldgroup->id) {
|
||
throw new WireException("You must save Fieldgroup '{$item->fieldgroup->name}' before adding to Template '$item'");
|
||
}
|
||
|
||
$rolesChanged = $item->isChanged('useRoles');
|
||
|
||
if($this->wire()->pages->get('/')->template->id == $item->id) {
|
||
if(!$item->useRoles) {
|
||
throw new WireException("Template '$item' is used by the homepage and thus must manage access");
|
||
}
|
||
if(!$item->hasRole('guest')) {
|
||
throw new WireException("Template '$item' is used by the homepage and thus must have the 'guest' role assigned.");
|
||
}
|
||
}
|
||
|
||
if(!$item->isChanged('modified')) $item->modified = time();
|
||
|
||
$result = parent::___save($item);
|
||
|
||
if($result && !$isNew && $item->fieldgroupPrevious && $item->fieldgroupPrevious->id != $item->fieldgroup->id) {
|
||
// the fieldgroup has been changed
|
||
// remove data from all fields that are not part of the new fieldgroup
|
||
/** @var FieldsArray $removeFields */
|
||
$removeFields = $this->wire(new FieldsArray());
|
||
foreach($item->fieldgroupPrevious as $field) {
|
||
if(!$item->fieldgroup->has($field)) {
|
||
$removeFields->add($field);
|
||
}
|
||
}
|
||
if(count($removeFields)) {
|
||
foreach($removeFields as $field) {
|
||
/** @var Field $field */
|
||
$field->type->deleteTemplateField($item, $field);
|
||
}
|
||
/*
|
||
$pages = $this->fuel('pages')->find("templates_id={$item->id}, check_access=0, status<" . Page::statusMax);
|
||
foreach($pages as $page) {
|
||
foreach($removeFields as $field) {
|
||
$field->type->deletePageField($page, $field);
|
||
if($this->fuel('config')->debug) $this->message("Removed field '$field' on page '{$page->url}'");
|
||
}
|
||
}
|
||
*/
|
||
}
|
||
}
|
||
|
||
if($rolesChanged) {
|
||
/** @var PagesAccess $access */
|
||
$access = $this->wire(new PagesAccess());
|
||
$access->updateTemplate($item);
|
||
}
|
||
|
||
$cache = $this->wire()->cache;
|
||
$cache->maintenance($item);
|
||
|
||
return $result;
|
||
}
|
||
|
||
/**
|
||
* Delete a Template
|
||
*
|
||
* @param Template|Saveable $item Template to delete
|
||
* @return bool True on success, false on failure
|
||
* @throws WireException Thrown when you attempt to delete a template in use, or a system template.
|
||
*
|
||
*/
|
||
public function ___delete(Saveable $item) {
|
||
|
||
$name = $item->name;
|
||
$id = $item->id;
|
||
|
||
if($item->flags & Template::flagSystem) {
|
||
throw new WireException("Can't delete template '$name' because it is a system template.");
|
||
}
|
||
|
||
$cnt = $item->getNumPages();
|
||
|
||
if($cnt > 0) {
|
||
throw new WireException("Can't delete template '$name' because it is used by $cnt pages.");
|
||
}
|
||
|
||
$return = parent::___delete($item);
|
||
|
||
if($return) {
|
||
$fieldgroups = $this->wire()->fieldgroups;
|
||
$fieldgroup = $fieldgroups->get($name);
|
||
if($fieldgroup) {
|
||
// also delete fieldgroup, if not used by any other templates
|
||
$cnt = 0;
|
||
foreach($this as $t) {
|
||
/** @var Template $t */
|
||
if($t->id != $id && $t->fieldgroup->id == $fieldgroup->id) $cnt++;
|
||
}
|
||
if(!$cnt) $fieldgroups->delete($fieldgroup);
|
||
}
|
||
}
|
||
|
||
$cache = $this->wire()->cache;
|
||
$cache->maintenance($item);
|
||
|
||
return $return;
|
||
}
|
||
|
||
/**
|
||
* Clone the given Template
|
||
*
|
||
* Note that this also clones the Fieldgroup if the template being cloned has its own named fieldgroup.
|
||
*
|
||
* @todo: clone the fieldgroup context settings too.
|
||
*
|
||
* @param Template|Saveable $item Template to clone
|
||
* @param string $name Name of new template that will be created, or omit to auto-assign.
|
||
* @return bool|Template $item Returns the new Template on success, or false on failure
|
||
*
|
||
*/
|
||
public function ___clone(Saveable $item, $name = '') {
|
||
|
||
$original = $item;
|
||
/** @var Template $item */
|
||
$item = clone $item;
|
||
|
||
if($item->flags & Template::flagSystem) {
|
||
// we want to avoid creating clones that have system flags
|
||
$item->flags = $item->flags | Template::flagSystemOverride;
|
||
$item->flags = $item->flags & ~Template::flagSystem;
|
||
$item->flags = $item->flags & ~Template::flagSystemOverride;
|
||
}
|
||
|
||
$item->id = 0; // note this must be after removing system flags
|
||
|
||
$fieldgroup = $item->fieldgroup;
|
||
|
||
if($fieldgroup->name == $item->name) {
|
||
// if the fieldgroup and the item have the same name, we'll also clone the fieldgroup
|
||
$fieldgroup = $this->wire()->fieldgroups->clone($fieldgroup, $name);
|
||
$item->fieldgroup = $fieldgroup;
|
||
}
|
||
|
||
/** @var Template|bool $item */
|
||
$item = parent::___clone($item, $name);
|
||
|
||
if($item && $item->id && !$item->altFilename) {
|
||
// now that we have a clone, lets also clone the template file, if it exists
|
||
$config = $this->wire()->config;
|
||
$files = $this->wire()->files;
|
||
$path = $config->paths->templates;
|
||
$ext = $config->templateExtension ? $config->templateExtension : 'php';
|
||
$file = "$path$item->name.$ext";
|
||
if($original->filenameExists() && is_writable($path) && !$files->exists($file)) {
|
||
if($files->copy($original->filename, $file)) $item->filename = $file;
|
||
}
|
||
}
|
||
|
||
return $item;
|
||
}
|
||
|
||
/**
|
||
* Rename given template (and its fieldgroup, and file, when possible)
|
||
*
|
||
* Given template must have its previous 'name' still present, and new name provided in $name
|
||
* argument to this method.
|
||
*
|
||
* @param Template $template
|
||
* @param string $name New name to use
|
||
* @since 3.0.170
|
||
* @throws WireException if rename cannot be completed
|
||
*
|
||
*/
|
||
public function rename(Template $template, $name) {
|
||
|
||
$config = $this->wire()->config;
|
||
$saniName = $this->wire()->sanitizer->templateName($name);
|
||
|
||
if(empty($saniName)) throw new WireException("Invalid template name: $name");
|
||
|
||
$name = $saniName;
|
||
$basename = "$template->name.$config->templateExtension";
|
||
$filename = $template->filenameExists() ? $template->filename() : '';
|
||
$fieldgroup = $template->fieldgroup;
|
||
$t = $this->get($name);
|
||
|
||
if($t instanceof Template && $t->id != $template->id) {
|
||
throw new WireException("Template '$name' already exists");
|
||
}
|
||
|
||
if($fieldgroup->name === $template->name) {
|
||
// rename fieldgroup too
|
||
$fg = $this->wire()->fieldgroups->get($name);
|
||
if($fg && $fg->id != $fieldgroup->id) throw new WireException("Fieldgroup '$name' already exists");
|
||
$fieldgroup->name = $name;
|
||
$this->wire()->fieldgroups->save($fieldgroup);
|
||
}
|
||
|
||
$template->name = $name;
|
||
$this->save($template);
|
||
|
||
if($filename && basename($filename) === $basename) {
|
||
$newFilename = $config->paths->templates . $name . $config->templateExtension;
|
||
if(is_readable($filename) && is_writable($filename) && !file_exists($newFilename)) {
|
||
// rename file
|
||
$this->wire()->files->rename($filename, $newFilename);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Return the number of pages using the provided Template
|
||
*
|
||
* @param Template $tpl Template you want to get count for
|
||
* @return int Total number of pages in use by given Template
|
||
*
|
||
*/
|
||
public function getNumPages(Template $tpl) {
|
||
$database = $this->wire()->database;
|
||
$query = $database->prepare("SELECT COUNT(*) AS total FROM pages WHERE templates_id=:template_id"); // QA
|
||
$query->bindValue(":template_id", $tpl->id, \PDO::PARAM_INT);
|
||
$query->execute();
|
||
return (int) $query->fetchColumn();
|
||
}
|
||
|
||
/**
|
||
* Overridden from WireSaveableItems to retain specific keys
|
||
*
|
||
* @param array $value
|
||
* @return string
|
||
*
|
||
*/
|
||
protected function encodeData(array $value) {
|
||
return wireEncodeJSON($value, array('slashUrls', 'compile'));
|
||
}
|
||
|
||
/**
|
||
* Export Template data for external use
|
||
*
|
||
* #pw-advanced
|
||
*
|
||
* @param Template $template Template you want to export
|
||
* @return array Associative array of export data
|
||
*
|
||
*/
|
||
public function ___getExportData(Template $template) {
|
||
|
||
$template->set('_exportMode', true);
|
||
$data = $template->getTableData();
|
||
|
||
// flatten
|
||
foreach($data['data'] as $key => $value) {
|
||
$data[$key] = $value;
|
||
}
|
||
|
||
// remove unnecessary
|
||
unset($data['data'], $data['modified']);
|
||
|
||
// convert fieldgroup to guid
|
||
$fieldgroup = $this->wire()->fieldgroups->get((int) $data['fieldgroups_id']);
|
||
if($fieldgroup) $data['fieldgroups_id'] = $fieldgroup->name;
|
||
|
||
// convert family settings to guids
|
||
foreach(array('parentTemplates', 'childTemplates') as $key) {
|
||
if(!isset($data[$key])) continue;
|
||
$values = array();
|
||
foreach($data[$key] as $id) {
|
||
if(ctype_digit("$id")) $id = (int) $id;
|
||
$t = $this->get($id);
|
||
if($t) $values[] = $t->name;
|
||
}
|
||
$data[$key] = $values;
|
||
}
|
||
|
||
// convert roles to guids
|
||
if($template->useRoles) {
|
||
$roles = $this->wire()->roles;
|
||
foreach(array('roles', 'editRoles', 'addRoles', 'createRoles') as $key) {
|
||
if(!isset($data[$key])) continue;
|
||
$values = array();
|
||
foreach($data[$key] as $id) {
|
||
$role = $id instanceof Role ? $id : $roles->get((int) $id);
|
||
$values[] = $role->name;
|
||
}
|
||
$data[$key] = $values;
|
||
}
|
||
}
|
||
|
||
// convert pages to guids
|
||
if(((int) $template->cache_time) != 0) {
|
||
if(!empty($data['cacheExpirePages'])) {
|
||
$pages = $this->wire()->pages;
|
||
$values = array();
|
||
foreach($data['cacheExpirePages'] as $id) {
|
||
$page = $pages->get((int) $id);
|
||
if(!$page->id) continue;
|
||
$values[] = $page->path;
|
||
}
|
||
}
|
||
}
|
||
|
||
$fieldgroupData = array('fields' => array(), 'contexts' => array());
|
||
if($template->fieldgroup) $fieldgroupData = $template->fieldgroup->getExportData();
|
||
$data['fieldgroupFields'] = $fieldgroupData['fields'];
|
||
$data['fieldgroupContexts'] = $fieldgroupData['contexts'];
|
||
unset($data['_lazy'], $data['_exportMode']);
|
||
|
||
$template->set('_exportMode', false);
|
||
return $data;
|
||
}
|
||
|
||
/**
|
||
* Given an array of Template export data, import it to the given Template
|
||
*
|
||
* ~~~~~~
|
||
* // Example of return value
|
||
* $returnValue = array(
|
||
* 'property_name' => array(
|
||
* 'old' => 'old value', // old value (in string comparison format)
|
||
* 'new' => 'new value', // new value (in string comparison format)
|
||
* 'error' => 'error message or blank if no error' // error message (string) or messages (array)
|
||
* ),
|
||
* 'another_property_name' => array(
|
||
* // ...
|
||
* )
|
||
* );
|
||
* ~~~~~~
|
||
*
|
||
* #pw-advanced
|
||
*
|
||
* @param Template $template Template you want to import to
|
||
* @param array $data Import data array (must have been exported from getExportData() method).
|
||
* @return array Returns array with list of changes (see example in method description)
|
||
*
|
||
*/
|
||
public function ___setImportData(Template $template, array $data) {
|
||
|
||
$fieldgroups = $this->wire()->fieldgroups;
|
||
|
||
$template->set('_importMode', true);
|
||
$fieldgroupData = array();
|
||
$changes = array();
|
||
$_data = $this->getExportData($template);
|
||
|
||
if(isset($data['fieldgroupFields'])) $fieldgroupData['fields'] = $data['fieldgroupFields'];
|
||
if(isset($data['fieldgroupContexts'])) $fieldgroupData['contexts'] = $data['fieldgroupContexts'];
|
||
unset($data['fieldgroupFields'], $data['fieldgroupContexts'], $data['id']);
|
||
|
||
foreach($data as $key => $value) {
|
||
if($key == 'fieldgroups_id' && !ctype_digit("$value")) {
|
||
$fieldgroup = $fieldgroups->get($value);
|
||
if(!$fieldgroup) {
|
||
/** @var Fieldgroup $fieldgroup */
|
||
$fieldgroup = $this->wire(new Fieldgroup());
|
||
$fieldgroup->name = $value;
|
||
}
|
||
$oldValue = $template->fieldgroup ? $template->fieldgroup->name : '';
|
||
$newValue = $fieldgroup->name;
|
||
$error = '';
|
||
try {
|
||
$template->setFieldgroup($fieldgroup);
|
||
} catch(\Exception $e) {
|
||
$this->trackException($e, false);
|
||
$error = $e->getMessage();
|
||
}
|
||
if($oldValue != $fieldgroup->name) {
|
||
if(!$fieldgroup->id) $newValue = "+$newValue";
|
||
$changes['fieldgroups_id'] = array(
|
||
'old' => $template->fieldgroup->name,
|
||
'new' => $newValue,
|
||
'error' => $error
|
||
);
|
||
}
|
||
}
|
||
|
||
$template->errors("clear");
|
||
$oldValue = isset($_data[$key]) ? $_data[$key] : '';
|
||
$newValue = $value;
|
||
if(is_array($oldValue)) $oldValue = wireEncodeJSON($oldValue, true, false);
|
||
else if(is_object($oldValue)) $oldValue = (string) $oldValue;
|
||
if(is_array($newValue)) $newValue = wireEncodeJSON($newValue, true, false);
|
||
else if(is_object($newValue)) $newValue = (string) $newValue;
|
||
|
||
// everything else
|
||
if($oldValue == $newValue || (empty($oldValue) && empty($newValue))) {
|
||
// no change needed
|
||
} else {
|
||
// changed
|
||
try {
|
||
$template->set($key, $value);
|
||
if($key == 'roles') $template->getRoles(); // forces reload of roles (and resulting error messages)
|
||
$error = $template->errors('clear');
|
||
} catch(\Exception $e) {
|
||
$this->trackException($e, false);
|
||
$error = array($e->getMessage());
|
||
}
|
||
$changes[$key] = array(
|
||
'old' => $oldValue,
|
||
'new' => $newValue,
|
||
'error' => (count($error) ? $error : array())
|
||
);
|
||
}
|
||
}
|
||
|
||
if(count($fieldgroupData)) {
|
||
$_changes = $template->fieldgroup->setImportData($fieldgroupData);
|
||
if($_changes['fields']['new'] != $_changes['fields']['old']) {
|
||
$changes['fieldgroupFields'] = $_changes['fields'];
|
||
}
|
||
if($_changes['contexts']['new'] != $_changes['contexts']['old']) {
|
||
$changes['fieldgroupContexts'] = $_changes['contexts'];
|
||
}
|
||
}
|
||
|
||
$template->errors('clear');
|
||
$template->set('_importMode', false);
|
||
|
||
return $changes;
|
||
}
|
||
|
||
/**
|
||
* Return the parent page that this template assumes new pages are added to
|
||
*
|
||
* - This is based on family settings, when applicable.
|
||
* - It also takes into account user access, if requested (see arg 1).
|
||
* - If there is no shortcut parent, NULL is returned.
|
||
* - If there are multiple possible shortcut parents, a NullPage is returned.
|
||
*
|
||
* @param Template $template
|
||
* @param bool $checkAccess Whether or not to check for user access to do this (default=false).
|
||
* @param bool|int $getAll Specify true to return all possible parents (makes method always return a PageArray)
|
||
* Or specify int of maximum allowed `Page::status*` constant for items in returned PageArray (since 3.0.138).
|
||
* @return Page|NullPage|null|PageArray
|
||
*
|
||
*/
|
||
public function getParentPage(Template $template, $checkAccess = false, $getAll = false) {
|
||
|
||
$pages = $this->wire()->pages;
|
||
$user = $this->wire()->user;
|
||
|
||
$foundParent = null;
|
||
$foundParents = $getAll ? $pages->newPageArray() : null;
|
||
$foundParentQty = 0;
|
||
$maxStatus = is_int($getAll) && $getAll ? ($getAll * 2) : 0;
|
||
|
||
if($template->noShortcut || !count($template->parentTemplates)) return $foundParents;
|
||
if($template->noParents == -1) {
|
||
// only 1 page of this type allowed
|
||
if($this->getNumPages($template) > 0) return $foundParents;
|
||
} else if($template->noParents == 1) {
|
||
return $foundParents;
|
||
}
|
||
|
||
foreach($template->parentTemplates as $parentTemplateID) {
|
||
|
||
$parentTemplate = $this->get((int) $parentTemplateID);
|
||
if(!$parentTemplate) continue;
|
||
|
||
// if the parent template doesn't have this as an allowed child template, exclude it
|
||
if($parentTemplate->noChildren) continue;
|
||
if(!in_array($template->id, $parentTemplate->childTemplates)) continue;
|
||
|
||
// sort=status ensures that a non-hidden page is given preference to a hidden page
|
||
$include = $checkAccess ? "unpublished" : "all";
|
||
$selector = "templates_id=$parentTemplate->id, include=$include, sort=status";
|
||
if($maxStatus) {
|
||
$selector .= ", status<$maxStatus";
|
||
} else if(!$getAll) {
|
||
$selector .= ", limit=2";
|
||
}
|
||
$parentPages = $pages->find($selector);
|
||
$numParentPages = count($parentPages);
|
||
|
||
// undetermined parent
|
||
if(!$numParentPages) continue;
|
||
|
||
if($getAll) {
|
||
// build list of all parents (will check access outside loop)
|
||
$foundParents->add($parentPages);
|
||
continue;
|
||
} else if($numParentPages > 1) {
|
||
// multiple possible parents, we can early-exit
|
||
$foundParentQty += $numParentPages;
|
||
break;
|
||
} else {
|
||
// one possible parent
|
||
$parentPage = $parentPages->first();
|
||
}
|
||
|
||
if($checkAccess) {
|
||
if($parentPage->id) {
|
||
// single defined parent
|
||
$p = $pages->newPage($template);
|
||
if(!$parentPage->addable($p)) continue;
|
||
} else {
|
||
// multiple possible parents
|
||
if(!$user->hasPermission('page-create', $template)) continue;
|
||
}
|
||
}
|
||
|
||
if($parentPage && $parentPage->id) $foundParentQty++;
|
||
$foundParent = $parentPage;
|
||
if($foundParentQty > 1) break;
|
||
}
|
||
|
||
if($checkAccess && $getAll && $foundParents && $foundParents->count()) {
|
||
$p = $pages->newPage($template);
|
||
foreach($foundParents as $parentPage) {
|
||
if(!$parentPage->addable($p)) $foundParents->remove($parentPage);
|
||
}
|
||
}
|
||
|
||
if($getAll) return $foundParents;
|
||
if($foundParentQty > 1) return $pages->newNullPage();
|
||
|
||
return $foundParent;
|
||
}
|
||
|
||
/**
|
||
* Return all possible parent pages for the given template, if predefined
|
||
*
|
||
* @param Template $template
|
||
* @param bool $checkAccess Specify true to exclude parent pages that user doesn't have access to add pages to (default=false)
|
||
* @param int $maxStatus Max allowed `Page::status*` constant (default=0 which means not applicable). Since 3.0.138
|
||
* @return PageArray
|
||
*
|
||
*/
|
||
public function getParentPages(Template $template, $checkAccess = false, $maxStatus = 0) {
|
||
$getAll = $maxStatus ? $maxStatus : true;
|
||
return $this->getParentPage($template, $checkAccess, $getAll);
|
||
}
|
||
|
||
/**
|
||
* Get class name to use for pages using given Template
|
||
*
|
||
* Note that value can be different from the `$template->pageClass` property, since it is determined at runtime.
|
||
* If it is different, then it is at least a class that extends the one defined by pageClass.
|
||
*
|
||
* @param Template $template
|
||
* @param bool $withNamespace Include namespace? (default=true)
|
||
* @return string Returned class name includes namespace
|
||
* @since 3.0.152
|
||
*
|
||
*/
|
||
public function getPageClass(Template $template, $withNamespace = true) {
|
||
|
||
if(isset($this->pageClassNames[$template->id])) {
|
||
// use cached value when present
|
||
$pageClass = $this->pageClassNames[$template->id];
|
||
if(!$withNamespace) $pageClass = wireClassName($pageClass, false);
|
||
return $pageClass;
|
||
}
|
||
|
||
$corePageClass = __NAMESPACE__ . "\\Page";
|
||
$cacheable = true;
|
||
|
||
// first check for class defined with Template 'pageClass' setting
|
||
$pageClass = $template->pageClass;
|
||
|
||
if($pageClass && $pageClass !== 'Page') {
|
||
// page has custom class assignment in its template
|
||
$nsPageClass = wireClassName($pageClass, true);
|
||
// is this custom class available for instantiation?
|
||
if(class_exists($nsPageClass)) {
|
||
// class is available for use and has a namespace
|
||
$pageClass = $nsPageClass;
|
||
} else if(class_exists("\\$pageClass") && wireInstanceOf("\\$pageClass", $corePageClass)) {
|
||
// class appears to be available in root namespace and it extends PW’s Page class (legacy)
|
||
$pageClass = "\\$pageClass";
|
||
} else {
|
||
// class is not available for instantiation
|
||
$this->warning(
|
||
"Template '$template' page class '$pageClass' is not available",
|
||
Notice::debug | Notice::superuser | Notice::admin
|
||
);
|
||
$pageClass = '';
|
||
// do not cache because maybe class will be available later
|
||
$cacheable = false;
|
||
}
|
||
}
|
||
|
||
$config = $this->wire()->config;
|
||
$usePageClasses = $config->usePageClasses;
|
||
|
||
if(empty($pageClass) || $pageClass === 'Page') {
|
||
// if no custom Page class available, use default Page class with namespace
|
||
if($usePageClasses) {
|
||
// custom classes enabled
|
||
if(!isset($this->pageClassNames[0])) {
|
||
// index 0 holds cached default page class
|
||
$defaultPageClass = __NAMESPACE__ . "\\DefaultPage";
|
||
if(!class_exists($defaultPageClass) || !wireInstanceOf($defaultPageClass, $corePageClass)) {
|
||
$defaultPageClass = $corePageClass;
|
||
}
|
||
$this->pageClassNames[0] = $defaultPageClass;
|
||
}
|
||
$pageClass = $this->pageClassNames[0];
|
||
} else {
|
||
$pageClass = $corePageClass;
|
||
}
|
||
}
|
||
|
||
// determine if custom class available (3.0.152+)
|
||
if($usePageClasses) {
|
||
// generate a CamelCase name + 'Page' from template name, i.e. 'blog-post' => 'BlogPostPage'
|
||
$className = ucwords(str_replace(array('-', '_', '.'), ' ', $template->name));
|
||
$className = __NAMESPACE__ . "\\" . str_replace(' ', '', $className) . 'Page';
|
||
if(class_exists($className) && wireInstanceOf($className, $corePageClass)) {
|
||
$pageClass = $className;
|
||
}
|
||
}
|
||
|
||
if($cacheable && $template->id) $this->pageClassNames[$template->id] = $pageClass;
|
||
|
||
if(!$withNamespace) $pageClass = wireClassName($pageClass, false);
|
||
|
||
return $pageClass;
|
||
}
|
||
|
||
/**
|
||
* Get all tags used by templates
|
||
*
|
||
* @param bool $getTemplateNames Get arrays of template names for each tag? (default=false)
|
||
* @return array In return value both key and value are the tag
|
||
* @since 3.0.176 + hookable in 3.0.179
|
||
*
|
||
*/
|
||
public function ___getTags($getTemplateNames = false) {
|
||
$tags = array();
|
||
foreach($this as $template) {
|
||
/** @var Template $template */
|
||
$templateTags = $template->tags;
|
||
if(empty($templateTags)) continue;
|
||
$templateTags = explode(' ', $templateTags);
|
||
foreach($templateTags as $tag) {
|
||
if(empty($tag)) continue;
|
||
if($getTemplateNames) {
|
||
if(!isset($tags[$tag])) $tags[$tag] = array();
|
||
$tags[$tag][$template->name] = $template->name;
|
||
} else {
|
||
$tags[$tag] = $tag;
|
||
}
|
||
}
|
||
}
|
||
ksort($tags);
|
||
return $tags;
|
||
}
|
||
|
||
|
||
/**
|
||
* Set a Permission for a Template for and specific Role
|
||
*
|
||
* Note: you must also save() the template to commit the change.
|
||
*
|
||
* #pw-internal
|
||
*
|
||
* @param Template $template
|
||
* @param Permission|string|int $permission
|
||
* @param Role|string|int $role
|
||
* @param bool $revoke Specify true to revoke the permission, or omit to add the permission
|
||
* @param bool $test When true, no changes are made but return value still applicable
|
||
* @return bool True if an update was made (or would be made), false if not
|
||
* @throws WireException If given unknown Role or Permission
|
||
*
|
||
*/
|
||
public function setTemplatePermissionByRole(Template $template, $permission, $role, $revoke = false, $test = false) {
|
||
|
||
if(!$template->useRoles) throw new WireException("Template $template does not have access control enabled");
|
||
|
||
$defaultPermissions = array('page-view', 'page-edit', 'page-create', 'page-add');
|
||
$updated = false;
|
||
|
||
if(is_string($role) || is_int($role)) $role = $this->wire()->roles->get($role);
|
||
if(!$role instanceof Role) throw new WireException("Unknown role for Template::setPermissionByRole");
|
||
|
||
if(is_string($permission) && in_array($permission, $defaultPermissions)) {
|
||
$permissionName = $permission;
|
||
} else if($permission instanceof Permission) {
|
||
$permissionName = $permission->name;
|
||
} else {
|
||
$permission = $this->wire()->permissions->get($permission);
|
||
$permissionName = $permission ? $permission->name : '';
|
||
}
|
||
|
||
if(in_array($permissionName, $defaultPermissions)) {
|
||
// use pre-defined view/edit/create/add roles
|
||
$roles = $template->getRoles($permissionName);
|
||
$has = $roles->has($role);
|
||
if($revoke) {
|
||
if($has) {
|
||
if($test) return true;
|
||
$roles->remove($role);
|
||
$template->setRoles($roles, $permissionName);
|
||
$updated = true;
|
||
}
|
||
} else if(!$has) {
|
||
if($test) return true;
|
||
$roles->add($role);
|
||
$template->setRoles($roles, $permissionName);
|
||
$updated = true;
|
||
}
|
||
|
||
} else if($permission instanceof Permission) {
|
||
$rolesPermissions = $template->get('rolesPermissions');
|
||
if(!is_array($rolesPermissions)) $rolesPermissions = array();
|
||
$rolePermissions = isset($rolesPermissions["$role->id"]) ? $rolesPermissions["$role->id"] : array();
|
||
$_rolePermissions = $rolePermissions;
|
||
if($revoke) {
|
||
$key = array_search("$permission->id", $rolePermissions);
|
||
if($key !== false) unset($rolePermissions[$key]);
|
||
if(!in_array("-$permission->id", $rolePermissions)) $rolePermissions[] = "-$permission->id";
|
||
} else {
|
||
$key = array_search("-$permission->id", $rolePermissions);
|
||
if($key !== false) unset($rolePermissions[$key]);
|
||
if(!in_array("$permission->id", $rolePermissions)) $rolePermissions[] = "$permission->id";
|
||
}
|
||
if($rolePermissions !== $_rolePermissions) {
|
||
if($test) return true;
|
||
$rolesPermissions["$role->id"] = $rolePermissions;
|
||
$template->set('rolesPermissions', $rolesPermissions);
|
||
$updated = true;
|
||
}
|
||
|
||
} else {
|
||
throw new WireException("Unknown permission for Templates::setPermissionByRole");
|
||
}
|
||
|
||
return $updated;
|
||
}
|
||
|
||
/**
|
||
* Hook called when a Template detects that its file has changed
|
||
*
|
||
* Note that the hook is not called until something in the system (like a page render) asks for the template’s filename.
|
||
* That’s because it would not be efficient for PW to check the file for every template in the system on every request.
|
||
*
|
||
* #pw-hooker
|
||
*
|
||
* @param Template $template
|
||
* @since 3.0.141
|
||
*
|
||
*/
|
||
public function ___fileModified(Template $template) {
|
||
if(empty($this->fileModTemplates)) {
|
||
// add hook on first call
|
||
$this->addHookAfter('ProcessWire::finished', $this, '_hookFinished');
|
||
}
|
||
$this->fileModTemplates[$template->id] = $template;
|
||
}
|
||
|
||
/**
|
||
* Saves templates that had modified files to update 'modified' and 'ns' properties after the request is complete
|
||
*
|
||
* #pw-internal
|
||
*
|
||
* @param HookEvent $e
|
||
* @since 3.0.141
|
||
*
|
||
*/
|
||
public function _hookFinished(HookEvent $e) {
|
||
foreach($this->fileModTemplates as /* $id => */ $template) {
|
||
if($template->isChanged('modified') || $template->isChanged('ns')) {
|
||
$template->save();
|
||
}
|
||
}
|
||
$this->fileModTemplates = array();
|
||
}
|
||
|
||
/**
|
||
* FUTURE USE: Is the parent/child relationship allowed?
|
||
*
|
||
* By default this method returns an associative array containing the following:
|
||
*
|
||
* - `allowed` (bool): Is the relationship allowed?
|
||
* - `reasons` (array): Array of strings containing reasons why relationship is or is not allowed.
|
||
*
|
||
* If you specify the `false` for the `verbose` option then this method just returns a boolean.
|
||
*
|
||
* @param Template|Page $parent Parent Template or Page to test.
|
||
* @param Template|Page $child Child Template or Page to test.
|
||
* @param array $options Options to modify default behavior:
|
||
* - `verbose` (bool): Return verbose array. When false, returns boolean rather than array (default=true).
|
||
* - `strict` (bool): Disallow relationships that do not match rules, even if relationship already exists (default=false).
|
||
* Note that this option only applies if method is given Page objects rather than Template objects.
|
||
* @return array|bool Returns associative array by default, or bool if the verbose option is false.
|
||
* @throws WireException if given invalid argument
|
||
*
|
||
public function allowRelationship($parent, $child, array $options = array()) {
|
||
|
||
$defaults = array(
|
||
'verbose' => true,
|
||
'strict' => false,
|
||
);
|
||
|
||
$options = array_merge($defaults, $options);
|
||
$parentPage = null;
|
||
$childPage = null;
|
||
|
||
if($child instanceof Template) {
|
||
$childTemplate = $child;
|
||
} else if($child instanceof Page) {
|
||
$childPage = $child;
|
||
$childTemplate = $child->template;
|
||
} else {
|
||
throw new WireException('Invalid argument for child');
|
||
}
|
||
|
||
if($parent instanceof Template) {
|
||
$parentTemplate = $parent;
|
||
} else if($parent instanceof Page) {
|
||
$parentPage = $parent;
|
||
$parentTemplate = $parent->template;
|
||
} else {
|
||
throw new WireException('Invalid argument for parent');
|
||
}
|
||
|
||
$reasonsNo = array();
|
||
$reasonsYes = array();
|
||
$isAlreadyParent = $parentPage && $childPage && $childPage->parent_id == $parentPage->id;
|
||
$isAlreadyParentNote = "parent/child allowed because relationship already exists";
|
||
|
||
if($isAlreadyParent) {
|
||
if($options['strict']) {
|
||
// in strict mode, existing relationships are ignored and we stick only to the rules
|
||
$isAlreadyParent = false;
|
||
} else {
|
||
$reasonsYes[] = "Given child page ($childPage) already has this parent ($parentPage)";
|
||
}
|
||
}
|
||
|
||
if($parentTemplate->noChildren) {
|
||
$reason = "Parent template “$parentTemplate” specifies “no children”";
|
||
if($isAlreadyParent) {
|
||
$reasonsYes[] = "$reason - $isAlreadyParentNote";
|
||
} else {
|
||
$reasonsNo[] = $reason;
|
||
}
|
||
}
|
||
|
||
if($childTemplate->noMove) {
|
||
$reason = "Child template “$childTemplate” specifies “no move”";
|
||
if($isAlreadyParent) {
|
||
$reasonsYes[] = "$reason - $isAlreadyParentNote";
|
||
} else {
|
||
$reasonsNo[] = $reason;
|
||
}
|
||
}
|
||
|
||
if($childTemplate->noParents > 0) {
|
||
$reason = "Child template “$childTemplate” specifies “no parents” option";
|
||
if($isAlreadyParent) {
|
||
$reasonsYes[] = "$reason - $isAlreadyParentNote";
|
||
} else {
|
||
$reasonsNo[] = $reason;
|
||
}
|
||
}
|
||
|
||
if(count($parentTemplate->childTemplates)) {
|
||
if(in_array($childTemplate->id, $parentTemplate->childTemplates)) {
|
||
$reasonsYes[] = "Parent template “$parentTemplate” specifically allows children of “$childTemplate”";
|
||
} else {
|
||
$reasonsNo[] = "Parent template “$parentTemplate” does not allow children using template “$childTemplate”";
|
||
}
|
||
}
|
||
|
||
if(count($childTemplate->parentTemplates)) {
|
||
if(in_array($parentTemplate->id, $childTemplate->parentTemplates)) {
|
||
$reasonsYes[] = "Child template “$childTemplate” specifically allows parents using template “$parentTemplate”";
|
||
} else {
|
||
$reasonsNo[] = "Child template “$childTemplate” does not allow parents using template “$parentTemplate”";
|
||
}
|
||
}
|
||
|
||
$allowed = count($reasonsNo) ? false : true;
|
||
|
||
if($options['verbose']) {
|
||
return array(
|
||
'allowed' => $allowed,
|
||
'reasons' => $allowed ? $reasonsYes : $reasonsNo,
|
||
);
|
||
}
|
||
|
||
return $allowed;
|
||
}
|
||
*/
|
||
|
||
}
|
||
|