Bulletproof Components (Part 2): Back End Checklist

Index

We've covered the front end checklist in part 1. Let's move to the back end.

• Does the template inherit from a base template? Should it?
• Is your client educated on the limitations of certain fields?
  • For example, do they know that they can't add links / bolded / italicized text in multi line fields? It would be highly unfortunate if they asked you to change all of the multi-line text fields to rich text field after all the development was done and the content authoring already began...
• Does your template have standard values?
• Do your field and field section names make sense?
  • Do the names follow conventions?
  • Should any fields or sections be pulled out and moved to somewhere more general?
  • Do your field types and names match the requirements?
    • If development has already commenced and you need to change template names to match requirements, consider changing the display names rather than the template names.
• Do all of your fields have proper validations?
• Do your fields have help text?
  • If you're having a hard time coming up with help text, imagine being the content author. What would they want to know?
  • Does your help text have any typos?
  • Are there any quotations in the help text? This has been known to break the Experience Editor.
• Does your template have a unique icon?
  • Did you verify that the icon path is not a temp icon?
  • Icons with temp in the path will not be deployed upstream.
• Are fields and field sections ordered properly?
  • Make sure to test this on a content or Standard Values item because template inheritance can affect the end results.
  • This can be controlled with the Sort Order field.
  • Once template inheritance gets more complex you may need to take some time to map out the sort orders in a spreadsheet.
• Should any fields be shared? This standardizes field values across different languages of an item.
  • Think carefully about which fields should truly be shared. Toggling the shared status of a field can cause major content authoring issues. There is a reason Sitecore warns you before turning the shared status off!
• Have the insert options been set up?

• If your item(s) are bucketable:
  • Think very carefully about anything that could be stored within a bucket, both now and in the future.
  • Do the items in question need to lock their child relationships?
  • For example, if items within the bucket have children, should that parent item lock its relationship with its children? If the relationship it not locked, those child items will be moved unexpectedly when the bucket is synced.

• Should your rendering have thumbnails?
• Has your rendering been added as an allowed control in all relevant placeholders?
• Does the rendering have a proper datasource location?
  • Does it need more than one datasource location?
• Does the rendering have the proper datasource template set?
• Should the rendering have its own custom experience button(s)?
• If your template has a branch associated with it, is it set as the datasource template on the rendering?

If you use an existing Sitecore module (from the Sitecore Marketplace or github) to get your component completed, there are a number of risks involved. Many modules provide an astounding amount of functionality, but one must remember that most of the modules were hacked together under severe time and resource constraints.

The creators of these modules are brilliant, but since the modules are usually built by only one developer, support is often poor. The codebase is often cryptic and full of bugs. Most of these modules were selfishly built for a very particular implementation, and your implementation may vary greatly. Additionally, many available modules were developed prior to the shift to more complex cloud architectures. In other words, most modules were built for deployments to standalone instances of Sitecore.

Unless you understand the module completely and have control over the code, you are exposing yourself to more risk than you may realize -- even if it seems to work during your initial testing. Issues often crop up only when deploying to production.

An approach worth considering is the consumption model. Though it takes more upfront work, many benefits can be realized. The idea is to fully integrate the module into your solution (software license permitting, of course). This method will make your deployments smoother (less manual actions) and allow you to easily make changes. With modules, more often than not you will have to make changes, so why not set yourself up for that possibility to begin with?

The following checklist items will help you perform the conversion.

• Will all binaries be deployed on all upstream servers?
  • The problem with installing modules via Sitecore packages is that the files will only be installed on the CM server. What if your CD server also needs the files? What if you have many CD servers? Best to automate those installations!
• Do you need any config transforms?
  • Some configurations may vary between your different environments.
• Using your item serialization method of choice, are all of the items included in your solution?
  • Which items should always be deployed?
  • Which items should only be deployed once?
• Once the module is fully consumed, has it been done so in a way that makes it easy to reuse the functionality in other projects with minimal additional work?
  • This is a great test of whether or not the consumption has been done correctly.

• Do the JavaScript dependencies of Sitecore Forms conflict with your JavaScript configurations?
  • This is often the case with jQuery in particular.
• Do any of your forms have text fields?
  • Sitecore does not specify a max length for text fields. You must specify a max length and ensure that validation of the field is enabled, otherwise form submissions can become a security concern due to their length.

• Did you leverage indexes where possible instead of making direct calls to the database?
• Did you avoid the "God Index" problem by creating a custom index for your specific business case?
  • Bloating the default Sitecore indexes (master, core, web) can cause performance issues and can cause reindexing to take a long time.
  • If you're using Azure Indexes, they are limited to 1000 fields. By default, Sitecore indexes all fields. Once you reach a decent number of templates, you will likely reach that limit very quickly. Especially if your project is multilingual. In your Azure indexing config, you'll need to disable the indexing of all fields and only add the fields you need.

• Does this field NEED to be a rich text field?
  • Other fields such as single-line and multi-line text are safer and encourage content authors to conform to design standards.
  • There are less opportunities for content authors to break pages with problematic HTML or JavaScript.
  • Consider if a more restricted field type will meet your client's needs. One creative option is to consider using a custom markdown field.
• Should standard values include boilerplate HTML content?
  • This may help your content authors.
  • Is the HTML in the standard value valid HTML?
• If you're giving the users the option to add HTML snippets, do they work as expected?
  • For example, if you have a snippet that has nested containers and one of the elements contained within it is a <p> tag, the RTE may unexpectedly shift the elements around.
  • Snippets are all around quirky to deal with, but there are ways to structure the HTML and the styles associated with them such that the RTE won't break them.
• Did you adequately restrict what the content authors can enter in the field?
  • You can leverage different rich text editor profiles to impose limits.
  • Think rich text lite and rich text full.
• Instead of allowing content authors to apply classes to elements, did you consider the more intuitive process of allowing them to instead apply different paragraph styles?
  • Paragraph styles are not limited to Heading 1 and Normal Text.
  • They can be customized to be any type of HTML element with any number of classes applied to them.

• Do any visual elements contain hardcoded text?
  • Make sure content authors can edit the values using dictionary items or fields on the related item(s).
• If your code is dependent on other projects, are you keeping the Stable Dependency Principle in mind?
  • _The dependencies between packages should be in the direction of the stability of the packages. A package should only depend upon packages that are more stable than it is._
• Does your feature fail gracefully when no datasource is present?
  • If the datasource is missing, the ideal behavior is to show a useful error message in editing mode, and to hide the rendering entirely in preview or normal mode.
  • This prevents a single rendering from breaking an entire page, or in the case of global components such as navigation, breaking the entire site.
• Did you rewrite code that has already been written?
  • Become familiar with the code that is already at your disposal in your foundation projects.
• Does your component adequately handle broken link selections?
  • This can occur when a target item is missing (especially across different deployment environments with different content), or when the target item does not have a version in the specified language.
  • If you have multi language support, consider using item.Versions.Count > 0.

• Did you test your component in the Experience Editor?
• If your component requires a datasource, did you test your component without a datasource assigned to it?
• If your component requires a datasource and the datasource is missing, are you conveying that to the content author in edit mode?
  • Do you need to prevent the rendering from appearing in preview and normal mode?
• Did you make use of custom experience and edit frame buttons to make the content authoring experience easier and more powerful?
• Should any fields have DisableWebEdit = true?
  • In some cases you'll want to pair this up with an edit frame to force the editing to be done in a popup window that provides a more complete authoring experience.
• If the content author is creating new content in the Experience Editor, were the datasource locations properly specified? The following formats can be used:
  • ./Data|\{GUID\}
  • ./Data|sitecore/path/to/item
• Do your text fields support the addition of special characters such as ©?
  • Should the content authors also be able to add the character with ©? If so, you'll need to render the raw HTML of the field.
• Are images editable from the Experience Editor?
• Are all component fields editable from the Experience Editor?

• Is your component multisite compatible?
  • Even if the requirements aren't asking for multisite functionality in the beginning, it is often the case that clients will eventually migrate their other sites onto the Sitecore instance.
  • With only a bit of extra mindfulness during the development of each component you can save yourself a world of headaches when the client asks for the functionality in the future.
• Are your tree location source paths site agnostic?
• Did you avoid the use of paths in favor of item IDs?
• Is all dictionary-like text such as Open Menu or Search stored in a location that can be shared by multiple sites?

• Does your solution contain any circular project references?
• Does your project contain any cross project dependencies that can be removed?
  • Don't forget about your item serialization configuration too! It's very easy to amass implicit dependencies on items and directories specified in other projects.
  • Remember that your functionality should be modular enough that you can move files and items from solution to solution without much setup.
• Does your project contain any unused references?
  • This is typical of projects that were created via copying.
  • ReSharper has a great cleanup tool. Make sure to test after you're done!
• Are any of your web config files set to deploy when they shouldn't be? Check these properties:
  • Build Action
  • Copy to Output Directory
  • If your web configs are set to deploy, they may overwrite the vanilla Sitecore configs and break the site.
  • Remember that in addition to the web config in the root directory, there is also another one in the /Views directory.
• If you store SCSS / LESS / CSS files within the solution and you don't want the files to be deployed, are the file properties set to Build Action: None and Copy to Output Directory: Do not copy?
• If you need config transforms, did you test that they're working as expected prior to deploying upstream?
• Does the solution build in debug mode?
• Does the solution build in release mode?
• Are any items getting deployed that shouldn't be? Config transforms, webconfigs, README, and SASS files are the usual culprits.
• Would it make sense for your project to have a README.MD?
  • What should other developers or future developers know about your component? How to install it and use it would be a good start!
• If items need to be installed upstream do you have a good method of ensuring those get installed prior to QA starting?

• Are multiline text fields displayed via a proper field renderer such as @Html.Sitecore().Field?

  • If not, the line breaks won't work.

• Are multiline text fields wrapped in an appropriate element, such as a <p>?

• Do your link fields display their target, rel, and title attributes if not using the field renderer?

• Do image fields should display their alt text if not using the field renderer?

• Do you have any cases where elements will be excluded because their values are optional?

  • Do the absence of those elements break the view?
  • What if you have multiple fields that are optional? The permutations begin to add up...

• Can any of your duplicated HTML be consolidated or made more readable using @helper methods in your view?

• Are special characters displayed properly?

  • Content authors often need to add symbols such as ™ and ®.
  • Consider thinking about how content authors are expected to enter these characters and how your view displays them.

• If your component has various rendering options that customize its appearance, did you test all of the variations?
  • Better yet, did you create a page that contains all of the variations that other team members can see?
• Did you create a new rendering and new data source item in the view from scratch?
  • This will help you identify default data and display states, insert options, standard values, validation, and so on.
  • Better yet, did you test this using the same role as a content author? After all, we are building these components for the content authors!
• Did you run your HTML through an HTML validator?
  • Sitecore and Visual Studio also have HTML validators built in.
• Did you add more than one instance of the component to a page to test that CSS and JS is properly scoped?
  • Multiple instances of the same component on a page can be problematic if CSS and JavaScript is not scoped properly.
• Do the Sitecore logs have any exceptions?

In part 3, we'll explore some more general considerations.