ResourceLinks control
The central control for the theming of Sitefinity backend is ResourceLinks control located in the [Telerik.Sitefinity.Web.UI] namespace. The purpose of the control is to link to resources and it should be used exclusively for adding any resources that could be different in various themes
ResourceLinks control usage
The ResourceLinks controls can be used in many cases:
- When an embedded resource should be linked - JavaScript, CSS, Images
- When a JavaScript Library should be used - Prototype, MooTools, jQuery
Defining ResourceLinks control
The ResourceLinks control is of type Telerik.Sitefinity.Web.UI.ResourceLinks.
Here is an example on how it could be defined in a template:
<%@ Register Assembly="Telerik.Sitefinity" Namespace="Telerik.Sitefinity.Web.UI" TagPrefix="sf" %>
<sf:ResourceLinks id="resourceLinks" runat="server">
<sf:ResourceFile Name="CSS/Layout.css" />
</sf:ResourceLinks>
The ResourceLinks control contains collection of links in form of ResourceFile(s). This means that you can include several references with a single ResourceLinks controls. The code above will register the given CSS file from the appropriate theme folder located in the CSS folder of the theme folder. One can register any number of resources inside of one control, by simply adding additional Resource elements, as demonstrated here:
<sf:ResourceLinks id="resourceLinks" runat="server">
<sf:ResourceFile Name="CSS/Layout.css" />
<sf:ResourceFile Name="CSS/dashboard.css" />
</sf:ResourceLinks>
The control itself will make sure to load the files from the proper theme folder.
In the previous two examples we have seen how to use embedded resources with the ResourceLinks control. To illustrate the point, by default, the two resources from the last example will register the following css files:
- Telerik.Sitefinity.Resources.Themes.Default.CSS.Layout.css and
- Telerik.Sitefinity.Resources.Themes.Default.CSS.dashboard.css
That is, if the currently selected theme is
Default. If the user changes the theme to
Black, then the control would register following files:
- Telerik.Sitefinity.Resources.Themes.Black.CSS.Layout.css and
- Telerik.Sitefinity.Resources.Themes.Black.CSS.dashboard.css
ResourceLinks control also provides an option to work with external themes. Let us consider following declaration:
<sf:ResourceLinks id="resourceLinks" runat="server" UseEmbeddedThemes="false">
<sf:ResourceFile Name="CSS/Layout.css" />
<sf:ResourceFile Name="CSS/dashboard.css" />
</sf:ResourceLinks>
Since we have set the UseEmbeddedThemes property to false, this time ResourceLinks will register following two css files:
- ~/SitefinityExternal/Themes/Default/CSS/Layout.css and
- ~/SitefinityExternal/Themes/Default/CSS/dashboard.css
Similarily to the embedded themes, with external themes the actual path depends on the currently selected theme. So if user has configured Sitefinity to use
Black theme, the control would register following two files:
- ~/SitefinityExternal/Themes/Black/CSS/Layout.css and
- ~/SitefinityExternal/Themes/Black/CSS/dashboard.css
Sometimes, however, we may wish to use files that are same for all themes. Perhaps some kind of a reset style sheet or global layout style sheet file. So far we have seen that ResourceLinks control will always automatically generate the paths to resources based on the themes, which would mean that we would have to copy these files in every theme folder. There is a better solution though, by using the static property. When we declare resource as static, the resource will always be retrieved from the same location. Let us consider following example:
<sf:ResourceLinks id="resourceLinks" runat="server" UseEmbeddedThemes="false">
<sf:ResourceFile Name="~/SitefinityExternal/Layout.css" Static="True" />
<sf:ResourceFile Name="CSS/dashboard.css" />
</sf:ResourceLinks>
Notice how we have made the first resource static and provided the virtual path to it. Regardless of the currently selected theme, the first file will always be retrieved from the root/SitefinityExternal/Layout.css location. Another interesting observation is that we can mix themable and static files inside of one ResourceLinks collection of resources (take a look at the second resource). A very similar approach can also be used for the embedded resources:
<sf:ResourceLinks id="resourceLinks" runat="server">
<sf:Resource Name="Telerik/Sitefinity/Resources/Layout.css" Static="True" />
<sf:ResourceFile Name="CSS/dashboard.css" />
</sf:ResourceLinks>
Finally, it may be helpful to note following two characteristics about ResourceLinks:
- Resources will be registered in the order in which they are declared
- Sitefinity will determine the type of resource based on its extension and therefore generate the proper markup
Using ResoruceLinks control to insert JavaScript Libraries
You can insert the following JavaScript Libraries:
- jQuery
- MooTools
- Prototype
Here is an example with jQuery:
<sitefinity:ResourceLinks ID="resourcesLinks" runat="server">
<sitefinity:ResourceFile JavaScriptLibrary="JQuery"></sitefinity:ResourceFile>
</sitefinity:ResourceLinks>
Since this example is adding jQuery reference to the current page/template, jQuery can be used in the following way afterwards:
..
<script type="text/javascript">
$("body").addClass("sfNoSidebar");
$("p > ul").addClass("red");
</script>
..
Needless to say, apart from theming the backend, you can use this control for theming your own user controls and pages.