README

Xarpages 是一个用于管理网站上页面的模块。其主要目标是提供一个严格的框架，使得网站设计师可以从访客的角度来构建网站。它强调层次化的页面结构，并与之对应的菜单和短网址。

Xarpages 不管理内容。它不直接持有或存储任何内容，而是依赖于其他模块提供内容。内容可以通过创建一个用于输入 HTML 的动态数据文本字段等简单方法提供。它也可能非常复杂，例如通过连接分类、查找故事、在特殊模板中渲染它们、引入与该页面相关的块以及通过扩展短网址来添加额外的动态内容。

页面

在 Xarpages 中，基本元素是页面。暂时不考虑页面类型，每个页面可能包含以下特征的组合

• 名称和描述
• 在层次结构中的位置
• 可选的动态数据字段，这些字段会输入到项目模板中
• 用于渲染页面内容的项模板
• 始终用于该页面的页面模板
• 始终显示该页面的主题
• 页面可以注册为模块别名
• 可以修改上述任何内容的自定义函数
• 可以扩展默认短网址处理的自定义短网址函数

由于所有这些属性都可以配置，因此可以定义给定页面的确切外观和行为。

许多上述属性是从层次结构中更低的页面继承的，即从页面所在的树根部分。例如，如果一个页面被设置为使用主题 X，那么其所有子页面，如果它们没有覆盖主题，也将显示在主题 X 中。

访问页面

每个页面都有一个唯一的数字页面 ID，或“pid”，可以使用 pid 访问。更方便访问页面的方式是使用当模块启用短网址时提供的层次结构。页面可以通过以下两种方式通过短网址访问

• 列出页面的完整层次路径，例如 /index.php/xarpages/about/staff/directors
• 命名已设置为模块别名的任何页面，例如 /index.php/directors

注意，如果“about”页面已注册为模块别名，则第一个示例可以缩短为 /index.php/about/staff/directors。

通过小心使用 mod_rewrite() 或等效方法，以及修改 Xaraya 全局选项，可以删除路径中的“index.php”部分，使页面结构几乎类似于静态网站。

自定义短网址

路径的组成部分是页面的名称。所以上面有一个名为“about”的页面，有一个名为“staff”的子页面，依此类推。如果路径扩展到真实页面的树之外，则自定义短网址函数将启动。扫描尽可能多的路径组件以确定要显示的页面后，通常将忽略任何未匹配的组件。然而，通过创建一个自定义 URL 解码函数并将其链接到页面，开发人员可以使用剩余的组件将它们输入到页面本身。

例如，如果员工名单中有多个董事，可以为每个董事创建一个单独的页面。因此，Jim可能有一个页面 /about/staff/directors/jim，其中包含他的联系信息。然而，如果处理几十个或几百个董事，这可能变得难以管理。解决此问题的方法之一是创建一个单独的页面 /about/staff/directors，然后创建一个自定义的URL解码函数，该函数读取任何额外的路径组件，并为该页面查找董事详情。附加路径可能是 'jim'、'jane' 或可能是数字ID - 这取决于开发者。

将此模块定制为进行解码和查找，与编写全新的模块之间的主要区别在于，此模块旨在进行定制；大多数艰苦的工作都为您做好了，只需进行少量的定制即可。更重要的是，由于专门为定制保留了API，因此无需覆盖您的更改即可升级该模块。

自定义函数

除了自定义短URL外，开发人员还可以向页面添加自定义处理函数。该函数将获得页面的所有数据，并且可以在将其传递到模板进行渲染之前选择修改这些数据。例如，该函数可以读取一些额外的GET参数，并使用这些参数从某个类别中检索文章。页面为页面定义的动态数据字段可以用作此自定义函数的参数 - 不必直接显示所有DD数据。

可以通过按顺序列出它们，并用分号分隔来串联自定义函数。

页面类型

可以定义尽可能多的不同页面类型。不同的页面类型允许将不同的模块连接到它们。它们还各自使用不同的模板“基础”。

页面状态

模板有三个主要状态

• 活跃的
• 非活跃的
• 模板
• 空的

通常仅显示活跃的和空页面。未来的增强可能将状态拉入权限，以便为某些用户组启用非活跃页面的显示。非活跃页面通常不显示。它们作为占位符存在，在页面开发期间或页面被撤回时。

空页面是指没有内容且无法直接导航到的页面。尝试导航到空页面将带您转到页面的第一个可显示子页面。它允许管理员设置“占位符”页面来定义一个部分，而无需占位符页面包含内容。

模板状态页面在创建新页面时用作模板。只需像平常一样创建模板页面，将其状态设置为“模板”，该页面将用于为未来创建的该类型页面提供默认值。目前，仅支持每种页面类型的一个模板页面（数据库中第一个出现的），但未来的增强将允许您从一系列模板中选择。

项目模板

每种页面类型都使用一个默认的项目模板，其名称与该类型相同。例如，页面类型“html”将使用默认的项目模板“page-html.xt”。任何特定的页面都可以通过名称请求更具体的模板。例如，类型为“html”的页面“directors”可以定义“contact”作为其模板，它来自主题“page-html-contact.xt”，如果更具体的模板不存在，则回退到“page-html.xt”。

导航块

已为使用此模块设计了导航块。该块应该能够支持所有类型的菜单，包括CSS、DHTML、嵌套列表、多级、分割菜单等。每个菜单块具有以下功能

• 多宿主标志。 这决定了根页面是否会在菜单中显示或隐藏（仅作为保留页面）。当隐藏时，菜单的顶级由根页面的所有子页面组成，即多个顶级页面。

• 当前页面源。 这决定了如何确定“当前页面”。它可以从缓存变量中来 - 通常在显示 xarpages 页面时创建，或者它可以固定到指定的页面。如果固定，则“默认页面”始终用作当前页面。

• 默认页面。 默认页面在两种情况下使用。首先，它可以作为一个固定页面，始终在块内显示为“当前”页面。其次，它可以作为当外部没有定义当前页面时的默认页面（即没有作为“current_pid”属性传递到块中，也没有通过模块在缓存中设置）。这是可选的。如果没有显示 xarpage 页面，并且没有设置默认页面，则块将不会显示。

• 根页面。 默认情况下，当块设置为“自动”时，它将显示当前页面所在的树下的完整菜单。您可能希望将其限制为仅某些树，即只有当当前 xarpages 页面位于某些界限内时，块才显示菜单。可以设置一个或多个根页面，并且在运行时将检查这些根页面以确保当前页面位于由这些根页面定义的树中。如果当前页面位于所有根页面之外，则块不会显示。如果没有定义根页面，则没有界限，并将为每个 xarpages 页面显示菜单。根页面的第二个功能是允许将菜单分成更小的块。例如，侧菜单可能显示五个子菜单之一，每个子菜单都是主页面结构的分支。只有当显示该菜单的页面时，才会显示相应的菜单。另一个例子可以是处理主菜单第一层的顶部菜单，以及处理从第2层开始的侧菜单。

• 最大层级。 与根页面一起使用，此设置定义菜单块将显示的最大层级数。低于该层级的所有内容都将被截断。

为此块设置了一个简单的文本嵌套列表模板，应能演示其工作原理。一个更复杂的例子显示了菜单如何格式化为侧菜单。可以通过将 ;css-side-menu1 作为块的“实例模板”来调用更复杂的模板。可以使用类似的菜单构建更多菜单。

如果您有可以包含在此模块中的通用菜单示例，请随时将其传递给作者。

权限

权限已设计为允许子编辑器管理内容，而无法修改页面的结构。

请参阅此模块文档集中的 privileges.txt 文件。

待办事项列表

请参阅此模块文档集中的 TODO.txt 文件以获取完整列表。

目前主要缺少的功能是一个导入/导出功能，这也可以用于设置初始示例页面，以及用于根据当前页面及其在层次结构中的位置显示层次菜单的块。

作者

Jason Judge

judgej@xaraya.com