云客Drupal源码分析之主题处理器theme handler

2024-06-09 08:18

本文主要是介绍云客Drupal源码分析之主题处理器theme handler,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

主题处理器theme_handler与主题管理器theme.manager都是系统提供的服务,虽然一字之差但她们功能完全不同,主题管理器用于主题渲染和派发主题修改钩子,而主题处理器完成更为底层的工作,向上为主题管理器、初始化器等各主题相关组件提供基础功能支持,定义如下:
服务id:theme_handler
类:Drupal\Core\Extension\ThemeHandler
获取方法:\Drupal::service("theme_handler");
主要完成的工作是扫描查找文件系统中的主题扩展、理顺继承关系、添加主题info文件的默认项、初始化一些全局函数的静态变量值、判明主题是否应该显示在UI中等等;

主题处理器主要工作是向上层应用提供主题的扩展对象(该对象见下),上层组件有了扩展对象后就可以操作主题了。

主题相关名字:
以下是一些和主题相关的名字及其含义:
机器名:
又叫主题扩展名,全局唯一,是识别主题的唯一标识,来源于info文件的文件名,如“bartik.info.yml”那么机器名就是“bartik”,不能包含空格,正则为:/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$/,有些特定名字虽然满足该正则,但不能被使用,如“template”;下文中除非特别说明,当提到主题名时均指机器名。
人类可读名:
在info文件中name项指定的名称,这可以和机器名不同也可不同,显示在UI中,能包括空格
目录名:
存放主题相关文件的目录名称,注意:主题的扫描查找实际上是在查找内容满足要求的以“.info.yml”后缀结束的文件(内容中必须有type属性),而不是依据目录结构信息,因此主题的目录名可以和机器名不同,但最佳实践应该相同,目录深度与结构不限,目录名不能使用:'src','lib','vendor','assets','css','files','images','js','misc','templates','includes','fixtures','Drupal',
这些目录在被扫描时会被跳过(可以利用这种特性隐藏多余的主题,不会对系统造成任何影响)
主扩展文件名:

默认为“机器名.扩展类型”,如“bartik.theme”、“search.module”,主扩展文件不是必须的,用于存放模块或主题需要的函数或定义常量,位于扩展根目录,是一个php文件,但并不以php做文件名后缀,如果存在则被默认加载。引擎主题是一个特殊情况,命名为“引擎名.engine”,如“twig.engine”。

扩展对象:
当扫描到一个合法的扩展时,系统会初始化一个扩展对象:
\Drupal\Core\Extension\Extension
该对象虽然在类定义中只有很少的属性,但却在初始化后从对象外部赋值了许多属性,见下,这些属性是公共的(public),该对象携带了扩展本身的所有信息,她是主题信息的承载者,初始化时:
$theme = new Extension($root, $type, $pathname, $filename);
四个参数分别是:
$root:drupal根路径,如“C:\root\drupal”没有后缀反斜杠
$type:扩展类型,来自info文件里面的type值
$pathname:info文件相对系统根目录的相对路径,如“core/themes/bartik/bartik.info.yml”
$filename:主扩展文件名,见前文描述,如“bartik.theme”,注意并非info文件的文件名

在主题扩展中常用的扩展对象属性如下(这里以$theme指代扩展对象):
$theme->type:扩展类型,主题是“theme”
$theme->info:从info文件里面解析出来的内容,附加了默认值
$theme->engine:该主题使用的模板引擎,默认为“Twig”
$theme->base_theme:直接基主题的机器名
$theme->libraries:info文件中声明的库
$theme->status:表示主题是否被安装,整数值,1为安装,0为未安装
$theme->owner:所用引擎的主扩展名,通常值为:“core/themes/engines/twig/twig.engine”
$theme->prefix:所用引擎前缀,通常为“twig”
$theme->base_themes:是一个数组,键名是基主题机器名,键值为基主题的人类可读名,如果指定了基主题但其不存在,那么值为NULL,元素顺序代表继承顺序,第一个元素是根基主题,最后一个元素是直接基主题
$theme->base_theme:是一个字符串值,直接基主题机器名,如果没有基主题则该属性不存在
$theme->sub_themes:是一个数组,代表所有子主题,键名是子主题机器名,键值为子主题人类可读名,元素顺序没有意义
$theme->required_by:数组,元素为全部需要该主题的主题(子主题)
$theme->requires:数组,该主题需要的主题(基主题)
$theme->origin:内部为排序目的使用,用于跟踪扩展扫描的起始目录
$theme->subpath:内部为排序目的使用,加上$theme->origin就是相对于系统根目录的子目录
$theme->sort:显示主题时的排序值
$theme->root:系统根路径,如“C:\root\drupal”
$theme->pathname:info文件相对系统根目录的相对路径,如“core/themes/bartik/bartik.info.yml”
$theme->$filename:主扩展文件名,值如“bartik.theme”,注意并非info文件的文件名

该扩展对象中,除类定义的方法外,还可以调用info文件初始化的\SplFileInfo对象上的方法
下文提到扩展对象时均是指该对象。

主题关键配置项与状态值:
在了解主题处理器前我们应该先知道和主题相关的主要配置和信息储存。
\Drupal::service("config.factory")->get('system.theme')->get(“admin”);
储存后台管理主题的机器名
\Drupal::service("config.factory")->get('system.theme')->get(“default”);
储存前端默认主题的机器名
\Drupal::service("config.factory")->get('core.extension')->get('theme');
储存所有被安装的主题,数组值,键名为主题机器名,键值为0
\Drupal::state()->get("system.theme.data");
储存所有被安装的主题,数组值,键名为主题机器名,键值为对应的扩展对象
\Drupal::state()->get("system.theme.files");
储存系统所有主题的info文件路径,包括没有启用的主题,数组值,键名为机器名,键值为相对系统根目录的路径,如:core/themes/bartik/bartik.info.yml
\Drupal::state()->get("system.theme_engine.files");
同上,只是储存模板引擎主题的机器名和路径,默认为[twig=>‘core/themes/engines/twig/twig.info.yml’]
\Drupal::cache('bootstrap')->get('system_list')
缓存主题数据,值为两个元素的数组,键名theme的值为\Drupal::state()->get("system.theme.data")的内容,键名filepaths的值为多个['type' => 'theme','name' => ‘主题机器名’,'filepath' => “info文件路径”,]元素构成的数组,如:['type' => 'theme','name' => ‘bartik’,'filepath' => “core/themes/bartik/bartik.info.yml”,]

主题处理器方法简述:
\Drupal::service("theme_handler")->getDefault();
得到前端主题机器名
setDefault($name);
设置前端主题,参数为机器名,必须是已经安装过的主题,她不会失效如何缓存,所以该方法只应该系统使用内部使用
listInfo()
列出所有已经安装的主题,返回数组值,键名为主题机器名,键值为对应的扩展对象,以扩展目录名作为排序依据(见\Drupal\Core\Extension\ExtensionDiscovery::sort),在很多使用情况下这个顺序是无意义的
addTheme(Extension $theme)
添加一个扩展对象到已安装主题列表
refreshInfo()
重新扫描文件系统,重新构建已经安装主题列表
rebuildThemeData()
扫描文件系统,返回所有存在的主题,包括未安装的主题,理顺主题的继承关系以及设置相关属性变量,返回一个数组,键名为主题机器名,键值为对应的扩展对象。
getBaseThemes(array $themes, $theme)
在一个主题集中查找一个主题的所有基主题,返回一个数组,键名是基主题机器名,键值为基主题的人类可读名,如果指定了基主题但其不存在,那么值为NULL,元素顺序代表继承顺序,第一个元素是根基主题,最后一个元素是直接基主题。
getName($theme)
根据一个主题的机器名返回人类可读名
getThemeDirectories()
得到所有已经安装主题的绝对路径,返回数组,键名为机器名,键值为路径名(不带文件名),如:C:\root\drupal/core/themes/bartik
themeExists($theme)
判断主题是否存在于已安装主题中
getTheme($name)
通过主题机器名取得扩展对象
hasUi($name)
判断主题是否应该在ui中出现,如果info信息中'hidden'为真,那么不出现,如果省略该项设置,默认出现,如果是默认的管理主题或前端主题,那么强制出现

此外安装卸载方法虽然在8.x版本中存在,但你不应该使用,将在9.0版本中移除,使用安装服务代替

主题info文件的附加默认值:
主题info文件被系统读取时会附加默认值,采用数组“+”操作,由此可见在没有指定选项时她会是什么样子,默认值被定义在主题处理器中,如下:

$defaults = ['engine' => 'twig','base theme' => 'stable','regions' => ['sidebar_first' => 'Left sidebar','sidebar_second' => 'Right sidebar','content' => 'Content','header' => 'Header','primary_menu' => 'Primary menu','secondary_menu' => 'Secondary menu','footer' => 'Footer','highlighted' => 'Highlighted','help' => 'Help','page_top' => 'Page top','page_bottom' => 'Page bottom','breadcrumb' => 'Breadcrumb',],'description' => '','features' =>  ['favicon','logo','node_user_picture','comment_user_picture','comment_user_verification',],'screenshot' => 'screenshot.png','php' => DRUPAL_MINIMUM_PHP,'libraries' => [],
];

由于采用数组后附加操作,所以当不想要某默认值时,需要自定义该值,比如不想要基主题那么需要明确定义为FALSE,否则默认为'stable'主题。
默认值被附加后,会派发system_info修改钩:
$moduleHandler->alter('system_info', $theme->info, $theme, $type);
这里 $theme是前文提到的\Drupal\Core\Extension\Extension对象,info是对象外附加的公共属性,内容是应用了默认值的info文件内容数组,$type值为'theme',模块可以通过hook_system_info_alter()去修改她,接收三个参数,第一个和第三个参数实际上是包含在Extension对象中的,由于php对象默认是按引用传递所以模块可以修改该对象(修改$info数组参数将无作用,她不是引用传递),由于派发钩子的原因,意味着先安装的模块可以修改后面正在安装主题的info文件

主题的继承:
可以一层一层的继承下去,层数不限,但只有一个直接基主题(父主题),也就是“单基多层继承”,这和php类继承类似。
drupal是可以使用多个主题引擎的,如果在主题继承链中,子主题和基主题指定了不同的主题引擎,那么将以根基主题的设置为准。
当声明了基主题后,就自动声明了基主题依赖,在info文件中不必手动指定

补充:
1、    在info文件里面注意空格的问题,如“'base theme'”项写成了“'base  theme'”将失去作用,那影响了数组键名,在建立info文件时最好复制修改,避免这些小问题。
2、    在主题处理器中使用了一些编程技巧加快系统性能,如:为主题初始化drupal_get_filename全局函数,通过drupal_static函数设置中心静态属性等,有兴趣可以自行深究
 

我是云客,【云游天下,做客四方】,联系方式见主页,欢迎转载,但须注明出处

 

 

 


 

 

这篇关于云客Drupal源码分析之主题处理器theme handler的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/1044645

相关文章

Go标准库常见错误分析和解决办法

《Go标准库常见错误分析和解决办法》Go语言的标准库为开发者提供了丰富且高效的工具,涵盖了从网络编程到文件操作等各个方面,然而,标准库虽好,使用不当却可能适得其反,正所谓工欲善其事,必先利其器,本文将... 目录1. 使用了错误的time.Duration2. time.After导致的内存泄漏3. jsO

Python实现无痛修改第三方库源码的方法详解

《Python实现无痛修改第三方库源码的方法详解》很多时候,我们下载的第三方库是不会有需求不满足的情况,但也有极少的情况,第三方库没有兼顾到需求,本文将介绍几个修改源码的操作,大家可以根据需求进行选择... 目录需求不符合模拟示例 1. 修改源文件2. 继承修改3. 猴子补丁4. 追踪局部变量需求不符合很

Spring事务中@Transactional注解不生效的原因分析与解决

《Spring事务中@Transactional注解不生效的原因分析与解决》在Spring框架中,@Transactional注解是管理数据库事务的核心方式,本文将深入分析事务自调用的底层原理,解释为... 目录1. 引言2. 事务自调用问题重现2.1 示例代码2.2 问题现象3. 为什么事务自调用会失效3

找不到Anaconda prompt终端的原因分析及解决方案

《找不到Anacondaprompt终端的原因分析及解决方案》因为anaconda还没有初始化,在安装anaconda的过程中,有一行是否要添加anaconda到菜单目录中,由于没有勾选,导致没有菜... 目录问题原因问http://www.chinasem.cn题解决安装了 Anaconda 却找不到 An

Spring定时任务只执行一次的原因分析与解决方案

《Spring定时任务只执行一次的原因分析与解决方案》在使用Spring的@Scheduled定时任务时,你是否遇到过任务只执行一次,后续不再触发的情况?这种情况可能由多种原因导致,如未启用调度、线程... 目录1. 问题背景2. Spring定时任务的基本用法3. 为什么定时任务只执行一次?3.1 未启用

C++ 各种map特点对比分析

《C++各种map特点对比分析》文章比较了C++中不同类型的map(如std::map,std::unordered_map,std::multimap,std::unordered_multima... 目录特点比较C++ 示例代码 ​​​​​​代码解释特点比较1. std::map底层实现:基于红黑

Spring、Spring Boot、Spring Cloud 的区别与联系分析

《Spring、SpringBoot、SpringCloud的区别与联系分析》Spring、SpringBoot和SpringCloud是Java开发中常用的框架,分别针对企业级应用开发、快速开... 目录1. Spring 框架2. Spring Boot3. Spring Cloud总结1. Sprin

Spring 中 BeanFactoryPostProcessor 的作用和示例源码分析

《Spring中BeanFactoryPostProcessor的作用和示例源码分析》Spring的BeanFactoryPostProcessor是容器初始化的扩展接口,允许在Bean实例化前... 目录一、概览1. 核心定位2. 核心功能详解3. 关键特性二、Spring 内置的 BeanFactory

MyBatis-Plus中Service接口的lambdaUpdate用法及实例分析

《MyBatis-Plus中Service接口的lambdaUpdate用法及实例分析》本文将详细讲解MyBatis-Plus中的lambdaUpdate用法,并提供丰富的案例来帮助读者更好地理解和应... 目录深入探索MyBATis-Plus中Service接口的lambdaUpdate用法及示例案例背景

MyBatis-Plus中静态工具Db的多种用法及实例分析

《MyBatis-Plus中静态工具Db的多种用法及实例分析》本文将详细讲解MyBatis-Plus中静态工具Db的各种用法,并结合具体案例进行演示和说明,具有很好的参考价值,希望对大家有所帮助,如有... 目录MyBATis-Plus中静态工具Db的多种用法及实例案例背景使用静态工具Db进行数据库操作插入