Gallery:外观主题:如何建立Theme.inc文件
每个Gallery外观主题都有一个名为theme.inc的PHP文件。该文件用于从Gallery Framwork获取数据以显示相册和相片信息,如标题,摘要,描述及日期等。theme.inc文件还允许开发者定义自己的显示参量,并为这些参量设定默认数值。显示参量包括但不仅限于单位向页面的项目显示数量,缩略图规格尺寸及页面宽度。
通过讨论AutoRC外观主题的theme.inc,此文档对theme.inc 文件的结构和意图进行了说明。
概览[ ]
了解theme.inc的用途以及作用步骤是重要的。
Theme.inc的用途如下:
- 读取Gallery常规数据,包括:
- 相册数据(标题,摘要,组织等)
- 图片数据(标题,摘要,尺寸,位置等)
- 外观主题设定(要显示的区块等)
- 读取额外数据并在必要时转为外观主题的显示
- 使收集而来的和被转换的数据可用于外观主题模板文件
Theme.inc的结构[ ]
theme.inc文件是PHP类别的文件。对于不了解面向对象编程的人而言,一个类别就是一组具有相似目的的函数集合,也被理解为方法。theme.inc文件扩展了GalleryTheme类别,该类别控制Gallery中信息的显示。
有关theme.inc文件:
- 以类别声明开头
class AutoRcTheme extends GalleryTheme
AutoRC即Automatic Rows and Columns.
- 类别声明包括了外观主题名称或缩写,其后接着'Theme'
- 该类别中的第一个函数就是建构式(constructor)
- 建构式的名称必须符合类别的名称
- 类别必须包含GalleryTheme.class中的一些特定方法
- 你可以向类别中添加自己外观主题的特定方法
剩余的函数成员名称应能表明其用途。看看下面的theme.inc的骨架结构。接着我们会填充各函数中...的部分。 /** */
中的文本是批注,不会被解析。。
<highlightSyntax> class AutoRcTheme extends GalleryTheme {
/** * 建构式 */ function AutoRcTheme() { ... } /** * @参见 GalleryTheme::showAlbumPage */ function showAlbumPage(&$template, $item, $params, $childIds) { ... }
/** * @参见 GalleryTheme::showPhotoPage */ function showPhotoPage(&$template, $item, $params) { ... }
/** * @参见 GalleryTheme::showModulePage */ function showModulePage(&$template, $item, $params, $templateFile) { ... }
/** * @参见 GalleryTheme::showAdminPage */ function showAdminPage(&$template, $item, $params, $templateFile) { ... }
/** * @参见 GalleryTheme::showErrorPage */ function showErrorPage(&$template) { ... }
/** * @参见 GalleryTheme::showProgressBarPage */ function showProgressBarPage(&$template, $item, $params) { ... }
/** * @参见 GalleryTheme::getSettings() */ function getSettings($itemId=null) { ... }
/** * @参见 GalleryTheme::validateSettings */ function validateSettings($settings) { ... } }
</highlightSyntax>
外观主题建构式[ ]
建构式方法初始化或启用外观主题并读取用在整个外观主题中的常规数据。通过在scope中的全局声明,建构式也必须提取$gallery变量,图片文件名称,标题和字幕中的必要数据。现在$gallery变量中的数据可以为外观主题函数所用了。
<highlightSyntax> /**
* 建构式 */ function AutoRcTheme() { global $gallery;
$this->setId('autorc'); $this->setName($gallery->i18n('AutoRC Theme')); $this->setDescription($gallery->i18n('Rows and columns that automatically adjust')); $this->setVersion('0.5.0'); $this->setRequiredCoreApi(array(7, 0)); $this->setRequiredThemeApi(array(2, 1)); $this->setStandardSettings(array( 'perPage' => 6, 'sidebarBlocks' => serialize(array( array('search.SearchBlock', array('showAdvancedLink' => true)), array('core.ItemLinks', array('useDropdown' => false)), array('imageblock.ImageBlock', array()))), 'albumBlocks' => serialize(array( array('comment.ViewComments', array()))), 'photoBlocks' => serialize(array( array('exif.ExifInfo', array()), array('comment.ViewComments', array()))) ) ); }
</highlightSyntax>
构建式还:
- 设定外观主题的唯一ID,它会被存储在数据库中
- 定义外观主题名称,该明朝会被显示在插件及外观主题管理区中
- 设定外观主题的版本号,随着外观主题的更动此数字会增大
- 定义外观主题所能兼容的Gallery版本
- 定义兼容性所要求的外观主题API版本
- 设定外观主题的标准设定,包括外观主题边栏,相册和相片显示区域中所显示的区块
setStandardSettings数组中的perPage索引是我为AutoRC外观主题创建的变量。区块变量是在sidebarBlocks,albumBlocks和photoBlocks中设定的,它们定义要添加的元素及各元素具体的渲染方式。
你还可以向setStandardSettings添加更多的东西。参看一下其他外观主题的theme.inc文件,来看看是否能得到点灵感。
标准方法,方法结构及外观主题相关变量[ ]
剩下的theme.inc方法遵照一下的标准结构。
- 使用函数来对Gallery数据进行获取,修改或执行某些操作(
$ret = someFunction();
ORlist ($ret, $someData) = somefunction();
) - 执行错误检查(
if ($ret) { return array($ret, null); }
) - 如未发生错误,返回被请求视图的模板
return array(null, 'temaplateFileName.tpl');
theme.inc所接受的常规变量或参数有:
- $template: 持有某外观主题模板可用的所有信息
- $item: 被请求的相册或相片的信息,标题,描述及摘要等
- $params: 为被请求的相册或相片设定的外观主题参量,包括要显示的区块,图片尺寸及单位相册页面显示的项目数量等
- $childIds: 某被请求相册各要显示相片的ID号
- $templateFile: 当前请求(相册,相片,admin等)中被请求模板文件
- $settings: 由外观主题设定的自定义参量
现在来看看AutoRC的theme.inc成员函数。
showAlbumPage()[ ]
此函数准备并载入要显示在外观主题相册模板中的数据。在Gallery中,相册模板显示一组相片缩略图及各缩略图的详细信息。一般情况下,缩略图和标题会链接到个项目的详细视图。
对于theme.inc中其他各函数,我们只希望载入相册模板所需的数据。AutoRC外观主题使用loadCommonTemplateData来载入标题,子项目数,分支项目数,上级相册相关信息,站点管理及编辑项目视图的链接,项目摘要,权限信息,缩略图设定,页面导航,当然还有要显示项目的id。
<highlightSyntax> /**
* @参见 GalleryTheme::showAlbumPage */ function showAlbumPage(&$template, $item, $params, $childIds) { $ret = $this->loadCommonTemplateData( $template, $item, $params, array('title', 'childCount', 'descendentCount', 'parents', 'systemLinks', 'itemLinks', 'itemSummaries', 'permissions', 'thumbnails', 'pageNavigator', 'jumpRange'), $childIds); if ($ret) { return array($ret, null); } return array(null, 'theme.tpl'); }
</highlightSyntax>
showPhotoPage()[ ]
<highlightSyntax> /**
* @参见 GalleryTheme::showPhotoPage */ function showPhotoPage(&$template, $item, $params) { $dataTypes = array('parents', 'systemLinks', 'itemLinks', 'permissions', 'itemLinksDetailed', 'itemNavigator', 'imageViews', 'peerList', 'pageNavigator', 'jumpRange'); $ret = $this->loadCommonTemplateData($template, $item, $params, $dataTypes); if ($ret) { return array($ret, null); } return array(null, 'theme.tpl'); }
</highlightSyntax>
showModulePage()[ ]
<highlightSyntax> /**
* @参见 GalleryTheme::showModulePage */ function showModulePage(&$template, $item, $params, $templateFile) { $ret = $this->loadCommonTemplateData( $template, $item, $params, array('parents', 'systemLinks')); if ($ret) { return array($ret, null); }
return array(null, 'theme.tpl'); }
</highlightSyntax>
showAdminPage()[ ]
<highlightSyntax> /**
* @参见 GalleryTheme::showAdminPage */ function showAdminPage(&$template, $item, $params, $templateFile) { $ret = $this->loadCommonTemplateData( $template, $item, $params, array('parents', 'systemLinks')); if ($ret) { return array($ret, null); } return array(null, 'theme.tpl'); }
</highlightSyntax>
showErrorPage()[ ]
<highlightSyntax> /**
* @参见 GalleryTheme::showErrorPage */ function showErrorPage(&$template) { return array(null, 'error.tpl'); }
</highlightSyntax>
showProgressBarPage()[ ]
<highlightSyntax> /**
* @参见 GalleryTheme::showProgressBarPage */ function showProgressBarPage(&$template, $item, $params) { $ret = $this->loadCommonTemplateData( $template, $item, $params, array('parents', 'systemLinks')); if ($ret) { return array($ret, null); }
return array(null, 'theme.tpl'); }
</highlightSyntax>
getSettings()[ ]
<highlightSyntax> /**
* @参见 GalleryTheme::getSettings() */ function getSettings($itemId=null) { list ($ret, $settings, $params) = parent::getSettings($itemId); if ($ret) { return array($ret, null); } return array(null, $settings); }
</highlightSyntax>
validateSettings()[ ]
<highlightSyntax> /**
* @参见 GalleryTheme::validateSettings */ function validateSettings($settings) { $error = parent::validateSettings($settings); if (!is_numeric($settings['perPage'])) { $error['perPage'] = $this->translate('You must enter a number'); } return $error; }
</highlightSyntax>