Recently I have had to write a few import scripts to do bulk modification to rendering parameters, so I have added the capability to the Content Export Tool. Below I will explain the new Rendering Parameters Import feature; explain the two scenarios in which I needed to modify rendering parameters in bulk; and how each scenario is accomplished with the Content Export Tool.
It is recommended that the Rendering Parameters Import is used by developers rather than content authors, as it requires a somewhat more technical understanding of Sitecore than the Content Import.
How to use the Rendering Parameters Import
As with Content Import, this import is done using a CSV file. The Rendering Parameters Import can do the following:
- Change the placeholder of a rendering
- Change the value of a rendering parameter field on a specific rendering
- Change the position of a rendering (relative to all other renderings, or relative to the placeholder it is in)
- Move the rendering before or after another rendering
The above functions are accomplished using the following CSV headers:
- Item Path This column should contain the item path or ID.
- Apply to All Subitems Apply the changes on this line to the item and all subitems, defaults to false (TRUE/FALSE)
- Template With Apply to All Subitems, apply the changes only to items with the specified template name or ID. This field is ignored when Apply to All Subitems is not true
- Component Name The name or ID of the component to modify. If this is not specified, no changes will be made
- When Placeholder Equals Modify a component within this particular placeholder
- Nth of Type Modify the Nth component with the specified name (NUMERIC, STARTS AT 1)
- With When Placeholder Equals, modify the Nth component within the specified placeholder with the specified name
- Parameter Name The name of the rendering parameter to modify or add
- Value The value to set for the rendering parameter
- Placeholder The placeholder to move the rendering to
- Position The position to put the rendering in relative to all other renderings (NUMERIC, STARTS AT 0)
- Position in Placeholder The position to put the rendering in relative to its placeholder (NUMERIC, STARTS AT 0)
- Before The name of the FIRST rendering to put this rendering before
- After The name of the LAST rendering to put this rendering after
By default changes will be made to the first rendering that matches the requirements (i.e. matches Component Name and optional When Placeholder Equals). However, if you wish to target a rendering other than the first, you can use the Nth of Type header. For example, if you have three instances of the Rich Text component in the MainContent placeholder, you can target the second one by setting When Placeholder Equals to “MainContent” and Nth of Type to “2” (note: Nth of Type starts at 1, but Position and Position in Placeholder start at 0).
As with the Content Import, you can automatically publish all modified items by checking off the Publish Changes checkbox.
Example 1: Change the value of a rendering parameter
The first issue that occurred was when a client had me add a new rendering parameter field to a dynamic content listing component. The new field was a checkbox field called “Show Subtitle”. After this was created, they needed help because they needed “Show Subtitle” to be checked off on hundreds of pages… but not on EVERY instance of the component, only on the pages in a specific folder. So, I couldn’t easily check off “Show Subtitle” for every instance with the Standard Values; I had to modify them programatically, or else deal with a very tedious manual process.
How to do it:
This import only requires on line in the CSV, with the following values:
- Item Path: /sitecore/content/home/NewsListings (the folder where I needed to modify all items)
- Apply to Subitems: TRUE
- Template: News Listing Page (only modify pages of the particular template)
- Component Name: Dynamic Content Listing
- Parameter Name: Show Subtitle
- Value: 1
I uploaded the file and checked Publish Changes so that I could publish all of the modified pages without manually publishing the root folder, which would risk publishing changes that weren’t intended to be published yet.
Example 2: Change the placeholder of a rendering
The second issue was that the client had hundreds of pages of a particular template (Article Page) on their site, and they decided that they didn’t like the position of a particular component (the metadata component, which showed the date published and the author). They wanted it moved from the side of the page to the top content, beneath the Page Header and above the Social Share Bar.
This couldn’t be done with a simple CSS or HTML code change, because the metadata was a component on the page and the place it showed up was based on its placeholder (although technically it could maybe have been moved with CSS, it would have been hacky and not the right way to go about fixing it). So, I needed to update the placeholder and make sure it came before the Social Share Bar. Once again, with hundreds of pages to update, this would have been extremely tedious to do manually.
How to do it:
This import again only requires on line in the CSV, with the following values:
- Item Path: /sitecore/content/home/Articles
- Apply to Subitems: TRUE
- Template: Article Page
- When Placeholder Equals: Main Content Left Column
- Component Name: Page Metadata
- Placeholder: Header Content
- Before: Social Share Bar
The reason I used When Placeholder Equals is because I only wanted to move the Page Metadata when it was in the Main Content Left Column placeholder. If it was already in the header, or somewhere else on the page, I didn’t want to risk modifying it since it was either already in the right place, or somewhere else intentionally.
When run, this import moved the
The examples I provided were cases where only one instance of the component I needed to modify existed on each page. The import gets more difficult if, say, there are three Page Metadata components on the page; you will need to make sure to target the correct one, and use Nth of Type and/or When Placeholder Equals if you wish to modify other than the first one.
This consideration also applies to Before and After; if there were, say, three Social Share Bar components, Before would place the Page Metadata before the first Social Share Bar; After would place the Page Metadata after the last Social Share Bar.
One thing the import currently does not offer is the option to modify ALL matching components; you will have to add a new line with a different value for Nth of Type to update all instances of the component.
I recommend practicing the Rendering Parameters Import on some test items before making changes to real items. As always, use caution, especially when Publish Changes is checked, as this import can mess up your content if mistakes are made in the CSV.
You can download the new release on Github.