There are so many great resources out there that help developers learn “how” to do things. For young professionals just getting into their SharePoint development careers or for individuals looking to make a career shift towards SharePoint, this post is for you. When I began using SharePoint as a data analyst I was immediately drawn to the power of this platform. There were so many things that I could use SharePoint for beyond the obvious file storage capability.

I started building customized sites within my department’s collection for my colleagues. I built collaboration sites for management to review my reports, act on findings and organize their annual planning activities. After that, I continued to build sites for the Legal, R&D, and Operations departments. I was soon looked at as a SharePoint subject matter expert, but was far from it.

My focus for this post is to highlight some of the major pitfalls of SharePoint that early developers can come across.

Hopefully by shedding light on these topics it will save you from a good bit of trouble! This article will focus on my top 3 areas that a new SharePoint developer should gain a better understanding of prior to development.

This is not a list of things you should stay away from, not at all. I encourage all of you reading this article to be more eager to learn these areas of SharePoint. You will feel better equipped to employ best practice techniques in these areas and can be more confident in your SharePoint development.

Let’s get started…

Content Types

This is a big one. Content types are a sore spot for me which I will explain later. When I began working with SharePoint and started customizing lists and libraries, I naturally came across Content Types as many of you will. They can be incredibly useful when building your SharePoint solutions. However, a lack of knowledge of content types can get you into a good bit of trouble, as it did for me!

Content Types as defined by Microsoft:

“A content type is a reusable collection of metadata (columns), workflow, behavior, and other settings for a category of items or documents in a SharePoint list or document library. Content types enable you to manage the settings for a category of information in a centralized, reusable way.”

Content types have a hierarchy which starts at the System Level and works its way down. For example, if you were creating a custom list for your SharePoint solution then you will begin with the Item content type which is a direct child of the System content type. However, when customizing a list using content types you will actually be working with a child of the Item known as a List Content Type.

List content types are a direct copy of the site content type which you started with but are isolated from changing the site content type which can be very useful. For instance, you have a template content type that is broadly used but needs minor modifications for each department. You can add your custom content type to the list and then modify the list content type instead of changing the site content type.

So where do you need to focus your attention?

When creating a custom content type based off of a parent content type, such as Item, you will need to use caution when customizing existing site columns. Whenever you use Item as a parent it will, by default, include the Title column. Renaming the Title column can have an adverse impact to your site collection. Now that you are creating a site content type and using site columns, any changes you make to that column will affect all lists and libraries that use the site column. Also, making changes to an existing site content type can have an effect on lists or libraries that use that content type.

Where I went wrong was when creating a Site Content Type for a customer I had renamed the Title column to something more specific, such as “Article Name”. However, I also chose to “Update all content types inheriting from this type?” and I had navigated up to the Item level. By performing this action at the root level of the SharePoint site collection, I effectively renamed the Title column for all lists and libraries (yikes!).

Okay, but couldn’t you just change it back? The major problem with renaming a column like “Title” is that it’s a reserved column name. Once you’ve made this change the only way to undo the mistake is to run custom scripts, modify the database using SQL (Microsoft does not approve of this) or use SharePoint Administrator, which many of you may not have access to or be familiar with as a beginner. So this is a big one. In my case, I found some custom JavaScript which I was able to run in the console window to bypass the reserved name validation and return the column back to “Title”.

Key takeaways for Content Types:

  • When creating Site content types be cautious when renaming existing columns.
  • Do your research on the impact of modifying content types while using the “Update all content types inheriting from this type?” feature.
  • Modifying list content types is a safe way to make customizations to site content types used in your custom lists and libraries.

 

Custom CSS

Using custom CSS in SharePoint was widely used to brand a SharePoint 2010 Site Collection. With the introduction of SharePoint 2013, custom CSS was still a great way to brand a SharePoint Site Collection. However, 2013 introduced themes which could be tailored more easily, and for many customers that was enough. Even though we are approaching another release of SharePoint, there are still many businesses using SharePoint 2010 and custom CSS is still a great way to make subtle changes to a master page that can enhance the user experience so it’s definitely worth noting.

When using custom CSS to style a master page for a SharePoint site, many developers will start by changing colors for links, headings, backgrounds, etc. Where developers can run into trouble is when changing default font sizes, fonts, and generic classes. In SharePoint 2010 the UI was much more rigid than it is in 2013. By rigid I mean that if you were to change the default font size for the <body> tag or <p> element to enhance legibility for users; there could be an impact on pages, settings menus or dialogs causing them to become unreadable.

Because there are so many different components to SharePoint, using the out of the box controls to manage fonts and colors is highly recommended for new developers. Microsoft has already come up with the safeguards to adjust the UI accordingly when selecting fonts to be used on the site. As for colors, there are specific tools that can be used to generate a new color pallet which is branded to your organization. The SharePoint Color Pallet Tool has all of the proper contrast warnings so that you can be sure that the selections you are making will not render any UI in SharePoint illegible.

How can you still use custom CSS but not affect the SharePoint UI?

Well, you can start by creating your own custom classes and styling those. If you want to keep things simple and easy, then create custom page templates and wrap your content in a <div> with a custom class so you can target all of the styles within the wrapper. That way you can still use the generic element selectors like <p>, <div>, <hr>, <span>, etc. but you are targeting the wrapper first.

Key takeaways for Custom CSS:

  • Avoid changing fonts, font sizes, and generic classes through CSS. Use the out of the box tools for customization when possible.
  • Leverage tools like SharePoint Color Pallet Tool for color customizations to ensure correct contrast ratios are obtained.
  • When customizing generic elements such as <p> and <span> elements use a custom wrapper to avoid changing dialog boxes and menus.

 

Content Query Web Part & ItemStyle.xsl

The Content Query Web Part (CQWP) is a great tool to display data from a list in an organized way which is customizable and can be managed dynamically. The CQWP is connected to a list and can have filters applied to sort and pull only relevant data. It also can dynamically filter content when placed in a page template based on the current page name or other information.

The reason that CQWPs are so powerful is because they allow you to query list data and display them as a custom web application. The list data can be placed inside HTML elements, organized, and additional custom HTML elements could be added such as buttons or input fields. By using the ItemStyle.xsl file to build your custom templates a developer is able to build an interactive UI or just a more attractive UI than the typical out of the box SharePoint list.

In SharePoint 2013, there was a new way to manage the display of the List View Web Part using JSLink. A custom JavaScript file can be attached to a List View Web Part to override the display of the columns and do exactly what the CQWP did but with arguably less work and more reliability. Even with JSLink, many developers may still lean towards the ItemStyle.xsl customizations.

Here is where you will want to focus your attention.

The ItemStyle.xsl file controls the display for all Data View, Content Query, Search Results and Business Data Catalog Web Parts. If you are new to HTML or XSLT, then use caution when saving changes to the ItemStyle.xsl file in your new template, because a mistake there can cause errors in all of the previously mentioned web parts when rendering.

The best practice approach when using the ItemSyle.xsl file to customize your CQWP is to create a copy of the ItemStyle.xsl file and rename it to something specific for your solution. By doing this you can be sure that mistakes made in the file will only affect your web part and can simplify the available templates since you have the ability to remove any unused templates for your specific needs.

From there you will need to do your research on how to link up your new custom ItemStyle.xsl file to your CQWP but the basic steps are to export your CQWP, modify it in a text editor or SharePoint Designer and change the <property name=”ItemXslLink” type=”string”></property> with a path to your custom file. From there you will upload the web part back into the page, delete the original one and voila your web part now uses your template and not the default ItemStyle.xsl. At that point, your custom template will be available in the Web Part Properties menu.

Key takeaways for Content Query Web Part & ItemStyle.xsl:

  • Always be sure you review your HTML/XSLT in your ItemStyle.xsl file before saving because errors in your code will affect other web parts throughout your SharePoint Site Collection.
  • If you have a requirement to display list data in a customized UI, look into the new JSLink feature in SharePoint 2013.
  • Best practice is to create a copy of the ItemStyle.xsl file and update the CQWP to use the custom file rather than modifying the original.

I hope for any new developers reading this article that you found this content helpful. As a said before, I encourage you to find more information on these topics to become more confident as a SharePoint developer. See below for links to great resources on these topics that will kick start your understanding of the concepts covered in this article.