The Skin System - for Portal builders

From Sense/Net Wiki
Jump to: navigation, search
  • 100%
  • 6.0
  • Enterprise
  • Community
  • Planned

Overview

Sense/Net provides a skin system for customizing pages appearance. Builders may define new skins with custom styles, javascript functions and control templates that allow the looks of individual pages to be fully customized. Default stylesheets, javascripts, Content Views and Field Control Templates can be overridden in a skin. Referencing any of the previous types of items in a page is acheived through special controls and functions.

Details

The mechanism of our Skin System is based upon a fallback logic. You can override the Global template files of the /Root/Global folder in the Skin folders using the same folder/file structure. Find more information about this structure on the Skin anatomy page.

Referencing Content Views

There are four ways to reference Content Views:

  • absolute addressing with explicit reference (ie.: /Root/Global/contentviews/User/Browse.ascx)
  • absolute addressing without type info (ie.: /Root/Global/contentviews)
  • relative addressing with explicit reference (ie.: $skin/contentviews/User/Browse.ascx)
  • relative addressing without type info (ie.: $skin/contentviews)

When picking a Content View in a portlet absolute addressing with explicite reference is used by default.

Selecting a Content View in a portlet

The selected path can however be edited to allow relative addressing and addressing without type info. You can use relative addressing using the $skin prefix when a Content View is overridden in a skin so that changing the skin of the current page triggers a change in the used Content View as well. When using the most general referencing (or by not giving a Content View path at all) resolution of the Content View goes through a line of probing paths.

The following example shows how the browse Content View for a Car content is resolved when using $skin/contentviews path in a Content viewer Portlet:

  • /Root/{currentskin}/contentviews/Car/Browse.ascx is probed. If it does not exist then
  • /Root/{currentskin}/contentviews/Browse.ascx is probed. If it does not exist then
  • /Root/Global/contentviews/Car/Browse.ascx is probed. If it does not exist then
  • /Root/Global/contentviews/Browse.ascx is loaded.

The Sensenet CSS Framework

The Skin System's styles and class names are based on the jQuery UI CSS framework to easily create skins with the jQuery ThemeRoller and with few easy modifications in the Sense/Net CSS Framework. Of course, it is possible to use the jQuery UI support only partially (or completely turn it off) if you don't include all of its global scripts and styles in your templates except for those you really need. In this way you have the power to create fully customized designs and Theme Roller supported skins, too.

Adding stylesheet (.css) references to pages

When building and designing a page css files referenced by the controls and views need to be present when rendering the page. Different applications may use different css references but they may as well reference the same files. Builders may also need to specify the order of css references in which they are loaded on the page. Using the techniques below will also make use of css bundling.

from ascx

In case of ASP views (controls, Content Views) you can use the following syntax to add a reference to a CSS file:

<sn:CssRequest ID="ref1" Path="$skin/styles/book.css" runat="server" />

Here $skin will be resolved to current skin of the page. You may also use absolute addressing of the CSS file:

<sn:CssRequest ID="ref1" Path="/Root/Global/styles/book.css" runat="server" />

The following is an example for using the full set of available properties:

<sn:CssRequest ID="ref1" Path="$skin/styles/book.css" rel="stylesheet" media="all" order="30" title="book" runat="server" />

The page will load all css files that were referenced from any ASP.Net control (let it be a page or a control) in the right order - every css is included only once.

from xslt

You can use the xmlns:sn="http://www.sensenet.com/2010" namespace definition and the sn:cssrequest markup to reference a css from xslt:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                xmlns:sn="http://www.sensenet.com/2010">
 
  <sn:cssrequest path="$skin/styles/book.css" />

Adding javascript (.js) references to pages

When building a page js files referenced by the controls and views need to be present when rendering the page. Different applications may use different javascript references but they may as well reference the same files. Using the techniques below will also make use of javascript bundling.

from ascx

To reference a javascript from .ascx markup, as in a User Control without codebehind, you can use the sn:ScriptRequest serverside control:

  <sn:ScriptRequest Path="$skin/scripts/sn/SN.ContentEditable.js" ID="request1" runat="server" />

You can also use absolute paths when referencing a javascript file:

  <sn:ScriptRequest Path="/Root/Global/scripts/sn/SN.ContentEditable.js" ID="request1" runat="server" />

from xslt

You can use the xmlns:sn="http://www.sensenet.com/2010" namespace definition and the sn:scriptrequest markup to reference a javascript from xslt:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                xmlns:sn="http://www.sensenet.com/2010">
 
  <sn:scriptrequest path="$skin/scripts/sn/SN.ContentEditable.js" />

Javascript dependency

The above scripts will include the given javascript references in the page. Javascripts may also contain references to other javascripts. For example a script file using jQuery may use a special markup at the very beginning of the file to reference the jQuery library. The above referenced SN.ContentEditable.js for example contains the following line at the beginning of the file:

// using $skin/scripts/sn/SN.js
// using $skin/scripts/jquery/jquery.js

This way when using the sn:ScriptRequest control to reference the SN.ContentEditable.js not only the referenced javascript file will be included but the jQuery library will also be automatically referenced.

Script loading example

Let's look at an example scenario:

  • a.js depends on x.js and y.js
  • b.js depends on y.js
  • c.js depends on a.js

On a Sense/Net Portlet Page, a.js, b.js and c.js were requested by various modules, some of them several times. However, x.js and y.js were not requested explicitly. This is a possible order in which the SNScriptManager will load the scripts:

  1. x.js
  2. y.js
  3. a.js (needs x.js and y.js)
  4. b.js (needs y.js)
  5. c.js (needs a.js)

Note that dependencies are always loaded before the script that has requested them. Cycles in the dependency graph will however result in a serverside exception.

Please note that an sn:SNScriptManager control has to be present at the top of the page for all the above javascript referencing mechanism to work properly. The Sense/Net PageTemplates always include this control in master pages by default (even if the PageTemplate has been created manually) so you don't have to worry about it when working with Sense/Net Pages.

Related links

References