七、制作主题（二） Anatomy of a theme

Where Themes Live

主题必须放在网站/Themes/目录下。

 

TheThemeMachine

TheThemeMachine是Orchard的内建主题，你能通过这个主题来学习Orhcard的主题。

 

TheThemeMachine被设计成整洁的、现代的并作为开发新主题的起始点。

 

Anatomy of a Theme

Manifest

每个主题都必须有一个manifest，manifest是一个叫Theme.txt的文本文件，位于主题目录中，

Name: The Theme Machine
Author: jowall, mibach, loudej, heskew
Description: Orchard Theme Machine is a flexible multi-zone theme that provides a solid foundation to build your site. It features 20 collapsible widget zones and is flexible enough to cover a wide range of layouts.
Version: 0.1
Tags: Awesome
Website: http://orchardproject.net
Zones: Header, Navigation, Featured, BeforeMain, AsideFirst, Messages, BeforeContent, Content, AfterContent, AsideSecond, AfterMain, TripelFirst, TripelSecond, TripelThird, FooterQuadFirst, FooterQuadSecond, FooterQuadThird, FooterQuadFourth, Footer

 

文件给出了主题一个友好的名字、描述、作者、标签等，Zones提供zone名称列表，可通过主题的布局和模板用于widgets。Zones是能加入到任何模板或布局的内容的容器。许多UI元素能注入到Zones，但最常见的是widgets。不是所有的zones都需要暴露在manifest中，仅仅是打算包含widget的zone。

 

这个图显示了19个zone，通常是一个网站需要的。

 

Icon or Thumbnail

Theme.png应该在主题中，图片最小应该是400*400像素，它会在主题库和管理面板中显示，通常使用主题显示的页面来作为缩略图。

 

Widget Zones Preview Image

随意地，主题能加入widget zones的预览图片，这个图片应该放在主题根目录命名为ThemeZonePreview.png,这个图片要400像素宽并显示不同的zone和zone的名称。

 

Static Resources

主题通常包含一些静态资源，像CSS，Javascritp,Images等，这个文件应放在下面文件夹中：

• CSS 应放在主题的Styles文件夹中。
• JavaScript 应该放在Scripts文件夹中，放入这个文件夹的所有脚本应该是自定义的并仅与你的主题关联，不是打算重用脚本。一些要重用的脚本应该包含在各个模块中，请查看Jquery的例子。
• Images 应该放在\Content\Images文件夹中，如果主题包含少数图片，可以将它们放在一起，如果图片很多，我们推荐把它们分别放入不同的子文件夹中。

注意：要想文件能使用，包含静态文件的文件夹都应该包含一个web.config的文件：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.web>
    <httpHandlers>
      <!-- iis6 - for any request in this location,
           return via managed static file handler -->
      <add path="*" verb="*" type="System.Web.StaticFileHandler" />
    </httpHandlers>
  </system.web>
  <system.webServer>
    <handlers accessPolicy="Script,Read">
      <!-- iis7 - for any request to a file exists on disk,
           return it via native http module.
           accessPolicy 'Script' is to allow for a managed 404 page. -->
      <add name="StaticFile" path="*" verb="*" modules="StaticFileModule"
           preCondition="integratedMode" resourceType="File"
           requireAccess="Read" />
    </handlers>
  </system.webServer>
</configuration>

 

Document

Document.cshtml一般在主题中看不到，因为很少需要重写它。多数主题仅在SafeMode主题中能用到这个文件的版本，在/Views下面。Document.cshtml文件负责body以外的html元素，意思就是它定义doctype、html、head元素，一些脚本和CSS链接。

 

Layouts

Layout是body元素内最外面的shape。例如：通常你定义的主widget zone。

一个主题能包含不限数量的layout文件，尽管目前只支持一个，包含在TheThemeMachine主题中叫Layout.cshtml。例如：一个主题能添加专门的layouts，像是Layout-Blog.cshtml或Layout-homepage.cshtml用于替换默认的blog或homepage，提供那些layout shape的扩展。注意这个layout的名字是Layout-{layout name}.cshtml，每个layout能有不同的zones，组织成不同样式。

 

Shape Templates

Orchard中，一个网页面呈现为html之前，它构建了shapes树。shapes是呈现给页面的灵活的对象。示例有：zones,menus,menu items,widgets.

每个shape能用一个能被主题重写的模板渲染，模板与shape有同样的名称。例如：如果 Menu.cshtml存在，它用于渲染menu shape。

TheThemeMachine主题有两个shape模板，BadgeOfHonor and Branding，Layout.cshtml中建立的并使用下面代码注入到Header和Footer zones中：

// Site name and link to the home page
WorkContext.Layout.Header.Add(New.Branding(), "5");
// Powered by Orchard
WorkContext.Layout.Footer.Add(New.BadgeOfHonor(), "5");

 

注意：模板用两种方式中的一种渲染shapes，另外模板能用代码定义渲染，定义一个有Shape特性的方法。请看CoreShapes.cs例子，通常在模块中完成，但主题同样也能做。

 

Item Templates

主题能重写  /Views/Items文件夹中的模板如何渲染content items，模板的名字应该叫Content-{content type name}.cshtml 或 Content-{content type name}.{display type}.cshtml。例如：重写blog posts如何被渲染的模板 应该是/Views/Items/Content-BlogPost.cshtml，重写blog posts summary如何被渲染的模板 应该是/Views/Items/Content-BlogPost.Summary.cshtml。

 

Part Templates

主题能重写content parts的渲染。这个公约与content item templates类似，part的模板必须放在/Views/Parts文件夹中，例如：能创建\Views\Parts\Comments.cshtml渲染comments。

 

Field Templates

Field的渲染也能被重写，尽管不是在field实例层，换句话说，你能重写text field看起来像什么，但不是具体的text field看起来像什么。要重写field 模板，需要在/Views/Fields中创建{field type name}.cshtml or {field type name}.{display type}.cshtml文件，例如：text fields的渲染能被\Views\Fields\Common.Text.cshtml模板重写。

 

Alternates

alternates 是一组关联shapes的templates或layout文件，使用能用主题控制不同内容类型如何被渲染。例如：你能使用alternates为主页应用一个layout文件但为subpages应用另一个layout文件，或者，你能使用alternates 以一种方式渲染page中的元素但blog post中的元素用另一种方式渲染。

Widget Overrides

widget也能在\Views named widget-{widget type}中创建一个模板来重写，例如：你能重写HTML widget的渲染并添加一个红色框包围这个内容，在Views文件夹中创建widget-htmlwidget.cshtml文件

<div style="border:1px red solid">
@Display(Model.Content)
<div>

 

 

Placement Files

主题能通过包含placement.info文件修改shapes渲染的位置，placement.info是一个xml文件：

<Placement>
    <!-- widgets -->
    <Place Parts_Blogs_BlogArchives="Content:before"/>
    <Place Parts_Blogs_RecentBlogPosts="Content:after"/>
    <!-- default positioning -->
    <Match ContentType="Blog">
        <Match DisplayType="Summary">
            <Place Parts_Blogs_Blog_Description="Content:before"
                   Parts_Blogs_Blog_BlogPostCount="Meta:3"/>
        </Match>
    </Match>
</Placement>

 

Markup

每个文件中的markup强制使用你选择的视图引擎。Orchard默认是Razor(.cshtml)引擎

模板中，Model 对象代表当前shape的渲染，意思是如果你使用有一个Message属性的message shape工作，你能使用@Model.Message显示Message属性。

重点是Orchard提供了Display来渲染shape，例如：如果你查看layout.cshtml文件，你能看到zones是如何被渲染的，调用  @Display(Model.Content)

最后，你也能看到一些模板中的调用：@Html.RegisterScript("mystyle.css") or @Html.RegisterScript("myscript.js")，这个调用是必要的，因为scripts、stylesheets是共享的资源。如果多个模块或同样的widget实例请求同样的文件，link或script元素就不会被渲染两次。

 

Themes with Code

多数主题仅由css,template,images等组成，没有代码除了模板中的一些简单的代码。更高级的主题，你可能想在代码中提供设置、创建自宝义shapes、或重写shapes。它可能像构建一个模块并包含到一个.csproj文件中，描述如何编译它包含的代码。