替代-Alternates
Alternates are optional variations of a shape that you can implement in a theme in order to customize
Alternates[ˈɔ:ltərnət]是形状的可选变体，您可以在主题中实现以便自定义
the rendering of the shape for specific cases.
特定情况下的形状渲染。
By using alternates, you can override which template is used to render content, based on the type (or other characteristic) of that content.
通过使用alternates，您可以根据该内容的类型（或其他特征）覆盖用于呈现内容的模板。
For example, you can use alternates to apply one layout file for the home page but another layout file for subpages.
例如，您可以使用替换为主页应用一个布局文件，但为子页面应用另一个布局文件。
Or you can use alternates to render tags one way when the tags are in a page but a different way when the tags are in a blog post.
或者，当tag位于页面中时，您可以使用alternates以一种方式呈现tag，但是当tag位于博客文章中时，可以使用不同的方式。
Alternates are particularly useful when you have different types of content and you want to customize the appearance of these different types of content.
当您有不同类型的内容并且您想要自定义这些不同类型的内容的外观时，Alternates特别有用。
The Orchard framework uses a naming convention to determine whether an alternate template is used for rendering content.
Orchard框架使用命名约定来确定是否使用备用模板来呈现内容。
The naming convention enables you to add template files that are used automatically, without requiring you to modify any code.
命名约定使您可以添加自动使用的模板文件，无需修改任何代码。
Naming Convention for Alternates
Alternates命名公约
Alternate shapes are named using the name of the base shape followed by a double underscore (__) and an ending that is specific to the alternate shape.
Alternate shapes使用基本形状的名称命名，后跟双下划线（__）并使用特定alternate形状的结尾。
For example, a Parts_Tags_ShowTags shape can have alternates with names such as Parts_Tags_ShowTags__BlogPost and Parts_Tags_ShowTags__Page.
例如，Parts_Tags_ShowTags形状可以替换名称，例如Parts_Tags_ShowTags__BlogPost和Parts_Tags_ShowTags__Page。
The part of the alternate name after the double underscore reflects when the shape is used, such as the current content type. (For more information about how shapes are named, see Accessing and Rendering Shapes.)
双下划线后面的Part的alternate name反映了使用形状的时间，例如当前内容类型。 （有关如何命名形状的更多信息，请参阅[访问和渲染形状]（访问和渲染形状）。）
Mapping a Template File to an Alternate
将模板文件映射到Alternate
To create a template file that maps to the corresponding shape name, you must name the template according to the following naming convention:
要创建映射到相应形状名称的模板文件，您必须根据以下命名约定命名模板：
-
Convert an underscore (
_) in the shape name to either a dot (.) or backslash (\) in the template name. -
将形状名称中的下划线（
_）转换为模板名称中的点（.）或反斜杠（\）。
A backslash indicates that the template resides in a subfolder.
反斜杠表示模板位于子文件夹中。
-
Convert a double underscore (
__) in the shape name to a hyphen (-). -
将形状名称中的双下划线（
__）转换为连字符（-）。 -
For any Display type value in the shape name, place the type name after a dot (
.) -
对于形状名称中的任何显示类型值，将类型名称放在点后面（
.）
at the end of the template name, such as Content-BlogPost.Summary.
在模板名称的末尾，例如Content-BlogPost.Summary。
All templates for alternates must reside in the Views folder.
替换的所有模板必须位于Views文件夹中。
The Views folder can be located either in the theme or in the module.
Views文件夹可以位于主题或模块中。
The following table shows which subfolders of Views to use for different types of templates.
下表显示了Views的哪些子文件夹用于不同类型的模板。
Shape type | Template Folder
-------------- | ----------------
Content item | Views\Items
Parts | Views\Parts
Fields | Views\Fields
EditorTemplate | Views\EditorTemplates\[template type folder] (For example, an EditorTemplate for a part is located at Views\EditorTemplates\Parts.)
All other | Views
For example, to create an alternate template for the Tags part, you can add a template to the MyTheme\Views\Parts folder.
例如，要为“Tags”部分创建备用模板，可以将模板添加到“MyTheme\Views\Parts”文件夹中。
However, because the underscore can be converted to either a dot (.) or backslash (\),
但是，因为下划线可以转换为点（.）或反斜杠（\\），
you can also create a template in the Views folder and add Parts. to the beginning of the name.
您还可以在Views文件夹中创建一个模板，并将Parts添加到名称的开头。
A template at either Views\Parts\Tags.ShowTags-BlogPost.cshtml or Views\Parts.Tags.ShowTags-BlogPost.cshtml will map to a shape named Parts_Tags_ShowTags__BlogPost.
`Views\Parts\Tags.ShowTags-BlogPost.cshtml或Views\Parts.Tags.ShowTags-BlogPost.cshtml中的模板将映射到名为Parts_Tags_ShowTags__BlogPost的形状。
If the Orchard framework cannot locate an alternate template that has the expected name,
如果Orchard框架找不到具有预期名称的alternate模板，
the default template will be used for those shapes.
默认模板将用于这些形状。
For example, if you do not create an alternate for showing tags, the default template for tags (located at Views\Parts\Tags.ShowTags.cshtml) is used.
例如，如果不创建显示tag的alternate，则使用标记的默认模板（位于Views\Parts\Tags.ShowTags.cshtml）。
The Orchard framework automatically creates many alternates that you can use in your application.
Orchard框架会自动创建许多可在应用程序中使用的alternate。
However, you can create templates for these alternate shapes.
但是，您可以为这些alternate形状创建模板。
The patterns for creating alternates are shown below, with examples of matching templates in parenthesis.
创建替代项的模式如下所示，括号中的匹配模板示例。
For Content shapes:
对于内容形状：
-
Content__[DisplayType]. (Example template:Content.Summary) -
Content__[ContentType]. (Example template:Content-BlogPost) -
Content__[Id]. (Example template:Content-42) -
Content_[DisplayType]__[ContentType]. (Example template:Content-BlogPost.Summary) -
Content_[DisplayType]__[Id]. (Example template:Content-42.Summary)
For Zone shapes:
对于 Zone 形状：
Zone__[ZoneName]. (Example template:Zone-SideBar)
For Navigation shapes (the new menu system since version 1.5):
对于 Navigation 形状（自1.5版以来的新菜单系统）：
-
MenuItemLink__[MenuName]. (Example template:MenuItemLink-main-menu) -
MenuItemLink__[ContentType]. (Examples template:MenuItemLink-ContentMenuItem,MenuItemLink-HtmlMenuItem,MenuItemLink-Blog)
For menu and menu item shapes:
对于菜单和菜单项形状：
-
Menu__[MenuName]. (Example template:Menu-main) -
MenuItem__[MenuName]. (Example template:MenuItem-main)
For local menu and local menu item shapes:
对于本地菜单和本地菜单项形状：
-
LocalMenu__[MenuName]. (Example template:LocalMenu-main) -
LocalMenuItem__[MenuName]. (Example template:LocalMenuItem-main)
For styles and resources:
对于样式和资源：
-
Style__[FileName] -
Resource__[FileName]
For widget shapes:
对于小部件形状：
-
Widget__[ZoneName]. (Example template:Widget-SideBar) -
Widget__[ContentType]. (Example template:Widget-BlogArchive)
For fields:
对于字段：
-
[ShapeType__FieldName]. (Example template:Fields\Common.Text-Teaser) -
[ShapeType__PartName]. (Example template:Fields\Common.Text-TeaserPart) -
[ShapeType]__[ContentType]__[PartName]. (Example template:Fields\Common.Text-Blog-TeaserPart) -
[ShapeType]__[PartName]__[FieldName]. (Example template:Fields\Common.Text-TeaserPart-Teaser) -
[ShapeType]__[ContentType]__[FieldName]. (Example template:Fields\Common.Text-Blog-Teaser) -
[ShapeType]__[ContentType]__[PartName]__[FieldName]. (Example template:Fields\Common.Text-Blog-TeaserPart-Teaser)
For content parts:
对于内容部分：
-
[ShapeType]__[Id]. (Example template:Parts\Common.Metadata-42) -
[ShapeType]__[ContentType]. (Example template:Parts\Common.Metadata-BlogPost)
You can use the Shape Tracing module to generate alternate templates through the Shape Tracing user interface. For more information, see Customizing Orchard using Designer Helper Tools.
您可以使用 Shape Tracing 模块通过 Shape Tracing 用户界面生成alternate模板。有关更多信息，请参阅[使用Designer帮助工具自定义Orchard]（Customizing-Orchard-using-Designer-Helper-Tools）。
URL and Widget Alternates
URL和小部件替代
The URL Alternates module enables you to create templates for specific URLs, and the Widget Alternates enables additional alternates for widgets of certain types and in specific zones.
URL Alternates 模块允许您为特定URL创建模板， Widget Alternates 为特定类型和特定区域的小部件启用其他替换。
You must enable the URL Alternates and Widget Alternates modules in order to use their features.
您必须启用 URL Alternates 和 Widget Alternates 模块才能使用它们的功能。
When enabled, alternate shapes are created based on the URL or the zone.
启用后，将根据URL或区域创建alternate形状。
These URL alternates are combined with the alternate patterns defined above.
这些URL替换项与上面定义的alternate模式相结合。
For example, the URL /my-blog/post-1 has alternates available for a MenuItem object
例如，URL“/my-blog/post-1”具有可用于“MenuItem”对象的alternate
with the following template names:
使用以下模板名称：
MenuItem-main
MenuItem-main-url-my-blog
MenuItem-main-url-my-blog-post-1
For the homepage, the following alternate is available:
对于主页，可以使用以下alternate：
MenuItem-main-url-homepage
Using this module, you can add URL-specific alternates to the Layout shape, such as the following:
使用此模块，您可以将特定于URL的替换项添加到 Layout 形状，如下所示：
Layout-url-homepage. This adds a specific layout for your About page of your site.
Creating a new layout file in your Themes/ThemeName/Views named Layout-url-About.cshtml would be picked up and used when viewing the /About page in your site.
在您的Themes/ThemeName/Views中创建名为Layout-url-About.cshtml的新布局文件将在您查看站点中的/About页面时被选中并使用。
Note: if the changes are only small, perhaps using alternate URL naming to the zone would be more appropriate.
注意：如果更改很小，可能使用alternateURL命名到区域会更合适。
You can enable URL Alternates by downloading the Designer Tools module from the Orchard Team
您可以通过从Orchard团队下载Designer工具模块来启用URLalternate
in the Orchard Modules Gallery:
在Orchard Modules Gallery中：
[Orchard Designer Tools]（http://gallery.orchardproject.net/List/Modules/Orchard.Module.Orchard.DesignerTools）
Similarly, widget alternates add new templates names that you can use to change the rendering
同样，窗口小部件会交替添加可用于更改渲染的新模板名称
of content parts when they are rendered as part of a specific widget type or inside of a
当内容部分呈现为特定窗口小部件类型或内部部分时的内容部分
specific zone. Shape Tracing
特定区域。 [形状追踪]（定制 - 果园使用 - 设计师 - 助手 - 工具）
(another feature of the Orchard Designer Tools
（[Orchard Designer Tools]的另一个特性（http://gallery.orchardproject.net/List/Modules/Orchard.Module.Orchard.DesignerTools）
module) is a great way to discover what alternates are available for any shape template on the page.
模块）是一种很好的方式来发现页面上任何形状模板可用的alternate项。
Here are some examples of widget alternate template names:
以下是小部件alternate模板名称的一些示例：
-
Parts.Common.Body-HtmlWidget-TripelSecond -
Parts.Common.Body-TripelSecond
Explicitly Designating an Alternate Template
明确指定alternate模板
In addition to using the automatically generated alternates, you can manually specify an alternate.
除了使用自动生成的alternate之外，您还可以手动指定alternate。
In a Placement.info file, you can specify which alternates are available for a content type.
在“Placement.info”文件中，您可以指定哪些alternate项可用于内容类型。
For example, to specify a different template (identified as Parts_Tags_ShowTags_BlogPost)
例如，指定不同的模板（标识为Parts_Tags_ShowTags_BlogPost）
for rendering the tags for blog posts, you can revise the Placement.info file for the
为了呈现博客文章的标签，你可以修改Placement.info文件
Orchard.Tags module to include an element that matches BlogPost types.
Orchard.Tags 模块包含一个匹配BlogPost类型的元素。
The following example shows the revised file.
以下示例显示了修订后的文件。
<Placement>
<Place Parts_Tags_Edit="Content:7"/>
<Match ContentType="BlogPost">
<Place Parts_Tags_ShowTags="Header:after.7;Alternate=ShowTags_BlogPost"/>
</Match>
<Match DisplayType="Detail">
<Place Parts_Tags_ShowTags="Header:after.7"/>
</Match>
<Match DisplayType="Summary">
<Place Parts_Tags_ShowTags="Header:after.7"/>
</Match>
</Placement>
The ordering of the Match elements is significant.
“Match”元素的排序很重要。
Only the first matched element is used to render the item.
只有第一个匹配的元素用于渲染项目。
In the example, placing the element for BlogPost below Detail and Summary means that ShowTags_BlogPost will not be used, even for BlogPost items, because the earlier elements match the item.
在示例中，将“Blog Post”元素放在“Detail”和“Summary”下面意味着“Show Tags Blog Post”将不会被使用，即使对于“BlogPost”项也是如此，因为早期的元素与项目匹配。
For more information about the Placement.info file, see Understanding placement.info.
有关Placement.info文件的更多信息，请参阅[了解placement.info]（了解-position-info）。
Alternates for MVC views
alternateMVC视图
Some modules in Orchard use regular MVC views to render the results of an action that was invoked on a custom controller. To customize the look of the pages produced by custom MVC controllers in Orchard, you need to add a version of the view file in your theme's Views folder.
Orchard中的某些模块使用常规MVC视图来呈现在自定义控制器上调用的操作的结果。要自定义Orchard中自定义MVC控制器生成的页面外观，您需要在主题的Views文件夹中添加一个版本的视图文件。
For example, if you want to customize the search results page of the Orchard Search module (Orchard.Search) you need to add a file in the following folder of your theme:
例如，如果要自定义Orchard Search模块（“Orchard.Search”）的搜索结果页面，则需要在主题的以下文件夹中添加文件：
/Themes/{Your theme}/Views/Orchard.Search/Search/Index.cshtml
This file will override the default view used by the Orchard.Search module.
该文件将覆盖Orchard.Search模块使用的默认视图。
The ViewEngine used by Orchard will look for the following pattern when resolving MVC views.
在解析MVC视图时，Orchard使用的ViewEngine将查找以下模式。
-
~/Themes/[Active theme]/Views/[Area]/[Controller]/[View].cshtml -
~/Themes/[Active theme]/Views/[Controller]/[View].cshtml -
~/Themes/[Active theme]/[Partial].cshtml -
~/Themes/[Active theme]/DisplayTemplates/[TemplateName].cshtml -
~/Themes/[Active theme]/EditorTemplates/[TemplateName].cshtml
Please be aware, any other convention that is normally supported in MVC is not supported within a theme, unless specified in the list above.
请注意，除非在上面的列表中指定，否则主题中不支持MVC中通常支持的任何其他约定。
Adding Alternates Through Code
通过代码添加alternate
In addition to methods described above for adding alternates, you can add alternates through code.
除了上述用于添加替换项的方法之外，您还可以通过代码添加替换项。
To designate an alternate through code, you create a class that implements the IShapeTableProvider interface.
要通过代码指定alternate，可以创建一个实现IShapeTableProvider接口的类。
Then, you add a handler for OnDisplaying for each type of shape that needs an alternate.
然后，为需要替换的每种类型的形状添加“OnDisplaying”的处理程序。
You specify the shape name as the parameter for the Describe method on the ShapeTableBuilder class.
您可以在ShapeTableBuilder类中将形状名称指定为Describe方法的参数。
Within the handler, you add any logic that you need to specify when the alternate is used.
在处理程序中，添加在使用alternate时需要指定的任何逻辑。
The following example first shows how to specify an alternate for shape named Content,
以下示例首先显示如何为名为Content的形状指定alternate，
but only when the user is on the home page.
但仅当用户在主页上时。
It also shows how to specify an alternate for a shape named Parts_Tags_ShowTags
它还显示了如何为名为Parts_Tags_ShowTags的形状指定alternate
when the DisplayType is Summary.
当DisplayType是Summary时。
using Orchard;
using Orchard.ContentManagement;
using Orchard.DisplayManagement.Descriptors;
namespace MyTheme.ShapeProviders
{
public class ExampleShapeProvider : IShapeTableProvider
{
private readonly IWorkContextAccessor _workContextAccessor;
public ExampleShapeProvider(IWorkContextAccessor workContextAccessor)
{
_workContextAccessor = workContextAccessor;
}
public void Discover(ShapeTableBuilder builder)
{
builder.Describe("Content")
.OnDisplaying(displaying =>
{
if (displaying.ShapeMetadata.DisplayType == "Detail")
{
ContentItem contentItem = displaying.Shape.ContentItem;
if (_workContextAccessor.GetContext().CurrentSite.HomePage
.EndsWith(';' + contentItem.Id.ToString()))
{
displaying.ShapeMetadata.Alternates
.Add("Content__HomePage");
}
}
});
builder.Describe("Parts_Tags_ShowTags")
.OnDisplaying(displaying =>
{
if (displaying.ShapeMetadata.DisplayType == "Summary")
{
displaying.ShapeMetadata.Alternates
.Add("Tags_ShowTags_Summary");
}
});
}
}
}