Experience Sitecore ! | All posts tagged 'Rendering-Variants'

Experience Sitecore !

More than 200 articles about the best DXP by Martin Miles

Implementing blogs index page with filters and paging: SXA walkthrough

Objective.

Initially I've had a template called Blog, and several pages of it which are actual blog posts. Now I have created a page called Blog Index, implementing template, partial and page designs of the same name. The obvious purpose of given page is to show the list of blog posts, being able to filter this out by certain criteria, including a new custom one - series. Content authors want to group these blogs posts into series, so that's a grouping by a logical criteria. They also want to to display the most recent higher, but give readers an option to select an order, as well as page size.


Implementation plan

  1. Switch to SXA "Live mode" (optional)
  2. Create taxonomy categories
  3. Create Series interface template
  4. Use interface template and update blog posts
  5. Create search scope for page template
  6. Create computed field
  7. Publish, redeploy and re-build indexes
  8. Create facets
  9. Create filter datasources
  10. Make rendering variant for search filters
  11. Make rendering variant for search results
  12. Place component to partial design
  13. Configuring Search Results component
  14. Enjoy result!


IMPLEMENTATION

1. Before start, switch web to master, this can be done at /sitecore/content/Tenant/Platform/Settings/Site Grouping/Platform at Database field by setting it to master (dont't forget to publish that particulat item however). Once done, it will use not only master database at published site, but also master indexes.


2. Firstly, let's create Series taxonomy folder under Taxonomy (/sitecore/content/Tenant/Platform/Data/Taxonomy) and populate it with actual series-categories that will be used for filtering:


3. Now I can create interface template to implement series selection. This template will be later used with not just Blogs but also few other page types, that's why I make it an interface and put into shared - /sitecore/templates/Project/Tenant/Platform/Interfaces/Shared/_Series.

Make sure the Source column has correctly set datasource, so that you later will be able to pick up right category under site's Data/Taxonomy/Series folder, as on example below:

Datasource=query:$site/*[@@name='Data']/Taxonomy/Series&IncludeTemplatesForDisplay=Taxonomy folder,Category&IncludeTemplatesForSelection=Category


4. Once done, add _Series interface template to actual page template (Blog in my case). Then one can go to existing blog posts and assign them into series (best with Sitecore PowerShell):

$rootItem = Get-Item master:/sitecore/content/Tenant/Platform;
$sourceTemplate = Get-Item "/sitecore/templates/Project/Tenant/Platform/Pages/Blog";  
$selectedSeries = "{1072C536-0EC2-4EAB-8D98-DC9BF441F30A}";

Get-ChildItem $rootItem.FullPath -Recurse | Where-Object { $_.TemplateName -eq $sourceTemplate.Name } | ForEach-Object {  
        $_.Editing.BeginEdit()
        $_.Fields["Series"].Value = $selectedSeries;
$_.Editing.EndEdit() }

Now selecting an item displays which series it belongs to:


5. Create scope under /sitecore/content/Tenant/Platform/Settings/Scopes, call it Blogs and set its field Scope Query to filter out by Blog template ID:


6. Create computed field contentseries at you project to store actual name of Series into index that's in addition to another field in index called series so that automatically indexed by template and stores GUID for series. This is how I implemented it in Platform.Website.ContentSearch.config:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <contentSearch>
      <indexConfigurations>
        <defaultSolrIndexConfiguration>
          <fieldMap>
            <fieldNames>
              <field fieldName="contentseries" returnType="stringCollection" patch:after="*[0]" />
            </fieldNames>
          </fieldMap>
          <documentOptions>
            <fields hint="raw:AddComputedIndexField">
              <field fieldId="{ID-of-Series-field-within-_Series_template}" fieldName="contentseries" returnType="stringCollection" patch:after="*[0]">
                Tenant.Site.Website.ComputedFields.CategoriesField,Tenant.Site.Website
              </field>
            </fields>
          </documentOptions>          
        </defaultSolrIndexConfiguration>
      </indexConfigurations>
    </contentSearch>
  </sitecore>
</configuration>


7. Publish this configuration into webfolder, then clean up (you can run PS script below) and rebuild indexes.

stop-service solrServiceName
get-childitem -path c:\PathTo\Solr\server\solr\Platform*\Data -recurse | remove-item -force -recurse
start-service solrServiceName
iisreset /stop
iisreset /start


8. When computed field comes into index, the next step sould be to create Series facets. Please note that facet name should be different from the field name as the one got by template and then facet overwrites it

  • For Series - under /sitecore/content/Tenant/Platform/Settings/Facets. The most important field here is Field Name, the value would be contentseries that matched name of field we've created at the previous step
  • Also create one for Published date that relies on already existing published_date_tdt field, which is a custom date field presenting in all of my content page templates.


9. Create new datasource items:

  • checklist filter called Series under /sitecore/content/Tenant/Platform/Data/Search/Checklist Filter folder and assign its first field to point Series facet created at previous step
  • an item for Publication Date under /sitecore/content/Tenant/Platform/Data/Search/Date Filter/Publication Date.


10. Implement Search Filter rendering variant that will contain actual filters. I create that under my custom component Search Content, make two columns and also component variant field into each of them. Assign Filter (Checklist) into first and Filter (Date) into second. Reference datasource items from previous step for each component correspondingly:


11. Implement Search Result rendering variant that will define presentation for each item shown/found:

Noticed Series reference field? That switches context to the item references by Series field, so that I can get a value of actual category under Taxonomy folder.


12. In partial design for Blog Index, drop the following renderings into the canvas: Search content, Sort Results, Page Size and Search Results.


13. Finally, for Search Results component, go to Edit component properties, under SearchCriteria section assign Search results signature to search-results and also select Search scope to match Blogs.

The result:

How to add id and data-attributes to a Rendering Variant in SXA?

When dealing with a rendering variant field, it is not a big deal to set few data-attributes to it - those inputs are located at the very bottom of Variant Details section. You can do it like that:


But what if you need data attributes to the top level of component, which it Rendering Variant item itself? There isn't such an option!

Requirements are

  1. An id attribute (ie. section-1, section-2, ... section-N)
  2. One or many data-attributes (ie. " User-friendly title", "Another user-friendly title", etc.)
  3. CSS class section-with-anchor on those instances, which have both previous requirements implemented
All of the above should be set for the top node of a rendering - outside of the control of Rendering Variant. Thinking logically - if we ever could add the above to Rendering Variant item itself, then it would present on every single instance of that given rendering variant. We do have CSS-class field on Rendering Variant item, but as I said, we need this class to present only occasionally for some individual instances as per requirement so we cannot use that field.

Solution

That is where Rendering Parameters come into a play, as they apply per each individual rendering usage. Let's take a look!

1. ID of a component. That was the easiest as luckily default rendering parameters do support field for that:


2. Data-attributes do not exist in Rendering Parameters control, unlike id attribute. But since that is just a collection of Key-Value pairs, why not to convert them into a set of data-attributes on a component node. Not all, of them, of course, but those that start with data- as on an image below:


In order to pick them up and assign to a rendering view, I write a simple extension method:
public static MvcHtmlString RenderAllDataAttributes(this HtmlHelper helper)
{
    var rendering = Sitecore.Mvc.Presentation.RenderingContext.Current.Rendering;

    string additionalAttributes = String.Empty;
    if (rendering?.Parameters != null)
    { 
        foreach (KeyValuePair<string, string> parameter in rendering.Parameters)
        {
            if (parameter.Key.ToLower().StartsWith("data-"))
            {
                additionalAttributes += $"{parameter.Key}=\'{parameter.Value}\' ";
            }
        }
    }

    return new MvcHtmlString(additionalAttributes.Trim());
}
It can be called like that:
<div @Html.RenderAllDataAttributes() @Html.Sxa().Component(Model.Rendering.RenderingCssClass ?? "default-class", Model.Attributes)>
    <div class="component-content">
        ...
    </div>
</div>


3 Setting a style class. As mentioned before, do not misuse Css Class field of rendering variant definition for styling a specific implementation of rendering variant. Style that are applied individually for each instance of rendering (regardless of variant selected) can be found at that same Rendering Parameter window, located at Styling section.


Of course, you may need to create this style beforehand, if not yet done. To do so, create a new Style item underneath Styles grouping item and restrict to renderings where give style can be shown. That is a part of your style them and is located under /sitecore/content/Tenant/Site/Presentation/Styles node:

Result

Finally, I got it all rendered as expected:


That blog post shows how useful Rendering Parameters are, hope you find it helpful!

Script rendering variant field in SXA - why would one need it?

Note! The code used in this post can be cloned from GitHib repository: SXA.Foundation.Variants

Yet another rendering variant field came to my to-do list for implementation - Script rendering variant field. Why would I need one at all? 

I came across two uses cases where implementing this field type made my job done and that's just recently. Some developers have (reasonable) biases against having JavaScript code inline instead of referencing JS-file at the bottom of a page, and I do understand their point - Google may penalise your site for overusing inline JS. So use it responsibly, don't overuse. Keeping in mind that given field comes up as a part of a component dynamically added to a page - there isn't a big choice on how to extend running website with some additional client-side functionality. I am presenting both cases below, let's take a look at them. Would you know the better way of achieving these goals - please let me know via Slack or Twitter. Also, the code of Script Variant Field is at the very bottom of the page.


Use case 1: implementing in-page navigation panel

As usual, I got a precise requirement from my strict front-end team to implement such a piece of code as a component. It has a UL-tag that will keep a link list to other components of this same page (prefixed with #) created client-side dynamically, and a script that does the actual job. When rendering the in-page navigation component by the backend, we're now aware of other components and their attributes, so the walk-around was handling page loaded event and identifying all the components that have IDs set and class section-with-anchor.

<div class="component content col-12 content-section">
    <div class="component-content">
        <div class="anchor-panel">
            <ul class="anchor-panel__list"></ul>
            <script defer>
                document.addEventListener('DOMContentLoaded', function(){
                    if (!$('.section-with-anchor').length || !$('.section-with-anchor').length) return;
                    $('.section-with-anchor').each(function(index, el) {
                        var anchor = '#' + $(el).attr('id');
                        var text = $(el).attr('data-text');
                        var $anchorList = $('.anchor-panel__list');
                        var $anchorItem = $('<li class="anchor-panel__item"></li>');
                        var $anchorLink = $('<a href=""></a>')
                        $anchorItem.append($anchorLink.text(text).attr('href', anchor));
                        $anchorList.append($anchorItem);
                    });
                });
            </script>
        </div>
    </div>
</div>

Quite obviously, my rendering variant will contain 2 fields: a UL-tag section field for in-page navigation that takes the links dynamically and script variant field, containing the client-side logic. You can test this script in action by this link. That is how it looks in Content Editor:


Since I have 5 other sections qualifying script requirements - they all have been identified by the script and added to in-page navigation panel. Here's how the result looks like on a styled page for me:


Once again, I decided to implement a new script variant reference field because the component is subject to some seldom minor JavaScript changes, but should be configurable. Also, at given use case it can be dropped only once into a page, so there's no problem with multiple instances of the same script for me, but using it you might need to check if that applies for your scenarios. But even with that in mind, I'd probably not bothered creating yet another new rendering variant field, if not few more potential usages I have in backlog.


Use case 2: accessing client side URL hash-key parameter and presenting it on a page

Recently I implemented a URL query string parameter variant field, where one can set any parameter and the field present its URL-decoded value on a page in any given tag and style. A colleague of mine who develops search results page with SXA asked if that's doable to extract a hash-key URL parameter and show it on a page along with other content, however that a fully client-side parameter that never got posted to the server.

I decided to give a try and managed to confirm with a small proof of concept. I quickly wrote this script (so please be forgiving for it being just a quick PoC and me not being the proper FED).

window.addEventListener("hashchange", function () {
    var h1 = document.getElementsByClassName("updatedHashValue");
    if (h1.length > 0) {
        h1[0].innerHTML = getHashValue("param");
    }
    function getHashValue(parameter) {
        var hashValues = window.location.hash.substr(1);
        var result = hashValues.split('&').reduce(function (result, item) {
                var parts = item.split('=');
                result[parts[0]] = parts[1];
                return result;
        }, {});
        return result[parameter];
    };
});

That's how it looks implemented as the part of rendering variant. It creates an H1 element to store the value, extracted out of hash parameters stored at URL bar and updated without any postback to the server, and of source script variant field:


Testing. After adding a component to a page, saving and selecting the above rendering variant, I got the page reloaded as anticipated with no visual changes. Then I open a console from browser dev.tools and enter:

window.location.hash = "param=Successful!"

From dev.tools that was easy to confirm that there was no postback done to the server, however, browser navigation bar predictably changed, appending new hash parameters pair: 

And guess what? H1 element immediately got that value displayed. Love that magic!


The code is very simple, similar to other variant fields I've blogged previously. Create the model and implement property for a field:

public class VariantScript : VariantField
{
    public string Script { get; set; }
}

Reference ID of that field from a template and ID of a template itself:

public static class Constants
{
    public static class RenderingVariants
    {
        public static class Templates
        {
            public static ID Script = new ID("...");
        }
        public static class Fields
        {
            public static class Script
            {
                public static ID ScriptField { get; } = new ID("...");
            }
        }
    }
}

Here's a parser

public class ParseScript : ParseField
{
    public override ID SupportedTemplateId => Constants.RenderingVariants.Templates.Script;

    public override void TranslateField(ParseVariantFieldArgs args)
    {
        ParseVariantFieldArgs variantFieldArgs = args;

        variantFieldArgs.TranslatedField = new VariantScript
        {
            Script = args.VariantItem[Constants.RenderingVariants.Fields.Script.ScriptField]
        };
    }
}

and a renderer:

public class RenderScript : RenderVariantField
{
    public override Type SupportedType => typeof(VariantScript);

    public override RendererMode RendererMode => RendererMode.Html;

    public override void RenderField(RenderVariantFieldArgs args)
    {
        var variantField = args.VariantField as VariantScript;
        if (variantField != null)
        {
            args.ResultControl = RenderScriptField(variantField, args);
            args.Result = RenderControl(args.ResultControl);
        }
    }

    protected virtual Control RenderScriptField(VariantScript variantScript, RenderVariantFieldArgs args)
    {
        if (!string.IsNullOrWhiteSpace(variantScript.Script))
        {
            var tag = new HtmlGenericControl("script") { InnerHtml = variantScript.Script };
            tag.Attributes.Add("defer", String.Empty);
            return tag;
        }

        return new LiteralControl();
    }
}

New Script Rendering Variant field, that enhances your tooling for implementing more modern-looking websites. And as usual - please use it responsibly!

Welcome Item Reference - a rendering variant field missing out of the box in SXA

Note! The code used in this post can be cloned from GitHib repository: SXA.Foundation.Variants
The majority of folks working with SXA are aware of Reference Item variant field - that allows switching a context of rendering variant from a context item (current page or datasource item, if set) to either one or many items referenced by a link-type field of a given context item. It works like a charm, but in some cases one may meet a case where setting datasource is not applicable or you may need your component to show something different apart from provided datasource item - I have already described how to implement that using Query Variant Field. Let's evaluate it:
Pros
  • it comes out of the box, and could be used straight away
  • you may query in more complex way rather just proving an ID
Cons
  • it relies on SXA search index to be in actual state - you need to have it rebuilt
  • writing query is less user friendly then just picking up an item.
So why not to implement a dedicated Item Reference variant field - it definitely pays off, once used often.

This time I picked up built-in Reference variant field as a donor. Instead of PathTrough field I added Item field of Droptree type:



Code-wise, I implemented one property named PassThroughItem. There's also another one to store child fields, nested underneath given reference item field, those will be executed and render in a switched context:
public class VariantItemReference : BaseVariantField
{
    public string PassThroughItem { get; set; }

    public IEnumerable<BaseVariantField> NestedFields { get; set; }
}
Need to reference IDs of template and its single field:
public static class Constants
{
    public static class RenderingVariants
    {
        public static class Templates
        {
            public static ID ItemReference = new ID("...");
        }

        public static class Fields
        {
            public static class ItemReference
            {
                public static ID Item { get; } = new ID("...");
            }
        }
    }
}
Implement a parser:
public class ParseItemReference : ParseVariantFieldProcessor
{
    public override ID SupportedTemplateId => Constants.RenderingVariants.Templates.ItemReference;

    public override void TranslateField(ParseVariantFieldArgs args)
    {
        ParseVariantFieldArgs variantFieldArgs = args;

        var reference = new VariantItemReference();
        reference.ItemName = args.VariantItem.Name;
        reference.PassThroughItem = args.VariantItem[Constants.RenderingVariants.Fields.ItemReference.Item];

        reference.NestedFields = args.VariantItem.Children.Count > 0
            ? ((IVariantFieldParser)ServiceLocator.ServiceProvider.GetService(typeof(IVariantFieldParser))).ParseVariantFields(args.VariantItem, args.VariantRootItem, false)
            : new List<BaseVariantField>();

        variantFieldArgs.TranslatedField = reference;
    }
}
And a renderer:
public class RenderItemReference : RenderVariantFieldProcessor
{
    public override Type SupportedType => typeof(VariantItemReference);

    public override RendererMode RendererMode => RendererMode.Html;
      
    public override void RenderField(RenderVariantFieldArgs args)
    {
        var control = new PlaceHolder();

        var variantItemReference = args.VariantField as VariantItemReference;
        if (!string.IsNullOrWhiteSpace(variantItemReference?.PassThroughItem))
        {
            var newContextItem = Sitecore.Context.Database.GetItem(new ID(variantItemReference.PassThroughItem));
            if (newContextItem != null)
            {
                foreach (BaseVariantField referencedItem in variantItemReference.NestedFields)
                {
                    RenderVariantFieldArgs variantFieldArgs = new RenderVariantFieldArgs
                    {
                        VariantField = referencedItem,
                        Item = newContextItem,
                        HtmlHelper = args.HtmlHelper,
                        IsControlEditable = args.IsControlEditable,
                        IsFromComposite = args.IsFromComposite,
                        RendererMode = args.RendererMode,
                        Model = args.Model
                    };

                    CorePipeline.Run("renderVariantField", variantFieldArgs);
                    if (variantFieldArgs.ResultControl != null)
                    {
                        control.Controls.Add(variantFieldArgs.ResultControl);
                    }
                }
            }
        }

        args.ResultControl = control;
        args.Result = RenderControl(args.ResultControl);
    }
}
Here is the usage:


Don't' forget to add it into Insert Options and hope you'll enjoy it!

SXA: Implementing URL query parameter rendering variant with little efforts

Note! The code used in this post can be cloned from GitHib repository: SXA.Foundation.Variants

Got a requirement to display a value passed with a URL parameter on a page (URL decoded of course). I want to achieve the goal as quick as possible, with the minimum steps, ideally. So, here we go..

1. Just use existing VariantField (located at /sitecore/templates/Foundation/Experience Accelerator/Rendering Variants/VariantField). When copying, ensure you keep new variant field template outside of Experience Accelerator folder (to avoid it being lost on future SXA upgrade), ideally somewhere within a folder with serialization configured.


2. Remove unwanted fields from a new template. I left only a few I felt necessary, but you may end up having even less. Another thing I've done at this step was adding a user-friendly label to the field, to avoid editors' confusion with a misleading naming:


3. Then you need to create a model. As the simplest, I inherited from VariantField

public class VariantQueryString : VariantField
{
    public VariantQueryString(Item variantItem) : base(variantItem)
    {
    }
}

With a parser, I only process those fields I will be using - what I kept from the previous step: 

public class ParseQueryStringField : ParseField
{
    public override ID SupportedTemplateId => Constants.RenderingVariants.Templates.QueryString;

    public override void TranslateField(ParseVariantFieldArgs args)
    {
        ParseVariantFieldArgs variantFieldArgs = args;

        variantFieldArgs.TranslatedField = new VariantQueryString(args.VariantItem)
        {
            // this property is reused under different purpose rather than named - it stores URL parameter name
            FieldName = args.VariantItem[Constants.RenderingVariants.Fields.QueryField.FieldName],

            Tag = args.VariantItem.Fields[Constants.RenderingVariants.Fields.QueryField.Tag].GetEnumValue(),
            CssClass = args.VariantItem[Constants.RenderingVariants.Fields.QueryField.CssClass],
            Prefix = args.VariantItem[Constants.RenderingVariants.Fields.QueryField.Prefix],
            Suffix = args.VariantItem[Constants.RenderingVariants.Fields.QueryField.Suffix],
            RenderIfEmpty = args.VariantItem[Constants.RenderingVariants.Fields.QueryField.RenderIfEmpty] == "1"
        };
    }
}

Also reference IDs of these fields within Constants class:

public static class Constants
{
    public static class RenderingVariants
    {
        public static class Fields
        {
            public static class QueryField
            {
                public static ID Tag { get; } = new ID("{F556DEDD-5D6B-4FFF-A904-E4C65AB0E698}");
                public static ID CssClass { get; } = new ID("{B3B6B300-1704-493B-999C-AD21CCE58FEF}");
                public static ID FieldName { get; } = new ID("{9D3717EF-CD09-4D98-8C4A-914299503626}");
                public static ID Prefix { get; } = new ID("{5844C4AA-5E48-4721-8E30-91646E430C83}");
                public static ID Suffix { get; } = new ID("{0EFAF48E-E0DD-4408-80D3-4C001101E834}");
                public static ID RenderIfEmpty { get; } = new ID("{E14C3930-FE6C-48AC-99D8-C6867B489066}");
            }
        }
    }
}

4. Finally, implementing RenderQueryStringField class. Nothing complex - just getting a value from the query string, wrapping it with a selected tag/styles and rendering it into the page. Also, there's a fallback scenario for Experience Editor when a given parameter is missing from URL but component needs to be visible.

public class RenderQueryStringField : RenderVariantField
{
    public override Type SupportedType => typeof(VariantQueryString);

    public override RendererMode RendererMode => RendererMode.Html;

    public override void RenderField(RenderVariantFieldArgs args)
    {
        var variantField = args.VariantField as VariantQueryString;
        if (variantField != null)
        {
            args.ResultControl = RenderQueryStringValue(variantField, args);
            args.Result = RenderControl(args.ResultControl);
        }
    }

    protected virtual Control RenderQueryStringValue(VariantField variantField, RenderVariantFieldArgs args)
    {
        var queryString = HttpContext.Current.Request.QueryString;

        if (!string.IsNullOrEmpty(variantField.FieldName) && !string.IsNullOrWhiteSpace(variantField.Tag))
        {
            if (queryString.HasKeys() && queryString[variantField.FieldName] != null)
            {
                var tag = new HtmlGenericControl(variantField.Tag);
                AddClass(tag, (variantField.CssClass + " " + GetFieldCssClass(variantField.FieldName)).Trim());
                tag.InnerText = queryString[variantField.FieldName];
                return tag;
            }

            if (args.IsControlEditable && PageMode.IsExperienceEditorEditing)
            {
                return GetVariantFieldNameLiteral(variantField.FieldName);
            }
        }

        return new LiteralControl();
    }

    protected virtual HtmlGenericControl GetVariantFieldNameLiteral(string parameterName)
    {
        var missingField = new HtmlGenericControl("span");
        missingField.Attributes.Add("class", "missing-field-hint");
        missingField.InnerText = $"[{parameterName}] URL paramenter";
        return missingField;
    }
}

5. I am adding new field variant into existing Foundation project, but if you haven't got one - you might create it. Do not forget to include config patches. something like below:

?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <pipelines>
      <parseVariantFields>
        <processor type="Platform.Foundation.Variants.Pipelines.VariantFields.QueryString.ParseQueryStringField, Platform.Foundation.Variants" resolve="true" patch:before="processor[@type='Sitecore.XA.Foundation.RenderingVariants.Pipelines.ParseVariantFields.ParseField, Sitecore.XA.Foundation.RenderingVariants']" />
      </parseVariantFields>
      <renderVariantField>
        <processor type="Platform.Foundation.Variants.Pipelines.VariantFields.QueryString.RenderQueryStringField, Platform.Foundation.Variants" resolve="true" patch:before="processor[@type='Sitecore.XA.Foundation.RenderingVariants.Pipelines.RenderVariantField.RenderVariantField, Sitecore.XA.Foundation.RenderingVariants']"  />
      </renderVariantField>
    </pipelines>
  </sitecore>
</configuration>

6. You might consider adding a new variant field into Insert options. Once done, add it as you normally do with variant fields:


Result. That is how it works when passing a URL parameter with a value:


When a parameter is missing from URL, this is how it looks like in Experience Editor, at least making component selectable:


Hope you find this post helpful!

What is Query Variant Field to be used with rendering variants and few real life scenarios of using it

Imagine a case - there is a datasource item, that has a Droplink field to pointing to another item, let's say a Rich Text with an address (as on an image below):


That means, in your rendering variant you simply use Reference Variant Field referencing an item behind Rich text droplink, and within that Rich text item you simply render a field, as normal:


Seems obvious, right? Let's increase complexity!


Scenario one

We change scenario so that Droplink would now point not to an item having the field to render, but rather to an item, containing other children you might need to display:


So instead of referencing a Rich text item, we'll reference Link list item, where you need to iterate child items (links) of a referenced Link List item, and show all these links on a page with a rendering variant:


Question: how do I iterate children of my referenced item?

Okay, that's where your new friend comes to help you. Welcome, Query Rendering Variant Field!

What it actually does is also switching a context to a single item / multi items, similarly to Reference Variant Field, but instead of taking switching context from a link-powered field, it uses Sitecore search query and switches context to its execution result. Here's how one can add Query Variant Field into a rendering variant:


So for my simple example with Link List children, I use a query to search all the children of a current item (Link List):


That does the job and withing this query item you may use fields related to items coming out from a search.

One more helpful tip: when working with references, queries or whatsoever changes the context, you would often wondering iа changing context worked well and referencing what you intend to. The trick I use is inserting a debugging template field exposing ID and/or a name of where we've switched to (or any other universal property all the items do have and that are accessible from NVelocity $item):


This takes only 5 seconds of my time to implement but immediately helps to visualise a context on output. Very helpful!


Second scenario

... where Query Field Variant helps me so much. I need to implement a Subscription Level identifier on every page, so that it shows which privilege a current user has (obviously, he/she will see an only single one of the labels show below at one time):


But there is a requirement for that labels itself to be changeable and kept somewhere under site's settings item - subject to alterations at a later stage. So I already have a separate folder with such items:


With using a Reference Variant Field one would need to have rendering having a datasource item with a field pointing to one of those subscription items, which is not an elegant scenario. And what if my rendering does not accept datasources? Or it simply breaks sense, as in a described scenario?

Since we know the IDs of these subscription items we can reference them directly and that's where Query Variant Template also helps us. Also, search query by an ID always returns not more than one item, and since we know item exists we can use it as direct linking. That's how I do that:


Works like a charm!

I have just shown only two real-life examples of using Query Variant Field, but the potential area of their usage is virtually unlimited - as much as you can query you indexes. This gives an ultimate tool for comfy switching context as much as you may need that, but I'd warn you from overusing it too much.

How to make a link to downloadable media item from within SXA rendering variant?

This is just a quick tip about the way you can create a downloadable link to some media item from within a rendering variant. Given, that you have a template with a field of type File, and an item of that template has a downloadable resource, let's say PDF. Trying to use that field worn't work normally.

What you should do instead is create a reference variant field to that media item, attached within a File field. And from within a context of that reference variant field, you address to a field called File path. The image below describes that trick in action:


Hope that trick helps!

Creating custom SXA components with rendering variants and (almost) no codebehind on an example of social share buttons

Introduction. Initially, I was going to implement social share buttons on my page. The first thing coming into my mind was to use existing share components coming OOB with SXA. That's what I did and it looked well.. until I viewed generated source. It looks quite monstrous, includes iframes, inline JavaScripts and in general brought customization issues for my front-end developers. Here's how 2 of 3 buttons look like when rendered (3-rd is collapsed):


In general, that looks sort of over-engineering for given requirements. The code suggested by my front end developers looked more-less elegant like this:

<div class="social-block">
	<span class="social-block__label">share this</span>
	<ul class="social-block__list">
		<li class="social-block__item">
			<a href="#" class="social-block__link social-block__link_facebook"></a>
		</li>
		<li class="social-block__item">
			<a href="#" class="social-block__link social-block__link_twitter"></a>
		</li>
		<li class="social-block__item">
			<a href="#" class="social-block__link social-block__link_linkedin"></a>
		</li>
		<li class="social-block__item">
			<a href="#" class="social-block__link social-block__link_mail"></a>
		</li>
	</ul>
</div>

Definitely much nicer and cleaner, given that sharing functionality provided by many social platforms can be implemented just in a form of a link (ie. //www.facebook.com/sharer/sharer.php?u=https://your-site/page-to-share), so that can be simply passed with href attribute of anchor tag. 


Implementation. Based on that, I decided to implement my own Share buttons component. Of course, unwilling to create a new component from a scratch, I decided to take a look on existing with a purpose of cloning it. There were 2 requirements while picking the right component to clone: 1) it should support rendering variants and 2) it should work with datasource template, so that those are also cloned. It looks that Promo component fits the purpose well, so here we go, by using an SXA built-in clone script available from a context menu:



By that moment, I already have my custom module named Components, sitting outside of Experience Accelerator folder, that will likely be overridden by next version update, and where I separate my custom controls. So, in the following dialog, name the component, state where you want to put it and also give the name to CSS class to be used with it. 

I called my new component Social buttons, so that I will make two rendering variant as the part of it: one for sharing current page over social networs, and another will be called Social presense simply leading to my company's social network accounts. I also named CSS class social-buttons:

Also, in order to be able to provide some defaults, I also make a copy of Promo's rendering parameters under a new name, so that I could adjust it later according to my requirements:

And also copying datasource:

And finally, to make my new component even more isolated from its donor, I copy the rendering view file as well:


It is not mandatory, you may keep using existing control rendering. However, In my case I do want to modify HTML structure, to get rid of nested <div class="component-content"> elements, so I select "Copy MVC view file (specify path below)" option. 

Note 1: before you start cloning component, make sure ~/Views/SocialButtons target folder exists, otherwise script errors out. Also, once done don't forget to copy cloned rendering into your working folder so that you include it into solution and add to the source control (somewhere similar to src/Feature/Components/code/Views/SocialButtons/SocialButtons.cshtml as in my case).

Note 2: just to remind, that rendering view, CSS class name for the component and other settings can be adjusted later at the Experience Accelerator section of rendering item:

Click Proceed and when complete, you see successful result confirmation:


Once clone script finished, we may also want to add new component into the toolbox. To do so, navigate to Presentation - Available Renderings, find the desired module and add a new component into it:

I made few more changes - renamed Social buttons into Social buttons group as it makes more sense, and made item and folder templates for buttons. 

Here's what I got under feature templates for Social buttons group:


and for Social button:

You may also notice two correspondent folder templates to create folders for storing items of these new types.

These were feature-layer templates, but there's one more project-layer interface template to be appended to page types inheritance:


So now, under Data folder I can create social buttons and a social share group based on (some of) these buttons. I made just one and called it Default


From this moment, adding _Social share groups interface template into an inheritance of some page templates adds a section with an option of selecting a social group for all pages of these type. You may also customize label (and if) shown next to social buttons.


Usage. Here we carry on. After adjusting placeholder settings, you added a new component to a page, then selected appropriate datasource but nothing appears as the result. This comes due to a component supporting rendering variants, does not have any single variant availability. How comes that? 

Note 3: the clone script does not clone rendering variants (at least per SXA version 1.8), so you need to create at least one. Remember that when creating new Variants item (or duplicating an existing one), the name should be the same, as the name of the corresponding rendering:


Insert at least one Variant Definition. 

Note 4: the way rendering variants work it the first Variant Definition in the list becomes default one, if not set explicitly. I called variant Share buttons and added Info field so that it becomes visible on partial design in Experience Editor straight away (I explain Info field trick in more details in this article).


At least component shows up in Experience Editor as:


Now being aware that right component with right rendering variant presents on a page, I can carry on implementing that variant according to my desired output. 

Note 5: these buttons are not subjects to changes by content editors from within EE, rather they are configured by the site setup. That's why links should not be editable so I can use template variant field in order to render anchor tag precisely as per our requirements.


Creating rendering variant. This is how I implemented Share buttons rendering variant:


Few things I'd like to explain about the way it is structured and how it works. 

1. Naming conventions. instead of giving sections generic names, I am following "Element - Class" approach. Of course, it would make much sense from interpreting the point of view to name them "Element.Class" as CSS selectors normally do, however using dot is not allowed to be used for Sitecore item names by default while explicit setting that value for display name is an exhaustive waste of time. In any case, it is clear what element renders to.

2. You may notice, that I am having two reference variant fields, one nested into another. The way it works is that it contains the name of a field from a context item, that has a link to another item (or items). Thus, it switched context so that all nested field will be executed in the context of that "proxied" item.

3. NVelocity template (pictured above) is the very powerful way to extend rendering variants functionality far beyond out-of-the-box variant fields, employing the power of custom C# code, pre-built tools or creating your own. In one of my previous posts, I mentioned SXA built-in token tools to be used with rendering variant templates, so I am using the one already have in my solution, but if you haven't - these 2 snippets would be the only piece of your C# code to implement. Link Tool:

public class LinkTool
{
    public static string GetItemLink(Item item, bool includeServerUrl = false)
    {
        var options = UrlOptions.DefaultOptions.Clone() as UrlOptions;

        if (includeServerUrl)
        {
            options.AlwaysIncludeServerUrl = true;
        }

        return LinkManager.GetItemUrl(item, options);
    }
    public static string GetCurrent(bool includeServerUrl = false)
    {
        var item = Sitecore.Context.Item;
        return item == null ? String.Empty : GetItemLink(item, includeServerUrl);
    }
}
and ItemFieldTool below:
public class ItemFieldTool
{
    public static string GetField(Item item, string fieldName)
    {
        ReferenceField field = item.Fields[fieldName];
        return field?.Value ?? String.Empty;
    }
}

The payload, however, is lack of ability to edit anchor tag, as I mentioned in Note 5 above. But, that should not surprise, given that you see that it is being calculated on a fly from different sources. GetFieldTool reads field value of a context item, where context has been changed twice already, in this case, a variant is iterating through the list of Social buttons and $item relates to Social button item.

#set($title = $itemFieldTool.GetField($item, "Title"))
#set($suffix = $itemFieldTool.GetField($item, "Style suffix"))
#set($prefix = $itemFieldTool.GetField($item, "Url prefix"))
But how do I get a something from the context of an initial item, before "tunnelling" two times through references? The code behind tools is being still executed in Sitecore.Context which means access to page item, so I implemented GetCurrent() method that returns full URL of context page. I use it for appending to URL prefix of a social button.
$linkTool.GetCurrent(true)


Getting result. Finally, after opening exact item in Experience Editor (and not the partial design edited previously that does not wire to actual data), I am getting expected share links rendered, with correct URL:


and after applying CSS styles on a published site, Info Field scaffolding is not shown and we see nicely applied social share buttons:


This is a flexible approach allowing to configure individual buttons set per each page template by standard values with an option of overriding the default for specific page individually.

That was a walkthrough of creating new components with (almost) no new backend code written. You learned how to create custom components by cloning existing, how to create rendering variants, how to use reference fields to "proxy" the context and NVelocity templates from within rendering variant.

Hope it helps!

SXA tip: use information scaffolding fields to get more visibility over your components in Experience Editor

When working in Experience Editor, by default you see empty fields of components, that allows you editing these fields, selecting hierarchy and thus modifying components. However not always that happens...

Scenario: creating a rendering variant that has VariantReference (for switching context of related item) while editing partial design in Experience Editor. 

Symptoms: what actually happens is that partial designs are edited in their own context, all presentation data you create is stored in Final Renderings for that particular Partial Design, and not the page item. It will pull data from page item only once applied that item or (more likely) associated with its page template. But when using VariantReference field, it won't be wired to any data, thus not proxying the context to anything, leading to all the fields underneath VariantReference field item not rendered in EE. If there are not any other visuals within given rendering variant - entire component becomes non-selectable in EE.

Suggestion: to create some information field to be shown in Experience Editor, so that you may select given component and adjust its settings, as you normally do. At the same time we don't want this field to present outside of Experience Editor since its only purpose is make editors aware about this component.

Solution: that's the case where we can use personalization with a custom "where the Experience Editor is in editing mode" condition I recently wrote about. Having it in scope trick goes very simple - simply create a text variant field and enter component and rendering variant info: 


And once done, create a personalization rule for that info field to be shown only in Experience Editor, using newly created condition:


Finally, instead of unclickable whitespace, you'll see the component:


Hope this basic trick helps improving your productivity while working with SXA!

Quick tip: using rules engine for SXA rendering variants

I working on a rendering variant in order to implement a component similar to the one below:


The component should display a heading title, followed by a list of promo blocks leading to the other pages. What is important here, is that different page types can be assigned into given component, of course they all do implement _Promotable interface template that has fields allowing them being promoted through this component. So far, so good.

But notice, each promo block has its type in left top corner painted into appropriate color. The values of it (article, topic, blog) are actually types of the pages, they do not present in generic _Promotable interface template, but do match template names, so why not to expose template names for these fields?

The easiest way of doing that is to create a label for each of the page type and assign it corresponding CSS class to display in appropriate color. 


Then we may use built in Rules Engine in order to create a rules for each of these page type labels to be shown only if the item template matches given page type. Here's how it looks in Content Editor:


Note! If you cannot access your condition through SXA built-in Rule Engine, you need to assign tag to Conditional Renderings tags (/sitecore/system/Settings/Rules/Conditional Renderings):


Also, there is another way of achieving the same goat - using NVelocity templates: create a Variant Template field and expose current template name:


That will also work since type badge matches name of page template in our case, but will need some extra work to wire up CSS class, that should derive from template name in this or that way.