|
目录
来源:http://trac.seagullproject.org/wiki/Howto/Blocks 使用block什么是版块(block)?一个block是从你模板中调用的代码片断。组成一个页面的所有模板排布在主模板上。如果你浏览了这个目录，你会发现有很多你可以使用的主模板，不过大多数的开发人员会创建适合自己需要的模板。blocksLeft.html和blocksRight.html就是在模板内调用blocks的例子。 Seagull使用blocks来提供一个更灵活的包含动态内容的方式，就像左右两边的栏目，导航菜单或breadcrumbs。Block可以被限制归属于某个section，（以管理员登陆并选择导航），也可以限制特定角色的成员可以使用。如果要需要的话你可以重新排列，禁用block。按照惯例，如果一个block和一个模块的功能有关，它应该保存在那个模块内，如‘最近的文章’block应该是放在publisher模块中的block目录内。 激活一个现有的block要创建一个新block，使它出现在您的Seagull项目左边或右边专栏, 您需要做以下: 1. 登录作为admin 并选择Blocks → Manage Blocks 2. 点击'New Block' 来新增block。 3. 为您的block的名称和标题填写相关的细节信息。您可以选择现有的任何block类名。 4. 标题和正文类域允许对您的block选定CSS 类- 如果您把这些栏目放空，将应用全局block的CSS 类。 5. 通过击中' publish' 选择框, 您可选择block将出现的section、可访问该block的角色和它要出现的位置。 6. 一些block允许您增加一些块具体的参数, 如果是这样的block您将看到一个另外的选择框。 7. 点击’submit’,block详细内容将被保存。如果”activate” 选项被选中了，那么您选择的角色就可以在您指定的位置和里看见您新建的block。 您可以尝试Seagull自带但没有被默认激活的block: • LoginBlock • CalendarBlock 新建您自己的Block要新建您自己的block, 必须按照下列步骤进行(这些步骤是参考0.6.x版本写的) 创建类1. 首先, 您需要为您的Block创建一个类。我们以创建一个名为”PhotoGallery"Block为例子。 1. 在 modules/<module name>/blocks目录下创建一个新的Block类, <module name>是这个block所在模块里的名称。 2. 类的文件名应该是您的block的名字, 并且block类名应该是<module name>_Block_<block class name> 3. block类中必须有init() 方法,返回getBlockContent() 方法的返回值。getBlockContent() 方法可能返回HTML 或直接返回文本字符串, 就旬在Sample1 block那样；或者它可能直接调用其它方法检索它的内容, 也是在上面那个例子中可以看见。 注意当block被装载时, 它会收到多个可以block内部使用的参数(参见block参数以获取更多信息) 。 最快的方法是复制现有的某一个block类,如Sample1.php。但是, 这个方法将忽略许多block中可用的特性, 所以还是让我们来看一下。 Block参数当blocks在由BlockLoader装载处理过程中, 它们会收到如下的几个参数： 1. $output 对象(传递参考; 用来显示的对象) 2. $block_id (值传递; 存储在数据库里的block的id) 3. $aParams 数组(传递参考; 如果您的block有任何额外的参数, 参见block的额外参数) Block的额外参数在新建block时, 您可以一个名为< block name>.ini的文件内指定block可以访问的额外参数。当block被装载后, 他们将从这个文件中分离出来并运用于block的创建, 然后被序列化后保存在数据库中。以后这些参数就要可以在管理界面中编辑；当您编辑这个block时将看见block参数标签选项。 通常会有一个block 详细资料标签选项，那里应该是您输入名字、描述、作者、创建日期, 版本, 和版权的[ 细节] 部分。 所有其它的栏目就是您的block的额外参数, 在你的block类代码内可以通过$aParamssectionname调用这些参数。这些部分应该带着type, value, label, 和 description. • type让您选择在Admin区域您是否想要文本框, 下拉框, 复选框, 或单选按钮等表单控件 。 • value是这个参数的缺省值。 • label是被显示在block参数标签内的Admin 区域的文本。 • description将被显示在tooltip 文本 例子注意, 这个例子中创建的模板参数只是为了示范目的; 模板和模板路径参数不是必须的。 PhotoGallery.ini [details] name = "Photo Gallery Block" description = "Show random photos from a database" author = "Clay Hinson" created = "2006-09-15" version = "0.5" copyright = [blockTemplate] type = "text" value = "photoGallery.html" label = "Template file for block" description = "File that should be loaded for the block content" [blockTemplatePath] type = "text" value = "default" label = "Template file path" description = "Path to search for the template file" 自定义Block代码例子我们的block例子, PhotoGallery, 是放在default模块中, 因此文件名应该是modules/default/blocks/PhotoGallery.php。类名是 Default_Block_PhotoGallery。
class Default_Block_PhotoGallery
{
function init(&$output, $block_id, &$aParams)
{
SGL::logMessage(null, PEAR_LOG_DEBUG);
return $this->getBlockContent($output, &$aParams);
}
function getBlockContent(&$output, &$aParams)
{
// set up the block output object
$blockOutput = new SGL_Output();
$blockOutput->webRoot = $output->webRoot;
$blockOutput->imagesDir = $output->imagesDir;
$blockOutput->theme = $output->theme;
[... block php code - build the photo gallery html ...]
return $this->process($blockOutput, &$aParams);
}
function process(&$output, &$aParams)
{
// set template path and file
$output->moduleName = $aParams['blockTemplatePath'];
$output->masterTemplate = $aParams['blockTemplate'];
// output the HTML
$view = new SGL_HtmlSimpleView($output);
return $view->render();
}
}
创建一个Block 模板您的bock不仅需要类, 如果你要动态的创建html代码就还需要有模板 。这个文件被存放在 /www/themes/<mytheme>/<module name>/<block name>.html 作为我们的block例子。正如上面我们所看到的, 这个block在block参数中告诉我们这个文件的路径, 理论上您可以将它存放它任何地方在您自己主题的目录中或在默认主题目录中。
{foreach:resultValues,key,aValue}
<div class="photo">
<a href="{webRoot}/themes/{theme}/images/photos/{aValue[image_name]}" target="_blank">
<img src="{webRoot}/themes/{theme}/images/photos/thumbnails/{aValue[image_name]}" height="{aValue[thumb_height]}" width="{aValue[thumb_width]}" border=0></a>
<div class="caption small">{aValue[caption]:h}</div>
</div>
{end:}
使用Block您已经完成了block的类和参数文件的创建,现在您可以在参照上面的 http://trac.seagullproject.org/wiki/Howto/Blocks#Activatinganexistingblock｜激活一个现有的block, 或参照如下例子来使用你的bock。 激活一个现有的block例子我们试着实现一个Breadcrumbs block, 改变它的位置和布局: 我们按照上面的步骤增加一个新block:
我们使用包含在Navigation模块下的Breadcrumbs类创建了新的block，并把它放在MainBreadcrumb位置。 您可以通过在ary.blocksNames.php定义位置来添加你的自定义的block位置。 我们可以选择MainBreadcrumb 位置的的实际位置, 例如在您的banner.html 模板文件, 增加以下几行:
{foreach:blocksMainBreadcrumb,key,valueObj}
{valueObj.content:h}
{end:}
我们可为我们的主题修改breadcrumbs的html模板（译者注：意思是同一个block在不同的主题下可以采用不同的模板，以不同的面貌呈现给用户）:
在页面的上部或底部增加block简单地创造一个block并将它指定在页面的头部(top)或底部(bottom)，然后在您的模板增加如下代码：
{foreach:blocksBottom,key,valueObj}
{if:valueObj.title_class}
{valueObj.title}
{end:}
{if:valueObj.body_class}
{valueObj.content:h}
{end:}
{end:}
注: 如果您要在block内容为空时不被显示, 请修改成:
{foreach:blocksBottom,key,valueObj}
{if:valueObj.content}
{if:valueObj.title_class}
{valueObj.title}
{end:}
{if:valueObj.body_class}
{valueObj.content:h}
{end:}
{end:}
{end:}
创建自定义的block位置
默认所有的创建的block需要在页面中指定一个它的显示位置。位置模板在 lib/data/ary.blocksNmes.php 在主模板中调用block位置，主模板默认文件是 seagull/modules/default/templates/master.html 要创建你自已的主模板，只需要先创建你自己的主题，然后创建了个名为'default'的子文件夹，并在这个文件夹中创建名为master.html的文件，如 seagull/www/themes/my_theme/default/master.html 你可以通过设置全局变量重写这些值来创建你自己的block 位置。这里是一个例子：
$GLOBALS['_SGL']['aBlocksNames'] = array(
'Right'=> 'Right',
'Left' => 'Left',
'Top' => 'Top',
'Bottom' => 'Bottom',
'BodyTop' => 'BodyTop',
'AdminCategory' => 'AdminCategory',
'AdminNav' => 'AdminNav',
'AdminBreadcrumbs' => 'AdminBreadcrumbs',
'MainNav' => 'MainNav',
'SearchBar' => 'SearchBar',
'MainBreadcrumb' => 'MainBreadcrumb',
);
要在每次请求都载入这个全局数组，要么在一个自定义配置文件中定义： $conf['path']['pathToCustomConfigFile'] 或者在你的任意一个模块的根目录下创建一个init.php文件中定义，如 seagull/modules/my_module/init.php |