【Webtrees 手册】第 9 章 - 开发指南
Webtrees手册/开发环境
手册部分仍在建设中
请耐心等待或随意贡献自己的力量:-)。| 第 9 章 - 开发环境 <- 章节概述 |
目录
|
即使您不想自己开发webtrees的模块，您仍然会接触到开发环境。例如，如果您在使用webtrees时遇到错误或者某个功能对您来说不够用。德语翻译中的某些内容可能也让您感到困扰。或者您可能会遇到即使阅读本手册后仍无法解决的问题。
在本手册的这一章中，您将了解如何处理这些情况以及如何参与webtrees社区。也许您想根据您的需要调整webtrees模块，甚至开发一个新模块。这可能比你想象的要容易。本章倒数第二部分将对此进行更多介绍。然而，也可能您只想自定义用户界面的外观；借助“ CSS 和 JS ”模块，这可以变得非常容易。您可以在本章的 最后一节找到一些示例。
因此，您可以通过多种方式为webtrees做出贡献。例如，
- 回答其他用户的问题
- 如果发现错误，请报告问题
- 建议新功能或改进
- 翻译文本
- 改进文档
- 改进程序代码或编写全新模块
- 测试功能。
澄清问题
使用webtrees的一个无价的优势是该程序的用户社区受到高度赞扬。对于每个疑问和每个问题， webtrees的开发人员和其他用户都会提供快速而有效的帮助。
webtrees论坛
英语webtrees 论坛用于与其他webtrees用户和开发人员交流想法。您可以在那里询问任何问题。因此，您一定要在论坛上注册为用户。当前信息也会发布在那里，例如当发布 新版本的webtrees时。
论坛分为不同的主题
- 2.2 版帮助 - 您可以在这里找到有关webtrees当前版本的所有问题
- 2.1 版帮助 - 有关先前版本 2.1 的所有问题
- 2.1 迁移帮助 - 这里讨论了从 2.0 到 2.1 的过渡
- 2.0 版帮助 - 有关之前版本 2.0 的所有问题
- Beta 版 GitHub“主分支” - 这里讨论有关下一版webtrees的问题
- 1.7 版帮助 - 有关冻结的 1.7 版（及更早版本）的所有问题
- 公开讨论——高阶性质的问题（策略、一般谱系）
- webtrees 论坛问题 - 所有与论坛本身相关的问题
- 定制 - 关于扩展模块的问题
- 翻译 - 与翻译成不同语言相关的主题
- 新功能请求 - 请求webtrees的新功能
- 从 PhpGedView 转换（PGV） - 从前身程序 PhpGedView 切换到webtrees
因此，您应该做的第一件事就是考虑您的问题最适合哪个主题。然后在那里提出您的问题。
如果您考虑以下几点，将会很有帮助
- webtrees得到了许多志愿者的支持，他们为其编写程序并帮助解决论坛中的问题。请记住，您无权期望问题得到解决或新功能按照您的意愿实现。如果你想改变某些事情，你可以要求它，但你可能必须自己改进它。
- 如果您提供他们的网站地址，我们将更容易为您提供帮助。最好的方法是将您网站的链接直接集成到您的论坛签名中。
- 如果您遇到服务器问题，请告诉我们您的环境中安装了哪些软件版本，这将有所帮助。您也可以将此信息包含在您的论坛签名中。
- 请事先检查您的问题是否已在论坛中得到解答。您可以使用“搜索”选项卡搜索论坛页面。
- 如果您遇到从1.7 迁移到 2.0或从2.0 迁移到 2.1的问题，请首先阅读本指南中的相关部分。
- 如果您认为发现了错误，请首先禁用您正在使用的任何扩展模块。如果这样解决了问题，请在扩展模块的 GitHub 页面上提交错误，或者如果您打算在论坛上报告问题，请至少提及自定义模块是问题的可能原因。如果问题与扩展模块无关，请检查已知的webtrees 错误列表。然后在 GitHub 上报告错误之前返回论坛并询问。也许这是你没有完全理解的事情，而根本不是一个错误。
- 论坛的默认语言是英语。如果您更喜欢用德语提问，您还应该添加英语翻译（也许使用谷歌翻译或DeepL）。如果可能的话，我们会用德语回答您，或者您会使用反向翻译工具。
- 请勿使用论坛帖子、签名或头像链接进行广告或号召性用语。
- 不要发表过多的帖子，也不要添加对论坛中其他用户没有价值的不必要的评论。
- 另请阅读论坛帮助页面“论坛帮助”。这包含有关使用论坛的更多提示以及有关上传文件和图像作为附件的一些重要信息。
话语
在CompGen的“ Discourse ”系统中，有一个关于网络树的很少使用的线程。那里的讨论总是用德语进行。
程序错误的分析和报告
对于像webtrees这样庞大的程序来说，程序中不可避免地会出现错误。每次发布新版本时，错误都会被修复，但也会出现新的错误。然而，也存在一些位于webtrees之外的错误来源，例如，如果您作为网站管理员激活了新版本的 PHP，或者您的网络主机对系统环境进行了更改。其他开发人员的webtrees提供的库也常常被认为是错误的来源。
有些错误非常严重，以至于您无法再访问您的网站，有些错误会导致出现错误消息，还有一些错误会导致网站树无法按照您预期的方式运行。以下部分讨论这些类型的错误。这不包括家谱数据本身的错误，即错误的 GEDCOM 结构（参见故障排除部分）以及不合理或不正确的家谱数据。
错误并显示错误消息
使用该程序时，您可能会收到错误消息。这可能看起来有点像右边的截图。
最上面一行表示发生错误的位置。这不一定是导致错误的位置。因此，错误消息包含额外的行，显示之前调用了哪些程序函数。
如果发生错误的位置属于扩展模块，那么您应该做的第一件事就是停用该扩展模块并测试这是否也能解决错误。如果您随后重新激活有问题的扩展模块并且错误再次出现，那么您几乎肯定已经找到了错误，并且可以在扩展模块的 GitHub 页面上将其报告为“问题”。在执行此操作之前，您应该检查未解决问题列表，看看是否已经报告了此错误。然而，也可能出现这样的情况：导致错误消息的操作显然属于错误消息中显示的扩展模块的功能。那么任务就非常明确了，如果您和其他用户可以忍受不正确的行为直到问题得到解决，您可能能够避免停用扩展模块。
如果该错误出现在webtrees核心功能中，请在webtrees GitHub 页面上报告此错误。如果错误非常严重并且您无法等到修复它，那么也许唯一的选择是从备份中恢复早期版本的webtrees 。但是，您应该事先在webtrees论坛中澄清这一点。
|
| 还描述：如何在 GitHub 中创建问题（针对核心和扩展模块）以及应该报告什么（我做了什么，我期望什么，错误消息的顶行是什么样的（复制大约 10 行） |
|
安全相关错误
导致数据安全或数据保护问题的错误很少发生。如果您在webtrees中遇到此类错误，请立即报告。但是，不要使用论坛或 GitHub，而是直接向Greg Roach发送电子邮件。
作为网站管理员或网站运营商，您有责任修复您的网络服务器上的安全问题或与webtrees无关的其他问题。 PHP 中也存在安全问题。 PHP 开发人员仅维护 7.4 及更高版本。
维护版本
webtrees代码中与安全相关的错误可能长期未被发现。但是，仅webtrees 2.0 及更高版本仍得到维护。旧版本（因此不再受支持）的操作员必须自行修复新发现的安全漏洞。
响应时间
您可以在报告问题后 24 小时内通过电子邮件收到确认。
请记住，并非所有电子邮件都会被送达，并且世界上某些地区无法访问互联网。如果您没有收到回复，请发送后续电子邮件。如果您仍然没有收到回复，请尝试通过webtrees.net上的项目论坛与我们联系 。
根据问题的复杂性和严重性，我们将尝试在两到七天内发布解决方案。
披露和归属
请等待webtrees新版本发布并修复所报告的安全问题后再发布有关该问题的详细信息。如果您希望对您的发现获得认可，请告诉我。
意外的程序行为
有时Webtree 的行为可能会超出您的预期。功能的反应与预期不同，或者屏幕上的显示不符合您的预期。这可能是也可能不是webtrees的故障，因为您可能有不同的期望。因此，在这种情况下，再次仔细查看相关部分是有意义的。本手册也应该对此有所帮助。
并且您应该尝试缩小错误的可能原因。如果您使用扩展模块，则应首先停用它们。如果仍然出现意外行为，您可以假设问题出在webtrees本身。否则，请逐个重新启用扩展模块，以找到导致不正确或意外行为的模块。
如果您仍然不确定这是否是一个错误，您应该在webtrees论坛中报告 该问题。
请描述
- 你想要实现什么
- 在发生错误或意外行为之前你具体做了什么
- 发生了什么（最好用截图记录）
- 你期望但没有发生的事情
屏幕空白
空白页意味着发生了两件事[2]
- 创建网站时发生严重错误。
- 您的 Web 服务器（例如 Apache、Nginx、IIS）配置为不在屏幕上显示致命错误。
致命错误的典型原因包括
- 不兼容的软件：例如，将 PHP 7.3 与为 PHP 7.4 设计的软件一起使用。
- 文件权限：webtrees需要对“/data”文件夹中的所有文件和子文件夹具有写权限。
- 磁盘空间已耗尽：您可以通过 FTP 将大文件上传到服务器（然后删除它）来检查是否存在问题。
- 已达到CPU 时间限制：您可以判断这一点，因为只有在经过一段时间而没有任何响应后才会出现错误。
- 内存不足：这可能是由于程序错误或一次处理太多数据造成的。例如，如果您尝试一次列出几千人。
- 阻止的 PHP 函数：函数被服务器阻止。例如，发送电子邮件所需的功能可能会被阻止。
当发生严重错误时，Web 服务器通常会将详细的错误消息写入日志文件。您需要找到这个错误日志（请参阅下面的“其他错误分析方法”部分）。如果没有这个文件，解决问题将非常困难。
如果您的服务器支持.htaccess文件，您可以尝试在其中添加以下行（并非所有服务器都支持此功能）
php_flag display_errors开启
php_flag display_startup_errors开启
php_value error_reporting -1
进一步的误差分析方法
|
| 描述各种日志文件的分析 |
|
请注意，您的 Web 服务器会创建两个日志文件。一个是访问日志，另一个是错误日志。您将需要错误日志来解决问题。如果互联网上攻击您的服务器的尝试增多，访问日志可以提供线索。
如果您找不到错误日志，您应该联系您的托管服务提供商寻求帮助。
|
| 描述使用浏览器开发者功能进行错误分析 |
|
改进潜力
多年来，webtrees不断得到改进，并进行了许多小的改动。然而，我们在向现代软件架构和模块化概念迈进方面也取得了重大进展。然而， webtrees中仍有一些问题没有得到很好的解决。并且还有许多扩展请求。下面将更详细地讨论这两者。您还可以在webtrees 论坛中找到 所请求的新功能列表。
报告无法维护和进一步开发
使用 XML 生成报告的内部结构已经过时。结果，它们不再能够维持，甚至无法扩大。然而，这是必要的，因为布局、内容选择和自定义选项都不令人满意。这些报告必须从头开始制定。这也在论坛中被反复批评和解释，但不幸的是优先级很低。
此外，报告系统直接访问 GEDCOM 数据，而不像所有其他webtrees模块那样使用内部封装的数据结构。这意味着无法改变 GEDCOM 数据的存储方式。
缺少合理性检查
目前，webtrees会检查是否符合 GEDCOM 语法，但几乎不会分析数据本身。检查家谱数据真实性的功能很少，但需要进行更多检查。那些活了两百多岁、十岁结婚或死后才成为父母的人，说明有些事情没有被正确地描述。对于一个人出生前或死亡后发生的事件，用户界面中都会有一些小提示。列出此类错误或在数据输入期间提供明确信息的报告将会很有帮助。
图表不足
有不同的图表来表示家谱中的人物和家族，但目前没有装饰图表，即艺术表现形式，例如在背景中绘制一棵树。
支持长处理步骤
处理大量数据或高复杂性时，某些处理步骤需要很长时间。例如，导入非常大的家谱、搜索和替换大量数据，或在大量家谱数据中查找错误。由于webtrees是一个 Web 应用程序，因此此类操作不能花费无限长的时间，因为浏览器期望在一定时间后收到webtrees服务器的响应；如果没有到达，浏览器可能会终止连接，用户将收到错误消息或空白屏幕。对于可能需要更长时间的各种操作，webtrees已经包含内部解决方案，可以将这些任务分解为更短的子任务。然而，这一程序必须得到推广，然后在更多的地方使用。
支持GEDCOM 7.0
到目前为止， webtrees支持GEDCOM 标准 5.5.1 和各种 GEDCOM 方言。 GEDCOM 7.0 标准的某些选定语言元素也受支持。导入时，webtrees对要导入的结构非常宽容。很多东西都被内部认可和保留，即使它们是标准的延伸或偏差。导出家谱时，隐含支持 5.5.1 标准。目前还没有概念如何并行支持当前的 GEDCOM 标准 7.0 与广泛使用的标准 5.5.1。因此，目前尚不清楚webtrees何时会根据 GEDCOM 7.0 提供导出功能。但是，已经有一个扩展模块可以以 GEDCOM 7.0 格式进行导出。
调整用户界面的困难
webtrees提供了覆盖部分标准模块的可能性，从而可以更改视图或功能，而不必重新实现扩展模块中的所有功能，只需更改显示中的小细节即可。然而， webtrees系统中的方法并不完美，因为不同的扩展模块可能会覆盖相同的视图。没有针对可能发生的冲突的检测机制（最后注册的模块获胜），因此在这种情况下Webtree的行为无法可靠地预测。
覆盖函数并不总是目标；有时扩展模块仅用于扩展用户界面的特定部分，例如，在显示对象之前对其进行操作或抑制。其他示例包括向用户界面中的元素添加图标或向手风琴结构添加点。或者对表格的显示进行更小的添加，例如添加另一列。
规划安全
目前还没有针对webtrees的详细发布计划。目前，webtrees的版本为 2.2。切换到 2.2 版本后，2.1 版本中的许多扩展模块不再起作用。尽管在大多数情况下适应都很快，但开发人员对此只做好了部分准备。不幸的是， webtrees核心的开发没有与扩展模块的作者协调。
2.2 版本的未来更新是否也会集成到 2.1 版本中还有待观察。在 2.2 版的后续版本中，扩展模块将得到更好的管理：管理员可以执行模块的安装、升级和删除。
有时扩展模块的功能会被纳入核心，但这种情况很少见。最近，核心中添加了几个与位置数据集（_LOC）相关的功能，这些功能以前只能通过 Vesta 扩展模块使用。沟通不畅可能导致重复开发或扩展模块中的接口必须随着webtrees的每个新版本进行调整。在进行这些调整之前，受影响的扩展模块暂时无法再使用。
对接口的依赖
创建复杂模块时，可能需要提供基本功能的额外供应商库。将库添加到标准库可能很困难，因为它们可能与基础包中的现有库或其他扩展模块中的库冲突。webtrees不提供管理不同模块之间依赖关系的支持。
扩展模块无自动更新
除了手动升级之外， webtrees还提供了非常方便的自动升级，管理员启动后会自动切换到当前版本的webtrees 。不幸的是，这种机制不适用于扩展模块。webtrees 2.2 版旨在朝着这个方向迈出第一步。
改进建议
随着时间的推移，当您使用webtrees时，您肯定会注意到可以设计得更好或解决得更好的事情。您可以采用不同的方式来传达您的想法。本节将介绍更多详细信息。但是，您应该记住，webtrees是由志愿者在空闲时间无偿维护和开发的。因此，无法保证错误会在短期内得到纠正，也无法保证改进建议会在某个时候得到实施。因此，如果有什么事情困扰着你，你应该首先考虑自己能积极做出什么贡献。
改进 Webtree 的建议
|
| 描述：在论坛的“新功能请求”类别中 |
|
|
| 描述：通过 github（问题或拉取请求） |
|
改进德语翻译的建议
webtrees中的主要语言是美式英语。如果您发现您使用的另一种语言中有翻译错误或未翻译的单词，您可以在这里自己做出贡献。有关所用翻译系统的更多详细信息，请参阅“扩展翻译”一章。
您可能出于两个原因想要更改 Web 树中的默认翻译文本
- 因为您对某种表述方式有个人偏好，而使用相同语言的其他用户可能并不认同这种偏好。
- 因为您不同意您经常使用的语言的默认翻译，并认为应该为所有用户永久更改措辞。
如果第一个原因适用，您应该创建一个包含个性化翻译的扩展模块（请参阅“翻译定制模块”部分）。
如果第二个原因适用，您应该在webtrees论坛的“翻译”类别中讨论此翻译更改。如果达成共识，您可以使用 Weblate 翻译工具进行更改（参见“扩展翻译”一章）。
扩展模块的翻译直接在相应模块的 GitHub 目录中完成。相应模块的页面通常会提供README.md更多信息（请参阅“将模块文本翻译成其他语言”部分）。
改进本手册的建议
如果您发现本手册中有任何错误或发现缺少某些内容或需要更详细地描述，请开始输入，在 GenWiki 上注册为用户，然后自行编辑或添加任何不正确或缺失的部分。如果您不确定，您可以在平行的“讨论”页面上发表评论。
调整和开发自己的模块
GitHub [3]是webtrees的首选开发平台。编程是使用 PHP [4]的面向对象变体完成的，用户界面中的各个功能由 JavaScript [5]执行。
如果您想开发自己的模块，您应该熟悉以下主题
- 使用 PHP 进行面向对象编程
- 使用 JavaScript 编程
- Web 技术（HTML、CSS……）
- 使用 GitHub。
请注意，webtrees是在 GPL 3 许可证[6]下发布的，并且您的所有贡献都必须遵循相同的许可证。请确保您拥有所有贡献的权利。
软件架构和Webtrees的模块化结构
webtrees在版本 10 中使用了 Laravel 框架[7]。Laravel是一个遵循 MVC 模式的免费 PHP Web 框架。 “模型视图控制器”（MVC）架构方法提供了包含三个组件的软件架构
- 数据模型
- 演示文稿（英语版）和
- 程序控制（控制器）。
目标是实现灵活的程序设计，以方便以后的修改或扩展，并实现各个软件组件的可重用性。
webtrees数据模型很大程度上遵循 GEDCOM 标准中定义的结构。数据模型除其他内容外，还体现在数据库的表中。按照架构方法，不应 直接访问数据库，例如从扩展模块中的webtrees功能访问。
在webtrees 中，用户界面中的呈现很大程度上与提供要呈现的内容的功能分离。在很大程度上避免了在 PHP 代码和 HTML 代码中混合使用复杂的功能进行呈现，而这在使用 PHP 时原则上是可能的。 JavaScript仅用于用户界面中的功能，不适用于复杂的功能。特殊扩展模块是一个例外，例如用于显示地形节点边图的 TAM 模块。
在设计用户界面时，webtrees使用了Bootstrap [8] 5.2 版本。 Bootstrap 是一个免费的前端 CSS 框架。它包含基于 HTML 和 CSS 的排版、表单、按钮、表格、网格系统、导航和其他界面设计元素的设计模板以及其他可选的 JavaScript 扩展。
webtrees中的大多数功能都是在定义和实现 PHP 类的模块中实现的。这使得使用扩展模块添加或替换这些功能变得非常容易。 PHP 类中标记为“公共”的单个函数可以在扩展模块中被覆盖，从而导致功能被修改。
当然，您也可以直接在webtrees核心中更改该功能，方法是用修改后的文件替换相应的文件，而不是在扩展模块中用您自己的类覆盖该类。但是，这样的更改将在下次升级webtrees时被覆盖，因此如果您不小心并且没有在内核中直接详细记录这些更改并在每次升级后重建它们，则可能会丢失这些更改。因此，这样的改变是没有意义的。但是，如果您是一位经验丰富的软件开发人员，您可以通过 GitHub 上的拉取请求 提交对webtrees核心更改的建议。
Webtrees 数据库的结构
所有家谱数据和所有永久管理数据都存储在数据库中。 MySQL、MariaDB、SQLite、SQL Server 和 PostgreSQL 可以作为数据库的基础。对于生产系统，建议尽可能使用最新版本的 MariaDB。 SQLite 在许多测试安装中都有使用。确切的要求可以在原始页面上找到。
| 版本 | 地位 | MySQL | MariaDB | SQLite | SQL 服务器 | PostgreSQL |
|---|---|---|---|---|---|---|
| 2.1 | 稳定的 | ✅ 5.7+ | ✅ 10.2+ | ✅ 3.8.8+ | ✅ 2017年及以后 | ✅ 9.6+ |
| 2.2 | 稳定的 | ✅ 5.7+ | ✅ 10.3+ | ✅ 3.8.8+ | ✅ 2017年及以后 | ✅ 10.0+ |
| 2.2 开发 | 发展 | ✅ 5.7+ | ✅ 10.3+ | ✅ 3.8.8+ | ✅ 2017年及以后 | ✅ 10.0+ |
webtrees实例中的所有表都以data/config.ini.php文件中定义的公共前缀开头。前缀的默认值为“ wt_”。一些扩展模块还创建自己的数据库表；另一些人则将他们的数据存储在现有的表中。所有数据库表的完整表格描述如下。
| 表的名称 | 模块 | 表中的列 | 功能 |
|---|---|---|---|
| wt_block | 核 | block_id、block_order、gedcom_id、位置、module_name、user_id、xref | 家谱主页和用户个人主页上的区块 |
| wt_block_setting | 核 | ||
| wt_change | 核 | change_id、change_time、状态、gedcom_id、xref、old_gedcom、new_gedcom、user_id | 家谱数据变更日志 |
| wt_comments_likes | ？ | ||
| wt_dates | 核 | 日期 | |
| wt_default_resn | 核 | ||
| wt_families | 核 | ||
| wt_favorite | 核 | favorite_id、user_id、gedcom_id、xref、favorite_type、url、标题、注释 | |
| wt_gedcom | 核 | gedcom_id、gedcom_name、sort_order、chunk_data、已导入 | |
| wt_gedcom_chunk | 核 | ||
| wt_gedcom_setting | 核 | gedcom_id、setting_name、setting_value | |
| wt_gov_ids | 灶神星 | id、名称、gov_id | |
| wt_gov_标签 | 灶神星 | 键、gov_id、标签、语言、从、到、粘性 | |
| wt_gov_对象 | 灶神星 | gov_id、纬度、经度、版本 | |
| wt_gov_parents | 灶神星 | 键、gov_id、parent_id、从、到、粘性 | |
| wt_gov_types | 灶神星 | 键、gov_id、类型、从、到、粘性 | |
| wt_hit_counter | 核 | gedcom_id、page_name | |
| wt_individuals | 核 | ||
| wt_link | 核 | ||
| wt_log | 核 | ||
| wt_media | 核 | m_id、m_file、m_gedcom | |
| wt_media_faces | 面孔 | f_id、f_coordinates、f_m_id、f_m_filename、f_m_order、f_m_tree | |
| wt_media_文件 | 核 | ||
| wt_message | 核 | 消息 ID、发件人、IP 地址、用户 ID、主题、正文、创建 | |
| wt_模块 | 核 | 模块名称、状态、标签顺序、菜单顺序、侧边栏顺序、页脚顺序 | |
| wt_module_privacy | 核 | id、模块名称、设置名称、设置值 | |
| wt_module_setting | 核 | ||
| wt_name | 核 | ||
| wt_news | 核 | ||
| wt_新闻评论 | 消息 | comments_id、news_id、user_id、评论、已更新 | |
| wt_news_likes | 消息 | 新闻ID、用户ID | |
| wt_other | 核 | o_id、o_file、p_file、p_std_soundex、p_dm_soundex | |
| wt_placelinks | 核 | ||
| wt_places | 核 | ||
| wt_place_location | 核 | id、parent_id、地点、纬度、经度 | |
| wt_rel_families | 核 | f_id、f_file、f_gedcom、f_from | |
| wt_rel_individuals | 核 | ||
| wt_session | 核 | 会话 ID、会话时间、用户 ID、IP 地址 | |
| wt_site_setting | 核 | 设置名称、设置值 | |
| wt_sosa | 索萨 | ||
| wt_sources | 核 | s_id、s_file、s_name | |
| wt_用户 | 核 | 用户 ID、用户名、真实姓名、电子邮件、密码 | 用户管理 |
| wt_user_gedcom_setting | 核 | 用户 ID、gedcom ID、设置名称、设置值 | |
| wt_用户设置 | 核 |
|
| 简要描述上述所有数据库表并添加任何缺失的信息 |
|
当改变webtrees的版本时，数据库的结构也可能会改变。架构版本号已递增。一旦webtrees检测到请求的数据库当前版本大于当前可用的版本，数据库就会自动升级。切换回旧版本的数据库通常是不可能的。然而，数据库模式很长时间没有发生变化。
数据库表包含具有数据库当前模式版本的wt_site_setting条目。WT_SCHEMA_VERSION此值适用于 版本
- 1.7:37
- 2.1和2.2：45
如果扩展模块创建自己的数据库表，则它们必须管理各自的模式版本号和升级表本身的机制。
Webtrees 文件夹的结构
webtrees应用程序安装在服务器上可由 Web 服务器访问的目录中。
共有六个子文件夹，如下表所述。
| 目录 | 内容 |
|---|---|
/ | webtrees的根目录包含管理文件（例如 Composer）、favicon、文档（自述文件、许可证）以及可能的.htaccess。 |
/app | 这是构成webtrees核心的所有文件（例如所有模块）所在的位置。 |
/data | 此数据目录是唯一可由webtrees应用程序写入的目录；所有媒体文件、临时文件、缓存目录、导出的GEDCOM文件和配置文件config.ini.php都位于此处。 |
/modules_v4 | 所有扩展模块都位于此处。 |
/public | 这是内部使用的编辑器、CSS 文件、图标和中心 JavaScript 文件所在的位置。您还可以在此处将自己的媒体文件存储在不受webtrees防火墙保护的子文件夹中。 |
/ressources | 这是应用程序支持元素所在的位置，例如字符集、语言文件、图形、用户界面元素和报告模板（XML）。 |
/vendor | 所有第三方模块用到的库都收集在这个文件夹中。 |
该文件夹/data包含自动创建缓存文件的子目录/data/cache，以加快该过程。如果出现问题，可能是由于缓存中仍有旧版本的项目造成的，则可以删除此子文件夹。然后将自动重新创建该文件夹及其内容。缓存文件将在 100 天后自动删除。
默认情况下，所有使用的多媒体文件都位于子文件夹中/data/media。该子文件夹又可以构建成进一步的子文件夹。但是，建议避免使用这样的子文件夹结构，而是/data/media将所有文件平放在文件夹中，因为这样可以更轻松地查找和管理媒体文件。关于如何最好地命名媒体文件本身，存在不同的意见。有些人选择基于媒体文件标题的描述性名称，例如“baumgaertner_josef_geburtsurkunde.png”，其他人则更喜欢由webtrees自动生成的文件名，例如0eddebe2f70a3efc23feb9a945805d379bbc22c4.png。文件名中应避免使用空格和特殊字符以及变音符号和重音符号，以便文件在传输到其他系统时可以在所有操作系统下的所有文件系统中使用。
GitHub 上的结构
webtrees的源代码可以在Github 网站上找到。该存储库包含几个分支；例如版本分支 1.4、1.7 和 2.0 的最新版本。当前开发版本位于“主”分支。
开发环境和工具
webtrees的首选开发环境应该支持 GitHub。应用程序本身和几乎所有扩展模块的档案（存储库）都位于那里。因此，熟悉 GitHub 的功能非常重要。您可以克隆其他用户的档案并单独或一起开发它们。 GitHub 提供可安装在本地开发机器上的应用程序，并使本地文件与 GitHub 服务器上的文件保持同步。
PhpStorm可以作为开发工具使用。如果您声明将为 开源程序webtrees进行开发，您可以向制造商申请此强大工具的免费许可证。
|
| 描述 GitHub 和 PhpStorm 的最重要功能，并提供链接和徽标。 |
|
根据当前开发者版本搭建开发环境
webtrees Github 站点“主”分支中的开发版本不包含该文件夹/vendor。如果您想试用webtrees的当前开发版本或者为其开发自己的模块，则必须安装并运行Composer应用程序以在您的开发环境中创建此文件夹。命令是：
php composer.phar install
如果您想尝试自定义 JavaScript 函数，则需要/public在文件夹中创建更新。在这种情况下，使用以下命令 安装npm ：
npm install
要安装并编译在运行以下命令 package.json中找到的所有 JavaScript 模块webpack.mix
npm run production。
webtrees.js每次更改文件 时都必须再次运行此命令。
执照
webtrees使用 GPLv3 许可证（GNU 通用公共许可证版本 3）。[9]
GPL 许可证涵盖代码的分发。如果您分发webtree代码的修改版本，您也必须使用 GPLv3；这适用于webtrees模块的修改版本以及webtrees的完整分支。
因此，如果您为webtrees创建扩展模块，您也应该在 GPLv3 下发布它们。这可以在程序文件标题的注释中指出。在 GitHub 上发布时，您应该LICENSE.md在模块的根目录中创建一个包含许可证文本副本的文件。
编码风格和标准
webtrees遵循一些“ PHP 标准建议（PSR） ”。 PSR 是一种以建议形式编写的规范，由“PHP 框架互操作性组（ PHP FIG ）”发布。 PSR 仅建议使用PHP 进行编程，但不建议使用 PHP中的新功能。 PSR 的目标是实现组件的互操作性，使源代码具有普遍的可读性和可理解性，并标准化编程中已验证的概念。
| 数字 | 姓名 | 描述 | 关于网络树的状态 |
|---|---|---|---|
| PSR-0 | 自动加载标准 | 按照制造商、命名空间和类以及相关目录名称来命名组件，以便在 PHP 代码中使用组件时可以根据需要以统一的方式自动重新加载。 | 过时的；被 PSR-4 取代 |
| PSR-1 | 基本编码标准 | 通用编程风格，例如B.规范PHP代码开头的标签、使用的字符集（UTF-8）以及类/方法的命名；需要实现 PSR-0。 | 是的 |
| PSR-2 | 编码风格指南 | 指定代码中应在括号表达式、缩进和空格中何处使用换行符，或属性和方法的可见性；需要实现 PSR-1。 | 是的 |
| PSR-3 | 记录器接口 | 日志消息的统一接口、要使用的日志级别、异常、日志消息的格式以及在此环境中要使用的辅助类 | 未使用，但计划使用 |
| PSR-4 | 改进的自动加载 | PSR-0 自动加载规范的扩展 | 是的 |
| PSR-5 | PHP文档 | PHPDoc 语法的完整而正式的定义 | 不相关 |
| PSR-6 | 缓存接口 | 缓存概念的接口 | 是的 |
| PSR-7 | HTTP 消息接口 | HTTP 消息和 URI 处理的统一接口 | 是的 |
| PSR-8 | 可爱的界面 | 愚人节笑话 | 不相关 |
| PSR-9 | 安全披露 | 项目内安全相关信息的标准化（非活动 PSR） | ？ |
| PSR-10 | 安全公告 | 与公众沟通安全相关信息的标准化（非活跃 PSR） | ？ |
| PSR-11 | 容器接口 | 依赖注入容器接口 | 是的 |
| PSR-12 | 扩展编码风格指南 | 通过附加编程风格规则扩展 PSR-1 和 PSR-2 | 是的 |
| PSR-13 | 超媒体链接 | 关于超媒体链接统一呈现的规范。 | ？ |
| PSR-14 | 活动经理 | 事件实现的统一接口。 | ？ |
| PSR-15 | HTTP 处理程序 | HTTP 服务器请求处理程序和使用 HTTP 消息的 HTTP 服务器中间件组件的通用接口 | 是的 |
| PSR-16 | 简单缓存 | 简化缓存库的接口 | ？ |
| PSR-17 | HTTP 工厂 | 用于创建 PSR-7 兼容对象的工厂方法标准 | 是的 |
| PSR-18 | HTTP 客户端 | 发送和接收 HTTP 请求的标准 | ？ |
| PSR-19 | PHPDoc 标签 | PHPDoc 标签目录 | 不相关 |
| PSR-20 | 钟 | 访问时间的标准方法；在测试具有基于时间的副作用的行为时，实现测试期间的互操作性。 | ？ |
JavaScript 是按照“半标准” 在webtrees中编程的。
扩展模块示例
为了更轻松地开始编程扩展模块，有一些示例模块可以用作您自己的模块的模板。
| 模块 | 下载 | 描述 |
|---|---|---|
| 示例模块 | GitHub | 使用简单的基本模块，例如执行用户特定的翻译 |
| 示例模块自定义标签 | GitHub | 用户特定的 GEDCOM 标签定义 |
| 示例模块主题 | GitHub | 主题模块的扩展 |
| 示例模块中间件 | GitHub | 创建一个在每个 Web 请求之前和之后运行的中间件模块，例如阻止来自特定 IP 地址的请求或添加自定义 HTTP 标头。 |
| 示例模块页脚 | GitHub | 网站页脚的扩展 |
| 示例模块服务器配置 | GitHub | 更改 PHP 或数据库设置 |
除了示例模块之外，在开始webtrees编程时，研究其他扩展模块也是非常有帮助和指导意义的。如果您对单个功能有具体疑问，您也可以使用论坛。
翻译个性化调整模块
如果您想修改webtrees安装所选术语的翻译，可以在扩展模块中完成。通过这种方式，可以针对安装专门调整术语，而无需与翻译系统的所有其他用户达成共识。这也使得创建狗或马的血统系统成为可能，而不是创建人类祖先谱系的装置。示例模块显示如何添加自定义翻译。
扩展模块的基本结构
下面介绍扩展模块的组件和重要的基本功能原理。
该描述基于上表中链接的示例模块example-module-footer。为了遵循该示例，最好登录 GitHub 并在那里创建一个存储库。然后将示例文件复制到该目录中。必须注意的是，扩展模块的文件夹名称最多可以包含 30 个字符，因为文件夹名称存储在具有 32 个字符的数据库字段中，并且在前面和后面内部补充了下划线，这样就不会与webtrees核心的元素重叠。
模块.php
每个扩展模块都有一个启动模块module.php，可以自动找到并启动。这个模块看起来像这样
<?php/**
* 带有指向信息页面的链接的示例页脚。
*/声明（strict_types = 1 ）；命名空间 ExampleNamespace ；需要 __DIR__ 。 '/ExampleModuleFooter.php' ；返回 新的 ExampleModuleFooter ()；
该模块包含 PHP 代码，从文件扩展名可以看出。这里可以选择指定是否严格遵守变量和函数的类型。每个单独的文件中必须重复此定义。然后为模块定义一个特定的命名空间；命名空间可以自由选择；然后，所选命名空间必须以相同的形式出现在模块的所有 PHP 文件中。然后它将显示需要一个文件来进一步执行；这里是包含实际扩展模块及其定义的类的文件。这是ExampleModuleFooter.php扩展模块根目录中的文件。在最后一行，该类被ExampleModuleFooter()传递到一个新实例。这个类是在文件中定义的ExampleModuleFooter.php，接下来将进行描述。
带有扩展模块的类
|
| 通过示例描述扩展模块的其他基本结构元素 |
|
版本管理
webtrees可以检查已安装的扩展模块版本是否仍然是最新的。如果有必要，一旦有新版本可用，管理员就会在管理菜单中收到通知，以便网站管理员可以安装此新版本。
latest-version.txt为此，必须将名称为的文本文件添加 到扩展模块的根目录中，该文件始终包含扩展模块当前发布的版本号，例如字符串“2.1.15.0”。
在扩展模块的类定义中，即文件中的示例中，ExampleModuleFooter.php插入两个函数和一些字符串作为常量。可以从下面的代码中不加改变地获取这两个函数。当然，常数必须进行相应的调整；它们包含模块名称、模块的当前版本号以及对 GitHub 目录中具有当前版本号的文件的引用。
public const CUSTOM_TITLE = '模块英文名称' ; public const CUSTOM_MODULE = '模块的文件夹名称' ; public const CUSTOM_AUTHOR = '作者姓名' ; public const CUSTOM_GITHUB_USER = '作者的 GitHub 用户名' ;公共 const CUSTOM_WEBSITE = 'https://github.com/' 。 自我：：CUSTOM_GITHUB_USER 。 '/' 。 自我：：自定义模块 。 '/' ；公共 const CUSTOM_VERSION = '2.1.15.0' ;公共 const CUSTOM_LAST = 'https://raw.githubusercontent.com/' 。 自我：：CUSTOM_GITHUB_USER 。 '/' 。自我：：自定义模块 。 '/main/latest-version.txt' ；/**
* 此模块的版本。
*
* @return 字符串
*/ public function customModuleVersion () : string { return self :: CUSTOM_VERSION ; }/**
* 可以找到此模块当前版本号的 URL。
*
* @return 字符串
*/ public function customModuleLatestVersionUrl () : string { return self :: CUSTOM_LAST ; }
子文件夹/resources
扩展模块的子文件夹/ressources包含所有非 PHP 文件但运行模块所必需的文件。该文件夹通常分为多个子文件夹，每个子文件夹包含具有类似内容的文件。
/ressources/css：模块特定的页面设计（使用 CSS）/ressources/docs：用于文档的插图和文件/ressources/js：JavaScript 函数/ressources/lang：扩展模块中文本的翻译文件，以支持其他语言/ressources/views：显示用户界面页面（主要为 HTML，还有一些 PHP 和可能的一些 JavaScript）
/ressources可以将以下函数添加到扩展模块，以提供返回子文件夹引用的 功能。
/**
* 此模块将其资源存储在哪里？
*
* @返回字符串
*/公共 函数 resourcesFolder () : 字符串{返回 __DIR__ 。 目录分隔符 。 '资源' 。 目录分隔符；}
自述文件.md
每个扩展模块都包含所提供功能的简短英文描述。此描述是文件的一部分README.md。使用简单的Markdown代码进行格式化。最好的方法是从另一个扩展模块复制一个合理合适的描述，然后进行相应的调整。
将模块文本翻译成其他语言
扩展模块中使用的文本块以美式英语编写。使用I18N系统的功能进行翻译。有关webtrees翻译系统的一般信息可以在下面的第 7 章中找到。
待翻译的文本模块由翻译人员在线编辑，例如在网络服务poeditor.com中，或者也可以在系统中编辑po/mo，例如使用本地安装的程序Poedit。
有两种替代方法可以翻译成目标语言，即提供
- mo 翻译文件或
- PHP 翻译函数。
在第一种方法中，翻译人员拥有.po包含要翻译的文本模块及其翻译的文件。这些文件通常位于webtrees模块子目录中resources/lang。翻译完成后，翻译工具（例如 Poedit）会.po从文件创建机器可读的文件.mo。如果没有要翻译的新语言的文件，则可以.po从文件扩展名为 的示例文件复制.pot创建。所有原始文本均存储在此文件中。它也位于目录中resources/lang。每次模块文件发生影响要翻译的文本的更改后，都必须使用翻译工具重新生成此示例文件。所有需要翻译的文本模块都从模块文件中提取出来，并提供给.pot文件中的翻译人员。有时，对于翻译人员来说.mo，复制现有文件可能比复制带有空翻译的示例文件更容易。例如，如果已经有荷兰语翻译，最好选择并复制它作为新德语翻译的基础。
可以将以下函数添加到扩展模块以使用第一种方法提供翻译：
/**
* 附加/更新的翻译。
*
* @param 字符串 $language
*
* @return array<string,string>
*/ public function customTranslations ( string $language ) : array { $languageDirectory = $this -> resourcesFolder () . '长的' 。 目录分隔符；$文件 = $语言目录 。 $语言 。 '.mo' ；如果 （file_exists （$file ）） { return （new Translation （$file ））-> asArray （）; } 其他 {返回 []; } }
该函数由webtrees内核调用，以语言代码作为参数$language，例如de德语。该函数de.mo返回从关联文件获得的表，其中包含从内部美国英语到所请求的目标语言的翻译；例如像这样的行
"This is an example module." => "Dies ist ein Beispiel-Modul."
该变量$languageDirectory指定语言文件位于扩展模块的哪个子目录中。如果该目录中存在所请求语言的语言文件，例如de.mo，则将该.mo文件的内容转换为内部表格式并作为结果传递；否则将使用空表作为返回值。
|
| po/mo 格式的描述； poeditor.com 服务的简要说明；参考 php 表单而不是 mo/po。 |
|
如果您想使用第二种方法使用 PHP 翻译函数，该函数看起来有点不同；以下是一个例子：
/**
* 附加/更新的翻译。
*
* @param 字符串 $language
*
* @return 数组 <string,string>
*/ public function customTranslations ( string $language ) : array { switch ( $language ) { case 'ca' : case 'ca-ES' : $customTranslation = $this -> catalanTranslations ();休息;案例 'de' ：$customTranslation = $this- > germanTranslations （）;休息;案例 'zh-Hant' ：$customTranslation = $this -> chineseTraditionalTranslations ();休息;默认：$customTranslation = [];休息; }返回 $customTranslation ; }
对于提供的每种语言（例如“德语”为“de”）或每种语言变体（此处“加泰罗尼亚语”为“ca”或“ca-ES”，或“繁体中文”为“zh-Hant”），必须提供调用相应翻译功能的案例。对于每一种语言，都必须定义另一个函数。例如，它可能看起来像这样：
protected function germanTranslations () : array { // 注意复数和上下文相关的翻译中使用的特殊字符。return [ 'Example' => '示例' , '不要使用此过滤器' => '不要使用此过滤器' , '只有一个例子。' 。 I18N ::复数 。“有 %d 个例子。” => ‘只有一个例子。’ 。 I18N ::复数 。“有 %d 个例子。” ， ]；}
作为开发人员，选择第一种方法还是第二种方法取决于个人喜好。第一种方法允许翻译人员使用可能已经熟悉的翻译工具。翻译人员不需要熟悉PHP代码；他只能看到需要翻译的文本模块。此方法也适用于诸如 等网络工具poeditor.com。对于开发人员来说，第二种方法更为明显，因为它不需要任何额外的文件。在这里您可以轻松地将所有语言的所有文本模块保存在一个文件中，并确保一致使用。然而，翻译人员在这里直接看到程序代码，必须注意语法元素，例如每行末尾的逗号或赋值运算符“=>”，即使这些只是非常简单的 PHP 语言元素。
使用 CSS 定义页面元素的外观
所有页面元素都可以通过 CSS 受到影响。扩展模块创建的新元素应该适合该方案。一方面，它包含来自webtrees 所使用的引导系统的元素。其次，还有webtrees本身定义的 CSS 类，它们的名称都以“wt-”开头。这些类在webtrees.css文件中的其他地方定义。扩展模块的新类应该以模块特定的标识符开头，例如页脚模块的 CSS 类为“fm-”。
CSS 类的层次结构如下所示：
wt-global wt-theme-<THEME> wt-route-<ROUTE>
+---wt-header-wrapper
| +---wt-header-container
| +---wt-header-content
| +---wt-accessibility-links
| +---wt-site-logo
| +---wt-site-title
| +---wt-header-search
| | +---wt-header-search-form
| | +---wt-header-search-field
| | +---wt-header-search-button
| +---wt-secondary-navigation
| | +---wt-user-menu
| +---wt-primary-navigation
| +---wt-genealogy-menu
+---wt-main-wrapper
| +---wt-main-container
| +---wt-main-content
| +---wt-messages
| +---wt-page-title
| +---wt-page-options wt-page-options-xxxxx
| +---wt-page-content
+---wt-footers
+---wt-footer wt-footer-xxxxx
|
| 展示 CSS 类定义及其用法的示例。 |
|
测试
|
| 描述测试 Webtrees 新代码的过程。 |
|
如果您有兴趣在发布之前测试 webtrees 模块的拉取请求或在这种情况下执行回归测试，相应的模块开发人员会非常高兴。和他聯絡吧！一般来说，开发人员最好不要进行测试。测试人员不会通过开发人员的眼光来对待他的工作，因此更加公正。如果他们甚至能够创建自动化测试，任何开发人员都会兴奋不已。
使用“CSS 和 JS”模块进行调整
当需要对用户界面中元素的外观进行微小更改或更改此类元素的行为时，并不总是需要创建扩展模块。根据您的需要，您可以使用“ CSS 和 JS ”模块中适当的 JavaScript [10]函数或 CSS [11]指令来完成此操作。您可以在管理菜单的“模块/其他/CSS 和 JS”下找到此模块。
该模块有两个输入区域。第一个区域用于 CSS，集成在网站的头部，第二个区域用于 JavaScript，集成在网站的正文部分。 CSS 代码恰好被一对“<style>”和“</style>”指令包围，JavaScript 代码恰好被一对“<script>”和“</script>”指令包围。
示例 - 更好地利用屏幕空间
使用CSS您可以将屏幕列的宽度设置为最大值。
<样式>
。容器 { 最大宽度： 100 ％ }
。容器-lg { 最大宽度： 99 ％ }
</ style >
示例 - 根据历史事实调整颜色
CSS可用于修改显示“历史事实”时的背景颜色。
<样式>
[目录] 。wt-historic-fact > : first-child { background-color : #bfac99 ;}
[ dir ] . wt-historic-fact > : last-child { background-color : #d9c3ad ;}}
</ style >
示例 - 为近亲事件自定义颜色
CSS可用于修改显示“近亲事件”时的背景颜色。
<样式>
[目录] 。wt-relation-fact > : first-child { background-color : #b398b2 ;}
[ dir ] . wt-关系事实 > ：最后一个孩子 {背景颜色： #ccadcb ;}}
</样式>
示例 - 根据内容调整名称框
CSS可用于优化名称框的大小，以完整显示较长的内容。[12]
<样式>
。wt-块 。wt-chart-box {高度： 自动；}
。wt-chart-ancestors 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ；}
。wt-chart-后代 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ；}
。wt-chart-family-book 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4 rem ；}
。wt-图表-沙漏 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ；}
。wt-chart-pedigree-left 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ；}
。wt-chart-pedigree-right 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ；}
。wt-chart-pedigree-up 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ； 最小宽度： 18 rem ；}
。wt-chart-pedigree-down 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ； 最小宽度： 18 rem ；}
。wt-图表关系 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ；}
。wt-家庭成员 。wt-chart-box {边距： 2像素; 高度： 自动； 最小高度： 4.5 rem ；}}
</样式>
示例 - 突出显示姓氏
使用CSS，你可以在人物页面上强调姓氏，例如，通过使用大写字母和粗体打印：[13]
<样式>
。SURN { 文本转换： 大写； 字体粗细： 粗体； }
</样式>
示例 - 替换标准轮廓
-
女性
-
男性
-
各种各样的
-
未知
当某人没有分配个人图像时显示的默认轮廓是使用 CSS 设计的。它们被集成到 webtrees 核心的 CSS 文件中；要替换它们，您可以创建自己的替换图像，例如B.在webtrees/public/silhouettes目录的文件夹中。上面的示例图像可以自由使用，因为它们是使用DreamStudio.ai创建的。针对不同性别类型的轮廓，有以下 CSS 类
wt-individual-silhouette-mwt-individual-silhouette-f和wt-individuell-silhouette-u- 。
wt-individuell-silhouette-x。
替换图像可以具有以下文件名
silhouette-male.pngsilhouette-female.pngsilhouette-unknown.pngsilhouette-other.png。
“家庭”选项卡中的小轮廓不受这些变化的影响。扩展主题“现代”带来了自己的轮廓。如果需要，浏览器的开发工具将向您展示webtrees如何使用 CSS 类。
添加CSS代码如下：
<样式>
。wt-individual-silhouette-m {内容： url （/public/silhouettes/silhouette-male.png ）;}
。wt-individual-silhouette-f {内容： url （/public/silhouettes/silhouette-female.png ）;}
。wt-individual-silhouette-u {内容： url （/public/silhouettes/silhouette-unknown.png ）;}
。wt-individual-silhouette-x {内容： url （/public/silhouettes/silhouette-other.png ）; }
</ style >
示例 - 扩展名字
使用JavaScript，您可以确保在打开人物页面时始终展开人物的名字。
<脚本>
$ （'[id^="name-content-"]' ）。第一的（）。添加类（‘显示’ ）；
</script>
示例 - 在新窗口/选项卡中打开外部链接
|
| 请不要使用此示例！ |
|
此示例由于多种原因导致用户体验不佳
- 它会中断导航流程。在新选项卡或窗口中，没有“返回”按钮可以返回上一页。
- 用户被剥夺了控制权。用户可以随时使用 CTRL 键、鼠标右键或长按在新选项卡或窗口中打开链接。但是，没有办法在同一窗口中打开链接。
- 上网主要通过手机和平板电脑进行，部分手机和平板电脑的浏览器不使用标签页或窗口。管理这些设备上的“窗口”通常很麻烦。
但如果确实必须这样做，请将以下内容添加到 <body> 部分[14]
<脚本>
文档。addEventListener ( 'click' ，函数 （事件）{ if （ 事件。target。tagName === ' A' && ！事件。target。href 。包括（' // ' +位置。主机名））{事件。target。target = “ _ blank ” ;事件。target。rel = “ noopener ” ; } } ）；</script> 示例 - 记录的交叉引用
尽管webtrees使用交叉引用将注释中的 XREF（例如 @I2@）替换为适当的显示名称，但这并不那么灵活，而且不幸的是，如果您想在正文中引用记录而不插入绝对引用（此类绝对引用可以在 HTML 块的源代码中输入，如下所示：），则它无法在主页上的HTML块<a href="https://mustermann.genonline.de/tree/Mustermann/individual/I1/Max-Manfred-Mustermann">Max M. Mustermann</a>中工作。
下面描述的脚本在笔记的Markdown和HTML块中起作用。搜索 href 属性值以 #@ 开头，后跟字母 ('i': 'individual', 'f':'family', 's':'source', 'r':'repository', 'n':'note', 'l':'sharedPlace') 和 =@XREF@ 的 <a> 标签。还可以添加对另一个家谱的交叉引用。对于个人记录，附加的“+dia”可以额外显示一个图标，指向该人的“交互式沙漏图”。支持 两种 URL 变体（标准 URL 和漂亮 URL ）和不同的语言。
应用示例
- Markdown（例如在注释中）
- 交叉引用源记录：
[Quelle 1](#@s=@S1@) - 交叉引用人物页面并附加交互式沙漏图的链接：
[Max M. Mustermann](#@i=@I1@+dia)
- 交叉引用源记录：
- HTML 块
- 交叉引用另一个家谱：
<a href="#@i=@I1@tree2+dia">Lt. Cmndr. Joseph Allen jr.</a> - 要进入你可以
- 在编辑模式的文本字段中
Lt. Cmndr. Joseph Allen jr.，选择此文本，单击“插入链接”图标，然后#@i=@I1@tree2+dia在 URL 字段中输入，或者 - 单击“源代码”按钮切换到源代码模式，然后
<a href="#@i=@I1@tree2+dia">Lt. Cmndr. Joseph Allen jr.</a>输入。
- 在编辑模式的文本字段中
- 交叉引用另一个家谱：
|
| XREF 实际上是纯粹的内部标识符。在导入或导出家谱时，它们可能会发生变化。但是，webtrees在这些操作期间不会更改 XREF。然而，当家谱合并时，不可避免地会发生 XREF 变化，例如，如果要合并的两个家谱中都出现了 XREF。如果按照此处所述使用，将导致引用不正确。 |
|
必须在 <body> 部分输入以下脚本。
<script> function convertCrossReferenceLinks () { let rectype = { ' i ' : ' individual ' , 'f' : 'family' , 's' : 'source' , 'r' : 'repository' , 'n' : 'note' , 'l' : 'sharedPlace' };让分隔符= { 'default' ：{ 'path' ：'％2F' ，'option' ：'＆' }，'pretty' ：{ 'path' ：'/' ，'option' ：'？' } };让baseurl = document 。地点。href 。匹配（/^.+?\/ index\.php\?route=(?:%2F.+?)*%2Ftree%2F([^%\/#?]+)/ i）||文档。地点。href 。匹配（/^.+?\/tree\/([^\/#?]+)/i ）；如果（！baseurl ）{返回}让tree = baseurl [ 1 ]; baseurl = baseurl [ 0 ];让urlmode = （baseurl . indexOf （'index.php' ）> - 1 ？'default' ：'pretty' ）;让diatitle = $ （“a.dropdown-item.menu-chart-tree[role=menuitem]” ）。文本（）。修剪（）|| “交互式沙漏图” ；$ （'a[href^="#@"]' ）。each ( function ( index , element ){ let link = $ ( this ) .attr ( 'href' ) ; let m = link.match ( /^#@( [ ifsrnl ] )=@ ([^@]+)@ ( .* ) /i); if ( m ) {let type = m [ 1 ] .toLowerCase () ; let xref = m [ 2 ] ; let param = m [ 3 ] ; let dia = false; if ( param.match ( / \ + dia /i ) ) { dia = true ; param = param.replace(/\+dia/i,'')}let newtree = param ; let url = ( newtree ? baseurl.replace ( ` / tree / $ { tree } ` .replaceAll ( ' / ' ,分隔符[ urlmode ] .path ) , ` / tree / $ { newtree } ` . ' / ' ,分隔符[ urlmode ].路径)) : baseurl ); $ （这个）。attr ( 'href' , url +分隔符[ urlmode ].路径+ rectype [ type ] +分隔符[ urlmode ].路径+ xref )。attr （'目标' ，'_blank' ）；如果（类型== 'i' && dia ）{让diaurl = url 。replace ( “/tree/” . replaceAll ( '/' , 分隔符[ urlmode ] .path ), “/module/tree/Chart/” . replaceAll ( '/' , 分隔符[ urlmode ].path ) ) + 分隔符[ urlmode ].选项 + “xref=” + xref ; $ （这个）。之后（$ （' <a/>' ， { href ： diaurl ， class ： 'menu-chart-tree' ， target ： '_blank' ， title ： ` ${ diatitle } - ${ xref } ` + （ $ （this ）.text （） ？ '/' + $ （this ）.text （） ： '' ）， html ： ' ' }））；} } });
}$ （ 文档 ）。准备好（函数（） { convertCrossReferenceLinks （）;
}）;
</script>
示例 - 家谱标题成为主页的链接
为了快速切换到当前家谱的主页，该脚本将家谱标题转换为链接。只要家谱菜单可见，脚本就应该能够做到这一点。
必须在 <body> 部分输入以下脚本。
<脚本>
函数 setHomeLink （useMyPage ） {让 treename = $ （“ .wt-site-title” ）。文本（）。修剪（）;让 treelink = '' ; $ （“li.nav-item.menu-tree a.dropdown-item” ）。each ( function ( index ， elem ) { if ( elem . text . trim () == treename ) { treelink = elem . href + ( useMyPage && $ ( "li.nav-item.menu-logout" ). length > 0 ? '/my-page' : '' ); } });如果 （树形链接） { $ （“ .wt-site-title” ）。wrapInner （` <a href="${treelink}"> </a>` ）；} }$ （ 文档 ）。准备好（函数（） { setHomeLink （）;
}）;
</script>
如果您想根据登录状态选择链接到您自己的主页，则必须setHomeLink(1)使用参数集进行函数调用。
示例 - 使“查找和替换”菜单项不可见
搜索菜单包含搜索和替换选项（参见“编辑说明”一章中的“搜索菜单” ），编辑人员及更高级别的人员可以使用该选项。然而，如果使用不当，它可能会对家谱中的数据造成严重损害。如果所使用的用户帐户激活了“自动批准此用户所做的更改”选项，则尤其如此。更改将立即生效（请参阅“管理员指南”一章中的“编辑用户”）。因此，您可能想要隐藏此菜单项。
通过对所有无权访问“管理”菜单的用户隐藏菜单项，可以避免无意的误用。但是，仍然可以直接访问此功能的 URL，因为根据角色概念允许此功能。必须在模块的两个部分中都进行输入。
<样式>
a 。菜单搜索替换 { 显示：无;}
</样式>
<脚本>
$ （ 文档 ）。准备好（函数（） { 如果 （$ （“a.menu-admin” ）。长度 > 0 ） { $ （“a.menu-search-replace” ）。显示（）; } }）;
</script>
示例 - 标题菜单的扩展
使用 JavaScript，可以使用简单的条目来扩展标题菜单，而无需开发单独的模块。[15]
必须在 <body> 部分输入以下脚本。
<脚本>
jQuery （'.wt-用户菜单' ）。前置（'<li class="nav-item menu-wthb"><a class="nav-link" href="https://wiki.genealogy.net/Webtrees_Handbuch">Webtrees-Handbuch</a></li>' ）;
</script>
扩展翻译
webtrees中使用的术语和文本模块被翻译成多种不同的语言，并且不断添加新的语言。webtrees 的主要开发人员操作专用的Weblate实例来维护所有语言的翻译：translate.webtrees.net/projects/webtrees/webtrees-22/。此Weblate翻译系统需要用户注册。
I18N翻译系统
要翻译成美式英语的文本块可能还包含变量字符（如“％s”）或数字（如“％d”或“％.1f”）的占位符。这些占位符在翻译中相应地重复出现；如果顺序发生变化，则必须标记位置（例如，第一个参数为“%1$s”，第二个参数为“%2$s”）。
如果片段可以以单数和复数形式出现，则必须使用替代的 I18N 函数，该函数包含两个片段（上一节中显示了一个示例）。如果某种语言（例如波兰语）有几种复数形式，则翻译必须包含三个或更多文本块。如果某种语言（例如中文）没有复数形式，则仅提供一个文本块进行翻译。
当同一个词可以根据情况进行不同的翻译时，可以使用上下文相关的翻译。例如，“鱼”这个词既是名词又是动词。这两个词在英语中是相同的，但在其他语言中却有很大不同；此处“fish”与“fishing”相对。
为此，请使用函数translateContext()。
I18n::translateContext('verb', 'fish');
I18n::translateContext('noun', 'fish');
第一个参数仅包含一个标签作为对翻译者的提示，第二个参数是需要翻译的文本块。
要翻译的文本可能包含 HTML 标记或 Markdown 标记，这些标记必须与翻译中的完全一致。更复杂的 HTML 结构应放置在要翻译的文本之外，以便结构不会因可能的翻译错误而受到干扰。应避免使用一些特殊字符，例如撇号或引号；如果有必要，必须用前导字符“\”进行转义（参见上一节中的示例）。
|
| 仍需描述：I18N 的进一步文档和示例； I18N 复数形式包括指向相应 webtrees 文件的链接，每个语言都有复数概念；参考以语言典型形式输出的数字； |
|
关系术语的翻译
Webtrees中有一个单独的系统，用于将关系术语（例如“母亲前夫的叔叔”）从英语翻译成其他语言。目前用于英语、法语和斯洛伐克语。 Vesta 扩展模块为德语引入了另一种系统。
对于每个关系术语（例如“母亲”），有两个定义：
- 主格：“母亲”
- 所有格：“母亲的 %s”
要将此翻译系统扩展到其他语言，每种附加语言都需要一个维护者。对于每个关系术语（例如“嫂子”）都必须给出定义（此处例如Ehepartner->Schwester或Geschwister->Frau）。
时间或日期的翻译
Webtrees中任何地方的日期和时间格式都是可翻译的字符串。这使得每种语言都可以使用其首选格式。通过提供具有特定翻译的扩展模块，可以实现个性化适应。
一个例子是针对美国英语变体（en-US）的特殊翻译。它以 12 小时格式显示时间，并使用“月、日、年”格式表示日期：
'%H:%i:%s' => '%g:%i:%s %a',
'%j %F %Y' => '%F %j, %Y',
为了还显示星期几，您可以添加%D（缩写的星期几）或%l（完整的星期几）。
测试自创翻译
添加或更正翻译后，您必须等待webtrees的下一个版本，该版本将包含所有更改。因此，在下次升级webtrees时，更改后的翻译将可在您自己的服务器上使用。如果您想预先测试或使用翻译，我们建议您按照以下步骤操作
- 翻译更改几天后，可以在 GitHub webtrees
messages.po服务器上相应语言的语言子目录中找到最新的 PO 文件 ( ) ，例如，德语的 PO 文件位于github.com/fisharebest/webtrees/blob/main/resources/lang/de/messages.po。您还可以从 Weblate 网站translator.webtrees.net/projects/webtrees/webtrees-22/创建并下载此 PO 文件。要手动激活它，请将此文件放在服务器上相应的语言目录中，例如目录中。messages.po/resources/lang/de/ messages.php然后删除该目录下现有的文件；下次调用时，webtrees将根据更新的文件自动messages.po重新生成此文件。- 修改后的翻译应该经过彻底的测试。
首次创建一种新语言
如果要为webtrees引入一种新的语言，则必须集中存储一些语言属性，例如该语言的复数规则或书写方向。主要开发人员在webtrees核心中完成一次创建。/vendor/fisharebest/localization/src该目录中保存了语言的基本属性；例如，您可以在那里找到瑞士高地德语中数字的特殊定义。对特定语言的单词或日期排序的调整在文件中定义/app/Module/Language<Sprache>.php（对于德语，在 中/app/Module/LanguageGerman.php）。
如果您想在webtrees升级发布之前启用新语言进行测试，您需要将webtrees主要开发人员更新的一些目录或文件从webtrees GitHub 服务器复制到您自己的服务器。
/vendor/fisharebest/localization/src//app/Module/Language<Sprache>.php/app/Services/ModuleService.php
此外，您必须在自己的服务器上/resources/lang/<2 Zeichen Sprachkennung>/创建一个新的子目录（<2 Zeichen Sprachkennung>例如，“de”代表德语）。然后，您可以按照上面“测试您自己的翻译”部分中的说明进行操作。然后必须在webtrees管理菜单中激活所需的语言Module / Webseite / Sprachen，然后才能开始测试。
|
| 参考手册中的语言列表；参考语言代码列表/标准。 |
|
个别参考文献
- ↑ 文章Stacktrace。出处：维基百科，自由的百科全书。
- ↑ 页面FAQ - 500 error or blank page的翻译。
- ↑ 参见GitHub · Build and ship software on a single, collaborative platform · GitHub
- ↑ 文章PHP。出处：维基百科，自由的百科全书。
- ↑ 文章JavaScript。出处：维基百科，自由的百科全书。
- ↑ 文章GNU 通用公共许可证。出处：维基百科，自由的百科全书。
- ↑ 文章Laravel。出处：维基百科，自由的百科全书。
- ↑ 文章Bootstrap_(框架)。出处：维基百科，自由的百科全书。
- ↑ 文章GNU 通用公共许可证。出处：维基百科，自由的百科全书。
- ↑ 文章JavaScript。出处：维基百科，自由的百科全书。
- ↑ 文章层叠样式表。出处：维基百科，自由的百科全书。
- ↑ 参见论坛帖子“请求新功能 > 人员摘要框的几何形状”：Geometry of person's summary box - webtrees
- ↑ 参见论坛帖子“请求新功能 > 姓氏全大写”：Surnames full capitalization - webtrees
- ↑ 页面FAQ - How do I force external links to open in new tabs/windows?的翻译。
- ↑ 参见论坛帖子“2.0 版帮助 > 如何向二级菜单添加项目？”：Howto add a item to the secundary menu? - webtrees
- 网络树
- WT 待办事项
