During a recent discussion with @TashasEv, the topic came up of preserving site definition when rolling out jQuery form enhancements. The preservation of site definitions is something that many people ignore, but in the interest of best practices I figured it was worth a blog post to explain some of the pros and cons, and offer some solutions.
Many of us (myself included) use jQuery to enhance out of the box (OOTB) SharePoint forms. jQuery allows us to make a variety of minor or major changes to the usability and functionality of forms either through straight jQuery or with Marc Anderson's (@sympmarc) popular jQuery Library for SharePoint Web Services (SPServices). Cascading dropdowns, content relevant fields, dynamic changes to styling, and other enhancements can greatly improve the user experience and the data entry side of a form, but can be the achilles heel of your support model if done incorrectly.
In layman's terms, the site definition is the foundation on which all OOTB SharePoint sites, templates, forms and pages are based. Essentially, this allows you to manage assets within the site by managing the site definition. An easy to understand example would be upgrading your SharePoint environment. If a version upgrade or service pack comes along that touches the site definition, all objects using that site definition will be updated accordingly. The issue lies in the fact that when you open your OOTB SharePoint form in SharePoint Designer and edit it, you essentially disconnect that form from the site definition. Six months down the road when you upgrade your environment or push that next service pack, your form will now not be updated. Additionally, if you find yourself in a position where you need to consult Microsoft for support, Microsoft can very well point out that you've customized the OOTB code, and refuse your support request.
SharePoint Designer makes it very easy to tell when you have an item that's separated from the site definition, as those files are marked with a blue information icon as seen below: So you may be asking yourself... how can I add jQuery to my forms if I can't edit the code directly. Well, there's a couple different approaches:
- Create a new form: One method is to create a new copy of the form. You're still going to disconnect the form from the site definition, but you'll at least preserve the default OOTB form's association with the site definition. To do this, load the OOTB form (ie: NewForm.aspx) and highlight and copy all of the code. Next, create a new .aspx page within the same folder and paste all of the code in. You can now make the necessary changes to this custom file, and save it as a different filename (ie: NewFormCustom.aspx). You can then right-click on your list in SharePoint Designer, select "Properties", and go to the "Supporting Files" tab. Here you can select your custom form using the browse button, which tells SharePoint to use your custom form rather than the default OOTB form from here on out. This method allows you to preserve the OOTB form without compromising it, and still allows you to directly edit the source of your custom form.