Skip to content

了解placement.info文件-Understanding the placement.info File

In a CMS such as Orchard, content is built as a composition of arbitrary parts. For example, a blog post is an assemblage of a route (Autoroute Part), title (Title part), contents (Body part), tags (Tags part), comments (Comment part), and a few additional technical parts (Common and PublishLater).

在诸如Orchard的CMS中，内容被构建为任意部分的组合。例如，博客文章是路由（Autoroute Part），标题（Title part），内容（Body part），标签（Tags part），评论（Comment part）的集合。 ，以及一些额外的technical parts（Common和PublishLater）。

To get a template to render an object like this, you could access each of these parts explicitly and render them; that's a scenario that would work in Orchard. But that would not handle well the unpredictable changes in the definition of the content types that are the essence of a CMS. For example, what if the administrator of the site downloaded a star rating module and added the rating part to posts? If the layout for the whole item were explicitly defined, you would have to explicitly modify the template.

要获取模板来渲染这样的Blog对象，您可以显式访问这些Parts并渲染它们;在Orchard,这是一个可以工作的场景。但这不能很好地处理CMS内容的内容类型定义中不可预测的变化。例如，如果网站管理员下载了星级模块并将评级部分添加到帖子中，该怎么办？如果明确定义了整个项目的布局，则必须显式修改模板。

In Orchard, this isn't necessary, and adding a new part and displaying it can be done without touching the templates. This is possible because Orchard separates layout into two stages:

在Orchard中，这不是必需的，添加新Part并显示它，可以在不触及模板的情况下完成。因为Orchard将布局分为两个阶段：

  • Rendering (performed by generating HTML from templates or shape methods) and

  • 渲染（通过从模板或形状方法生成HTML）和

  • Placement (done through the Placement.info file).

  • 放置（通过Placement.info文件完成）。

This way, parts can not only specify their default rendering, which can be overridden by themes, they can also specify where they prefer to be rendered relative to other parts (which can also be overridden by themes).

这样，Parts不仅可以指定其默认渲染（可以被主题覆盖），还可以指定他们相对于其他Parts（也可以被主题覆盖）更喜欢渲染的位置。

Best Practice: Avoid creating templates for high level Content Types.

最佳实践：避免为高级内容类型创建模板。

Instead, create templates for Content Parts and Content Fields then change their order with placement.

而是为内容部件和内容字段创建模板，然后使用展示位置更改其顺序。

Specifying placement using the Placement.info file is the subject of this article.

使用Placement.info文件指定位置是本文的主题。

Summary

摘要

  • Placement works only on parts (and some fields) of content items.

  • 展示位置仅适用于内容项的部分（和某些字段）。

  • Place element attributes are shape names (not alternate names).

  • Place元素属性是形状名称（不是alternate名称）。

  • Find shape names via shape tracing or in driver code.

  • 通过形状跟踪或驱动程序代码查找形状名称。

  • Match element attributes include ContentType, DisplayType, and Path.

  • 匹配元素属性包括ContentType，DisplayType和Path。

  • Path can include a * to represent all child paths.

  • 路径可以包含一个“*”来表示所有子路径。

  • Override module placements in the theme

  • 覆盖主题中的模块放置

Syntax Overview

语法概述

<Placement>

    [ <Match scope> ]

        <Place Shape_Name="order[;alternate][;wrapper][;shape]" />

    [ </Match> ]

</Placement>
ScopeContentType="value" | ContentPart="value" | DisplayType="value" | Path="value"
Orderposition | suppress
Positionzone_name[ : { int | after | before } ][ .int ][ ...n ]
Suppress -
Alternate;Alternate=alternate_name
Wrapper;Wrapper=wrapper_name
Shape;Shape=new_shape_name

The Placement.info File

Placement.info文件

If you look at the files in your Orchard website, you'll see that most modules and themes have a Placement.info file at their root. This is an XML file that specifies the placement of each part of a content item.

如果查看Orchard网站中的文件，您会发现大多数模块和主题的根目录都有一个“Placement.info”文件。这是一个XML文件，用于指定内容项的每个部分的位置。

The following example shows an example of a placement file. (It's based on the Placement.info file that comes with Orchard.Tags.)

以下示例显示了放置文件的示例。 （它基于Orchard.Tags附带的Placement.info文件。） 

<Placement>

    <Place Parts_Tags_Edit="Content:7"/>

    <Match DisplayType="Detail">

        <Place Parts_Tags_ShowTags="Header:after.7"/>

    </Match>

    <Match DisplayType="Summary">

        <Place Parts_Tags_ShowTags="Header:after.7"/>

    </Match>

    <Match DisplayType="SummaryAdmin">

        <Place Parts_Tags_ShowTags="-"/>

    </Match>

</Placement>

Placement Scope

放置范围

A placement file acts at the Content Item level. This means that you can use it to reorder the display of the parts of anything that is a content item (blog posts, pages, comments, custom items, widgets, elements, etc.), but not necessarily arbitrary shapes. If a shape that is not representing a content part needs placement, it is up to you to provide a placement mechanism for that shape.

展示位置文件在内容项(ContentItem)级别起作用。这意味着您可以使用它来重新排序任何内容项（博客文章，页面，注释，自定义项，窗口小部件，元素等）的部分显示，但不一定是任意形状。如果不表示内容部件的形状需要放置，则由您来为该形状提供放置机制。

Comments

注释

Comments can be included in the Placement.info using normal <!-- comment --> syntax.

注释可以使用普通的<!-- comment -->语法包含在Placement.info中。

The "Placement" Element

“放置”元素

The Placement element must be present at the root of the Placement.info document. It is a simple container.

Placement元素必须出现在Placement.info文档的根目录中。这是一个简单的容器。

"Place" Element

“放置”元素

The Place element is the main entity in a Placement.info file. It can have any number of attributes, although it's recommended for readability to have only one shape place defined per Place element. For additional shapes, you can add more Place tags, one per line.

Place元素是Placement.info文件中的主要实体。它可以具有任意数量的属性，但建议可读性只为每个“Place”元素定义一个形状位置。对于其他形状，您可以添加更多Place标签，每行一个。

Single shape per line example:

每行单个形状示例： 

<Place Parts_TagCloud="Content:5"/>

<Place Parts_TagCloud_Edit="Content:7"/>

Multiple shapes per line example:

每行多个形状示例： 

<Place Parts_TagCloud="Content:5" Parts_TagCloud_Edit="Content:7"/>

Shape Name Attribute

形状名称属性

Each attribute of a Place element is the name of a shape (such as Parts_Tags_ShowTags), as defined from the relevant part driver, and has the placement as the value. To determine the shapes that are part of the display of a given content item, you can read the code for the part drivers. Or a simpler method might be to enable the Shape Tracing module and use the shape debugging tools to examine the model.

“Place”元素的每个属性都是一个形状的名称（例如Parts_Tags_ShowTags），由相关的零件驱动程序定义，并具有作为值的位置。要确定作为给定内容项显示的一部分的形状，您可以阅读部件驱动程序的代码。或者更简单的方法可能是启用“形状跟踪”模块并使用形状调试工具来检查模型。

The name of the attribute can be any shape name (but not an alternate name; use Match to specialize placement instead).

属性的名称可以是任何形状名称（但不是alternate名称;请使用“Match”来特殊化放置）。

There are also special extensions for certain fields so that placement can be targeted at specific field instances.

某些字段还有特殊扩展名，因此可以将放置定位到特定的字段实例。

For example, the following placement will display text fields named "Occupation" at the start of the local content zone:

例如，以下展示位置将在 local 内容区域的开头显示名为“Occupation”的文本字段： 

<Place Fields_Common_Text-Occupation="Content:before"/>

Note for field developers: you may give your own fields this capability by using a special override of ContentShape in your driver that provides the differentiator (the part after the dash in the attribute name). See the Text Field driver for example, or read Creating a Custom Field Type.

对于现场开发人员的注意事项：您可以通过在驱动程序中使用ContentShape的特殊覆盖来为您自己的字段提供此功能，该覆盖提供差异化​​（属性名称中破折号后面的部分）。例如，请参阅文本字段驱动程序，或阅读[创建自定义字段类型]（Creating-a-custom-field-type）。

You can learn more about shapes and alternates in these topics: Accessing and Rendering Shapes and Alternates.

您可以在以下主题中了解有关形状和替换的更多信息：[访问和渲染形状]（访问和渲染形状）和[替代]（替代）。

The value itself is split into a zone name, a colon, and then a position.

值本身被拆分为区域名称，冒号，然后是位置。

Local Zone Placement

本地区放置

By default the zone name will specify a local zone.

默认情况下，区域名称将指定本地区域。

If you look inside that shape template you will see that there are several locally defined zones. Razor templates would use @Display(Model.Content) to display the content zone for example.

如果您查看该形状模板，您将看到有几个本地定义的区域。 Razor模板将使用@Display（Model.Content）来显示内容区域。

Usually you will find a zones like Header, Meta, Content, or Footer available for placement.

通常你会发现一个像“Header”，“Meta”，“Content”或“Footer”这样的区域可供放置。

Example local zone placement:

本地区域放置示例： 

<Place Parts_TagCloud="Content:5"/>

Top-Level Zone Placement

顶级区域布局

The zone name can also specify a top-level zone. Top level zones are defined in the Layout.cshtml view.

区域名称还可以指定顶级区域。顶级区域在 Layout.cshtml 视图中定义。

In the case of a top-level zone, the zone name must begin with a slash, e.g. /AsideFirst

对于顶级区域，区域名称必须以斜杠开头，例如/AsideFirst

Example top-level zone placement:

顶级区域放置示例： 

<Place Parts_TagCloud="/AsideFirst:5"/>

Placement Order

放置顺序

The position is defined using a dotted notation. It can be a single number (1, 5, 10, 42) or it can be a succession of numbers separated by a dot (1.2, 1.52.3, etc.). The order will be determined starting from the first number, and if multiple positions have the same first number, using the subsequent numbers. This way, 1 comes before 2.4.5, and 2.4.5 comes before 2.10.

使用点分表示法定义位置。它可以是单个数字（1,5,10,42），也可以是由点（1.2,1.52.3等）分隔的连续数字。将从第一个数字开始确定订单，如果多个位置具有相同的第一个数字，则使用后续数字。这样，1在2.4.5之前，2.4.5在2.10之前。

You can also use before and after qualifiers to position shapes before or after a certain position. For example, Header:after positions the shape at the next available position following everything that's defined using numeric positions.

您还可以使用before和after限定符在某个位置之前或之后定位形状。例如，Header：after将形状定位在使用数字位置定义的所有内容之后的下一个可用位置。（就是说使用了after限定符后，出现的位置肯定在只使用了数字的后面）

Placement order examples:

展示位置示例： 

<!-- A weight of 5 in local content zone 在本地内容区域中的权重为5 -->

<Place Parts_TagCloud="Content:5"/>



<!-- Before the top-level header zone 在顶层标题区域之前-->

<Place Parts_TagCloud="/Header:Before"/>



<!-- After the top-level asidefirst zone with a weight of .5 在顶层asidefirst区域之后，权重为5。 -->

<Place Parts_TagCloud="/AsideFirst:After.5"/>

Suppression

抑制

There is a special value, "-", that suppresses the shape rendering instead of sending it to a zone.

有一个特殊值“ - ”，它会抑制形状渲染，而不是将其发送到区域。

Suppression examples:

抑制示例： 

<!-- Suppress Parts_TagCloud everywhere 到处抑制Parts_TagCloud-->

<Place Parts_TagCloud="-"/>



<!-- Suppress Parts_TagCloud in views using SummaryAdmin 在使用SummaryAdmin视图中取消Parts_TagCloud-->

<Match DisplayType="SummaryAdmin">

  <Place Parts_TagCloud="-"/>

</Match>

Alternate

Alternate

Added in v1.1

_在v1.1_中添加

Use alternate to specify shape alternates from Place elements.

使用alternate指定来自Place元素的形状替换。

For example, if you want to enable a theme author to specify a different template for rendering the tags for blog posts, you can do the following:

例如，如果要使主题作者指定用于呈现博客帖子的标记的其他模板，则可以执行以下操作： 

<Match ContentType="BlogPost">

  <Place

    Parts_Tags_ShowTags="Header:1;Alternate=Parts_Tags_ShowTags_BlogPost"/>

</Match>

A theme author can then provide a Parts/Tags.ShowTags.BlogPost.cshtml file that customizes the display of tags for blog posts.

然后，主题作者可以提供_Parts/Tags.ShowTags.BlogPost.cshtml_文件，该文件自定义博客帖子的标签显示。

Wrapper

包装

Added in v1.1

_在v1.1_中添加

Use 'wrapper' from Place elements to wrap an extra shape around the original shape.

使用Place元素中的'wrapper'在原始形状周围包裹一个额外的形状。

Similarly, you can provide a wrapper as part of the placement (Header:after;Wrapper=Wrapper_GreenDiv).

同样，您可以提供一个包装器作为放置的一部分（Header：after; Wrapper = Wrapper_GreenDiv）。

Using a wrapper enables wrapping content with a cshtml markup. Here is a 3 step example showing how to add a div around the Html Widget to enable css styling of the widget.

使用包装器可以使用cshtml标记包装内容。这是一个3步示例，显示如何在Html Widget周围添加div以启用窗口小部件的CSS样式。

In Placement.info :

在Placement.info中： 

<Match ContentType="Widget">

    <Place Parts_Common_Body="Content:5;Wrapper=Wrapper_HtmlContent" />

</Match>

If you just put the wrapper without specifying 'Content:5' the body part will not show up. By adding Content:5 it specifies which zone to render the part in.

如果您只是在不指定'Content：5'的情况下放置包装器，则身体部位将不会显示。通过添加“Content：5”，它指定了渲染Part的区域。

After modifying your Placement.info the Shape Tracing module Shape tab will show your wrapper location at the bottom. It will be: ~/Themes/{yourTheme}/Views/Wrapper.HtmlContent.cshtml.

修改Placement.info后，Shape Tracing模块Shape选项卡将在底部显示您的包装器位置。它将是：~/Themes/{yourTheme}/Views/Wrapper.HtmlContent.cshtml。

Create this file and put the following text in it:

创建此文件并在其中放入以下文本： 

<div class="htmlWrapperContent">

    @Model.Html

</div>

This will enable you to target the wrapper from site.css like this:

这将使您能够从site.css中定位包装器，如下所示： 

.htmlWrapperContent {

    background-color: #94CCE7;

}

Shape

形状

Added in v1.1

_在v1.1_中添加

Use 'shape' from Place elements to rename the shape.

使用Place元素中的'shape'重命名形状。

For example:

例如： 

<Place Parts_Common_Body="Content:5;Header:after;

Shape=IPreferToCallThoseStickersForSomeReason" />

"Match" Element

“Match”元素

Match elements let you scope a particular set of Place tags. Match elements can have the following scope attributes: Match元素允许您对一组特定的Place标记进行范围调整。 Match元素可以具有以下范围属性：

  • DisplayType

  • ContentType

  • ContentPart

  • Path Match elements can be nested.

DisplayType

显示类型

Scopes the contained Place tags to a specific display type.

将“Place”标记包含在特定显示类型的范围内。

You can define your own custom display types when developing content parts or fields, but Orchard uses standard ones:

您可以在开发内容部件或字段时定义自己的自定义显示类型，但Orchard使用标准部件或字段：

  • Detail - Used when rendering a single item, e.g. a blog post

  • Detail - 在渲染单个项目时使用，例如一篇博文 *

  • Summary - Used when rendering a list of items

  • Summary - 在呈现项目列表时使用 *

  • SummaryAdmin - Used when rending a list of items in the admin panel

  • SummaryAdmin - 在管理面板中重新列出项目列表时使用 *

Some modules have registered their own such as:

有些模块已注册了自己的模块，例如：

  • Layout - Added in v1.9 - Used by the Orchard.Layouts module when an element is rendering a shape like a ContentField or ContentItem

  • 布局 - 在v1.9中添加_ - 当元素呈现类似ContentField或ContentItem的形状时，由Orchard.Layouts模块使用 *

  • Design - Added in v1.9 - Used by the Orchard.Layouts module when showing an element in the admin panel

  • 设计 - 在v1.9中添加_ - 在管理面板中显示元素时由Orchard.Layouts模块使用 *

ContentType

内容类型

Scopes the contained Place tags to a specific content type or stereotype.

将“Place”标记包含在特定内容类型或构造型的范围内。

  • Content Type - Such as BlogPost or Page

  • 内容类型 - 例如BlogPost或Page *

  • Stereotype - Added in v1.1 - Such as Widget

  • 刻板印象 - 在v1.1_中添加_ - 例如Widget *

ContentPart

ContentPart

The ContentPart attribute was added in v1.7.2

_在UNIX1.1中添加了ContentPart属性

Scopes the contained Place tags to a specific content part such as BodyPart or LayoutPart. An example use of this scoping is to hide the title part in a content item with a LayoutPart.

将Place标记包含在特定内容部分中，例如BodyPart或LayoutPart。此范围的一个示例用法是使用“LayoutPart”隐藏内容项中的标题部分。

In Placement.info :

<Match ContentPart="LayoutPart">

    <Place Parts_Title="-" />

</Match>

<Match DisplayType="Layout">

    <Place Parts_Title="Header:0" />

</Match>

The first Match hides the TitlePart for content items that contain a LayoutPart. The second Match then displays the TitlePart when DisplayType is Layout. The title will only be displayed if the TitlePart element has been placed on the canvas.

第一个Match为包含LayoutPart的内容项隐藏TitlePart。当DisplayType是Layout时，第二个Match显示TitlePart。只有在画布上放置了TitlePart元素时才会显示标题。

Path

路径

The Path attribute was added in v1.1.

_在v1.1_中添加了Path属性。

Scopes the contained Place tags to a specific path or to a path and its children.

将“Place”标记包含在特定路径或路径及其子项中。

  • Specific Path - For example, Path="/About" enables changes that only affect the About page (assuming you have one)

  • 特定路径 - 例如，Path =“/ About”启用仅影响About页面的更改（假设您有一个） *

  • Path and it's Children - For example, Path="/MyBlog/*" affects everything that is under the path MyBlog, such as Myblog or MyBlog/FirstPost.

  • Path和它的子项 - 例如，Path =“/MyBlog/*”会影响_MyBlog_路径下的所有内容，例如_Myblog_ or MyBlog/FirstPost。

Overriding Placement

覆盖放置

A module should define default placements for the parts and fields it provides by having a Placement.info file at the root of the module's directory.

模块应该通过在模块目录的根目录下放置一个“Placement.info”文件来定义它提供的部分和字段的默认放置。

Without a placement your parts and fields will not appear on the page. By supplying a default you take the burden away from theme developers to configure your module and you make it easy for them to copy sections over to customise them. Consider the various DisplayTypes your parts and fields may be viewed and provide sensible defaults.

如果没有展示位置，您的Part和字段将不会显示在页面上。通过提供默认设置，您可以减轻主题开发人员的负担，从而配置模块，并使他们可以轻松地复制部分以进行自定义。考虑各种DisplayTypes可以查看您的Part和字段，并提供合理的默认值。

That default placement can be overridden by any theme by placing a Placement.info file in the root of the theme directory.

通过在主题目录的根目录中放置一个Placement.info文件，任何主题都可以覆盖该默认位置。

The current theme's placement will win over that of any module.

当前主题的位置将胜过任何模块。