Client Pay Portal

How To Build A Weighted Repeater In Kentico

In my years of Kentico development I’ve often needed to expand on existing Kentico functionality to achieve a specific purpose. While Kentico is extremely feature-rich out of the box, I have encountered several incidences where custom code is required. A recent project needed a “weighted” repeater, allowing users to determine how often a specific item was displayed. Here is a breakdown of how to achieve such a control:

1. Create a custom user control

I typically start by using an existing web part from Kentico’s existing library. The CMSRepeater is always a good one as it has most properties already defined. I will copy that to a site-specific section of my code and rename it accordingly.

2. Add the “WeightedColumn” property

This custom web part’s main function will be to display a random item from the specified path/class, but use a column of the document type to “weight” the results. This will allow users to specify how often a specific item will show up.

What this should result in is the “News Item 1” will be displayed 50% of the time, while the others will be shown 30% and 20%, respectively. The secret is appending a specific column to the SELECT part of the query to randomize the returned records and weight them accordingly.

            repItems.Columns = "*";

            //Check for weight column

            if (WeightColumnName != null)


                repItems.Columns += ",RAND(CAST(NEWID() AS VARBINARY)) * " + WeightColumnName + " AS WeightColumn";

                if(repItems.WhereCondition != "")


                    repItems.WhereCondition += " AND ";


                repItems.WhereCondition += WeightColumnName + " IS NOT NULL";

                if (repItems.OrderBy != "")


                    repItems.OrderBy += ",";


                repItems.OrderBy += "WeightColumn DESC";


            repItems.ClassNames = ClassNames;

            repItems.Path = Path;

            repItems.TransformationName = TransformationName;

            repItems.SelectTopN = SelectTopN;



3. Register the webpart

- Browse to CMSSiteManager / Development / Webparts
- Click “New web part” under the desired category
- Add the Web part name, class name, and path to the ascx file


- Add in all the properties defined in the ascx 

Note: I have removed several for simplicity


4. Add fields / transformation to desired document types 

After creating/registering the web part, the next step is to add the weight column to your desired document types. In this example I will add it to the CMS.News document type.

After adding the fields, you will want to create a transformation specific to your repeater.

5. Add/Update Documents with the weight column value

You will need to populate the property for the document type in order for it to be displayed in the repeater.

6. Add the web part the template

The final piece is to add the webpart to a page template and configure it.
  •  In the CMS Desk, click the design tab on the desired template.
  •  Click “Add web part”
  •  Set the properties

7. Test it!

Finally, test your site to make sure the items are showing up as often as they should.


That’s it! With this code you can quickly add a weighted a repeater to your site. This works well for ads and other items that you want to bring to a user’s attention on your site!

Download Weighted Repeater Web Part (3.27 kb)


Wiz E. Wig, Mascot & Director of Magic
Wiz E. Wig

Director of Magic