Refer to resources inside views
Using CSS styling, JavaScript logic, and jQuery support is a part of the process of developing your MVC views. This way, your custom functionality is styled and presented according to your requirements. When developing your MVC views, you can add JavaScript, CSS, and Sitefinity CMS built-in jQuery resources.
You must use the @Html.Script method to register scripts and @Html.StyleSheet in MVC views. @Html is an ASP.NET MVC helper method. For more information, see HTMLHelper methods. Script and StyleSheet methods are part of the helper methods inside the Telerik.Sitefinity.Frontend assembly.
Throughout this article, you can refer to the following view that demonstrates how to add resources to your views:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
// All helper methods are located under this namespace |
|
@using Telerik.Sitefinity.Frontend.Mvc.Helpers; |
|
|
|
// ***** Use sections ***** |
|
|
|
// Add Sitefinity's built-in jQuery to section "top" |
|
@Html.Script(ScriptRef.JQuery, "top") |
|
|
|
// Add login-status.js from the current widget assembly or resource package to section "bottom" |
|
@Html.Script(Url.WidgetContent("Mvc/Scripts/LoginStatus/login-status.js"), "bottom") |
|
|
|
// Add styles.min.css from the Bootstrap resource package to section "head" |
|
@Html.StyleSheet(Url.WidgetContent("~/ResourcePackages/Bootstrap/assets/dist/css/styles.min.css"), "head") |
|
|
|
// This will fail if section "fakeSection" does not really exist but this overload will not throw exception |
|
@Html.Script(ScriptRef.JQuery, "fakeSection", false) |
|
|
|
// ***** Use Sitefinity CMS built-in jQuery ***** |
|
|
|
// Add Sitefinity's built-in jQuery to section "top" |
|
@Html.Script(ScriptRef.JQuery, "top") |
|
|
|
// ***** Take advantage of the routing when registering resources ***** |
|
|
|
// Widget resource is searched in resource package first (e.g. "ResourcePackages/Bootstrap/js/sample.init.js") |
|
// Then in the widget assembly folder and then SitefinityWebApp folder |
|
@Html.Script(Url.WidgetContent("js/sample.init.js")) |
|
|
|
@Html.StyleSheet(Url.WidgetContent("Mvc/Scripts/Navigation.js")) |
|
|
|
// ***** Register scripts and style sheets from another assembly ***** |
|
|
|
// Add jquery.ui.map.js from the "Telerik.Sitefinity.Resources assembly" which has "Telerik.Sitefinity.Resources.Reference" type |
|
@Html.Script(Url.EmbeddedResource("Telerik.Sitefinity.Resources.Reference", "Telerik.Sitefinity.Resources.Scripts.jquery.ui.map.js")) |
|
|
|
@Html.StyleSheet(Url.EmbeddedResource("Telerik.Sitefinity.Resources.Reference", "Telerik.Sitefinity.Resources.Styles.all.css")) |
Use HTML sections to refer to resources
You can use HTML sections to specify where on your page you want to render the referenced resources. Placing your resources in the correct sections of the page is important. For example, a good practice is to place your stylesheets in the <head> tag and the scripts before the closing <body> tag.
Sitefinity CMS provides you with full control on where to place your resources. For this purpose, you can register sections in your layout files. Thus, when using the @Html.Section method, you can define where to insert your resource on the page. After you create a section, it is replaced by all referenced resources for that section. Both the @Html.Script and @Html.StyleSheet helper methods have an overload for accepting a section name. So, regardless of the position of the resources, registered via the @Html.Script and @Html.StyleSheet helper methods, they will be rendered inside this section. This means that you can register resources above the section and still have them in the correct place when the page is rendered. In the ReferToResourcesInsideViews.cshtml view, you can see how to register two scripts and a style sheet in the top, bottom, and head sections.
NOTE: If you specify a section name and this section does not exist, or is renamed or deleted, an exception is thrown.
You can also use an overload of the helper method to suppress the exception throwing. To do this, set the value of the third parameter of the overload method to "false".
The following sections are available out-of-the-box with the Bootstrap resource package:
head
Just before the closing head tagtop
Just after the opening body tagbottom
Just before the closing body tag
IMPORTANT: We recommend not to remove these sections.
Use Sitefinity CMS built-in jQuery
You can use the Sitefinity CMS built-in jQuery library to further customize the default Sitefinity CMS functionality without the need to refer or register jQuery as an additional resource.
In the ReferToResourcesInsideViews.cshtml example above, you can see how to register the jQuery in the MVC view using the ScriptRef enumerator.
ScriptRef is a special enumerator class, part of the Sitefinity CMS assembly with several predefined libraries. Some of the libraries that you can register are JQuery, MicrosoftAjax, KendoAll, JQueryCookie, JQueryFancyBox.
Register other JavaScript libraries
To correctly include a version of jQuery that is different than the built-in version, perform the following:
- Use the
jQuery.noConflict() method to wrap your custom JavaScript logic.
- Include a specific resource.
In the ReferToResourcesInsideViews.cshtml example, you can see how to include a specific script and stylesheet.
Take advantage of routing when registering resources
If you want to reference out-of-the-box MVC control resources, you need to provide the path to the script or stylesheet. Sitefinity CMS first searches for the script or stylesheet in the resource packages folder. If your views are using one of the Bootstrap resource package, we recommend to add the script or stylesheet files nearer to the views.
In the ReferToResourcesInsideViews.cshtml example, in case you based your page on the Bootstrap package, Sitefinity CMS searches the ~/ResourcePackages/Bootstrap/js/sample.init.jswith biggest priority.
Next, Sitefinity CMS looks for the resource in the widget assembly folder and finally in the SitefinityWebApp folder.
In the ReferToResourcesInsideViews.cshtml example, you can see how to refer to a resource from the MVC folder - "Navigation.js".
Register scripts and stylesheets from another assembly
If you placed your script in another assembly, you can register it in the MVC view using the @Url.EmbeddedResource helper. @Url is an ASP.NET MVC helper method. For more information, see UrlHelper methods.
EmbeddedResource method is part of the helper methods inside the Telerik.Sitefinity.Frontend assembly.
In the ReferToResourcesInsideViews.cshtml example, you register the embedded script and stylesheet with two parameters for the script and stylesheet using the @UrlEmbeddedResource helper method (type) that provides the full namespace to the class and the full assembly name of the script.
The scripts and stylesheets also have to be added to the AssemblyInfo.cs file of the external assembly. To do that in Visual Studio:
- Open your external assembly.
- Expand the Properties node.
- Open the
AssemblyInfo.cs file.
- Add your stylesheets and scripts following these examples.
- For scripts:
[assembly: System.Web.UI.WebResource("Telerik.Sitefinity.Resources.Scripts.jquery.ui.map.js", "text/javascript", PerformSubstitution = true)]
- For stylesheets:
[assembly: System.Web.UI.WebResource("Telerik.Sitefinity.Resources.Styles.all.css", "text/css", PerformSubstitution = true)]
Refer to resources in hybrid pages
In case your scenario requires both MVC and WebForms widgets on your page, you create a hybrid page and page template, based on the MVC Bootstrap template. For more information, see For developers: Hybrid MVC mode.
Your widgets may require scripts to be loaded on the page, so you use the @Html.Script helper method in the MVC view to call a specific script and place it in a specific section of the view. For example, @Html.Script(ScriptRef.JQuery, "bottom").
However, when working with hybrid pages, you need to use an additional parameter to the @Html.Script helper method that defines the location where the script is added to the page. This parameter is tryUseScriptManager, provided by the Telerik.Sitefinity.Frontend.Mvc.Helpers.ResourceHelper method. You need to explicitly state:
- The location (section), for example, “top”
- The value of the parameter, for example, false
NOTE: By default, the value is set to true. If you leave the value to true, the script is added to the <form> section
Following are a few examples of how you can use the @Html.Script helper method:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
// // When you do not specify the tryUseScriptManager value, it defaults to true and script will be placed in the page after the <form> tag. |
|
@Html.Script(Url.WidgetContent("/Mvc/Views/Scripter/myscript.js"), true) |
|
|
|
// When you set the parameter to false, the script is added to wherever you place the widget on the page. |
|
@Html.Script(Url.EmbeddedResource("Telerik.Sitefinity.Resources.Reference", "Telerik.Sitefinity.Resources.Scripts.jquery.ba-outside-events.min.js"), false) |
|
|
|
// When you specify the location and set the parameter to false, the script is added to this specific section on the page. |
|
@Html.Script(Url.WidgetContent("/Mvc/Views/Scripter/header.js"), "bottom", false, false) |
Add attributes to scripts and stylesheets
There are several overloads of the Html.Script and Html.Stylesheet helpers that allow you to add attributes to the script and the stylesheet links. Attributes are passed as the last parameter of type List<KeyValuePair<string, string>>. To use this C# type you need the following using at the start of your code file:
@using System.Collections.Generic;
Keep in mind that if you set tryUseScriptManager to true, the attributes will not be added to your scripts, since they are handled by the page script manager. Following are examples of each overload:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
// The first parameter is the script path, the second parameter is a list of html attributes as key value pairs. |
|
@Html.Script(Url.WidgetContent("/Mvc/Views/Scripter/myscript.js"), new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("defer", "defer")}) |
|
|
|
// The first parameter is the script path, the second is the section in which to render the script, the third indicates whether to throw an exception if the specified section does not exist, and the last parameter is a list of html attributes as key value pairs. |
|
@Html.Script(Url.WidgetContent("/Mvc/Views/Scripter/myscript.js"), "head", true, new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("defer", "defer")}) |
|
|
|
// The first parameter is the script path, the second is the section in which to render the script, the third indicates whether to throw an exception if the specified section does not exist, the fourth parameter indicates whether to use script manager (if it exists) when registering a JavaScript reference. Keep in mind that there is a limitation, if you use script manager, attributes will not be added to the script reference. The last parameter is a list of html attributes as key value pairs. |
|
@Html.Script(Url.WidgetContent("/Mvc/Views/Scripter/myscript.js"), "head", true, false, new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("defer", "defer")}) |
|
|
|
// The first parameter is the script reference, the second parameter is a list of html attributes as key value pairs. |
|
@Html.Script(ScriptRef.JQuery, new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("defer", "defer")}) |
|
|
|
// The first parameter is the script reference, the second parameter is the section in which you want to render the reference, the third parameter is a list of html attributes as key value pairs. |
|
@Html.Script(ScriptRef.JQuery, "head", new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("defer", "defer")}) |
|
|
|
// The first parameter is the script reference, the second is the section in which to render the script, the third parameters indicates whether to throw an exception if the specified section does not exist, the fourth parameter indicates whether to use script manager (if it exists) when registering a JavaScript reference. Keep in mind that there is a limitation, if you use script manager, attributes will not be added to the script reference. The last parameter is a list of html attributes as key value pairs. |
|
@Html.Script(ScriptRef.JQuery, "head", false, false, new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("defer", "defer")}) |
|
|
|
// The first parameter is the path to the CSS file, the second parameter is the section in which the stylesheet will be rendered, the last parameter is a list of html attributes as key value pairs. |
|
@Html.StyleSheet(Url.WidgetContent("~/ResourcePackages/Bootstrap4/assets/dist/css/mycss.css"), new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("data-index-number", "12314")}) |
|
|
|
// The first parameter is the path to the CSS file, the second parameter is the section in which the stylesheet will be rendered, the last parameter is a list of html attributes as key value pairs. |
|
@Html.StyleSheet(Url.WidgetContent("~/ResourcePackages/Bootstrap4/assets/dist/css/mycss.css"),"head", false, new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("data-index-number", "12314")}) |
Load minified scripts
By default, Sitefinity CMS serves a minified version of all built-in scripts that are referenced in the out of the box widgets. To make debugging easier, a source map is included alongside each minified script.
NOTE: If you have configured your project in debug mode from the web.config file, for example by specifying <compilation debug="true"..., Sitefinity CMS automatically loads the non-minified version of the referenced scripts.
Load minified scripts in custom widgets
You can take advantage of Sitefinity's ability to automatically load minified scripts when developing your custom widgets. By default, if you provide a minified version of the script files you are referencing in your custom widgets, Sitefinity CMS will load it automatically.
For example, if in your custom MVC widget view you are loading a script to display the user's login status, like:
@Html.Script(Url.WidgetContent("Mvc/Scripts/LoginStatus/login-status.js"), "bottom")
when Sitefinity CMS renders the widget on the page, it will search the respective folder, containing the scripts for your custom widget view, in this case Mvc/Scripts/LoginStatus for a login-status.min.js file. If a file is found, Sitefinity CMS loads it, instead of the non-minified version, that is referenced in the widget code.
For more information on how you can produce minified versions of your custom widget JavaScript files, refer to Create minified versions of custom widget scripts.