In this post I’ll be going over the various advanced custom code and configurations you can apply to the Sitefinity content editor along with tips and tricks to wrangle the admin the way you need it so it can perform at the optimal level for your client.
Cool Custom Textbox! Now what…
So we left off last time creating our very own custom field in code using Sitefinity Thunder and inserting it into a Sitefinity Content Editor. As of right now you’re thinking, “but it’s just a text box,” but that’s the starter-set for an entire custom field collection. Almost every custom field type will start as a custom text box created in Sitefinity Thunder. From there we can mold it into whatever we wish.
Outside the textbox, I find one of the most common form inputs to be the good ol’ fashion dropdown. Most of this blog piece will cover the code intricacies of our newly created custom textbox and how we will fashion it into a full-fledged, data-driven dropdown that saves selections in our content form to the database.
For your viewing pleasure I’ve attached the field and its files here you can follow along at home if you like. Keep in mind it in order to toss the same code into one of your existing projects you’ll probably need to adjust some namespaces, otherwise it should make a great reference for your future custom fields.
What’s in the box…
Let’s go ahead take a look at the code files generated from Sitefinity Thunder. There are six files altogether, three of which you’ll generally do most of your coding in. Depending on what you named your field, it generates a like-named ASCX, .CS, and .JS file that gets created along with three Definition .cs files, which we won’t be changing; these mostly control elements that are already editable in the WIZYWIG and it’s generally unnecessary to alter.
DIVE! DIVE! DIVE!
Let start with the simplest file, the .ASCX. Like any custom user controls created as widgets, this is the “face” of our field. You can see our pre-generated Text Box, “fieldBox”, along with a description and example label. These objects are fed information on page load from the accompanying .CS file.
Tip/Trick: For you interfaces out there: I found classes and styles work generally the same as they would on any other .ASCX page, however, I suggest linking to specific css files as the field tends to not find layout and master page references due to the nature of the admin (I suggest a separate CSS for the admin altogether anyways). Putting this on the page, For Example, will usually do the trick:
<link href="/Sitefinity/WebsiteTemplates/HWH_Desk/App_Themes/Styles/CSS/AdminEvents.css" rel="stylesheet" type="text/css" />
Before moving on to the .CS, let’s go ahead and make that an ASP drop-down as we won’t need to change anything else here later. Take notice I added the “ClientIDMode=’Static’” attribute. This will come into play further down the road, but ideally we want to know exactly what our dropdown’s id will be in the DOM, otherwise ASP.NET will generate a unique one for it (which for custom love later on is not what we want). If you plan on making a custom field “Template” that you plan on using multiple times, stick with the Client Generated ID, otherwise I think you’ll find doing this for all your truly custom fields will be a major stress-reliever later on.
OK, now for the meat and potatoes, the .CS. There’s nothing too crazy going on here, you have properties being defined for the ASCX controls, methods for initializing and populating said controls, Script Descriptors/References for the .JS files, and some file path references (these you would most likely change if we we’re trying to implement a 3rd party custom field).
Let’s take a look at the generated properties. You can see the ExampleLabel and DescriptionLabel shorthand setter/getters, which we don’t want to change as they work perfectly fine, but we need to replace the textbox because clearly it will no longer exist in the ASCX.
Also, check out the override Object “Value”. This is the Value that Sitefinity saves into its database to handle the custom field, whether it’s a short-text string, int, decimal, you name it. This is what you’ll be setting your controls value to. Let’s go ahead and replace that Text Box with a Drop Down.
Ok, the fun part. Let’s populate our drop down with some data! Just below our new DropDownList property you’ll see an override method for InitializeControls. This is where we’ll populate our dropdown.
So let’s go ahead and add a simple set of hardcoded choices and map out some values to populate with for demo purposes. Keep in mind you can save any value type to the database (in this case I’m using an int value) just be sure to select the appropriate value when you register your field control in Sitefinity.
Before moving onto the script file we need to map descriptors for it. You can see now that the TextBox property has been removed it’ll throw an error, we need to update it.
Take note of the name-change to “dropDownElement”, we’ll use that later in the .JS file. Also see that instead of ClientID we map to the normal ID as noted in a previous page.
Ok the last piece, the .JS File. Sitefinity uses these files to load in save/load commands as well as logic to be used in the DOM for their particular custom pieces. The .CS file that loads the data and Value for the custom fields doesn’t actually save or manage it, the .JS file does. This is also the piece where we can manage modal editors should we need to (like a file selector) before processing the form request. From there content items are saved and managed by a specific Decorator Event Class (which we’ll talk about in part III).
Go ahead and replace all the “textBoxElement” values to make the script kosher with the rest of the code base. Keep in mind, if you needed to rename your namespace there are several (at least 8) items to rename here.
Ok we’re ready to register our new dropdown. Like in part I, go ahead and register your project, this time as an int value.
Once you’ve filled out the appropriate fields and labels to the custom fields sections your dropdown will appear and be ready to go in your Sitefinity content type.
All that for a drop down?
Yes for demo purposes we stuck with just a hard-coded dropdown, but what you’re really doing is integrating a new ‘Type’ into the Content Admin. This can be more than just a dropdown but any cross-type integration. For instance, we recently integrated Intellipad and Constant Contacts CRM systems into one of our client’s Sitefinity Event Content, effectively mapping the three together with Sitefinity as its hub using custom dropdowns. Here’s a little taste:
Say instead of that hardcoded list we pull in a direct list of the clients mailing lists through CC’s API. You can then create another drop down for “Email Campaigns” and include a button on the ASCX for the custom fields. On click you can kick off a service call to create email campaigns and call lists based on people that signed up for this particular Sitefinity Event. Remember when I had you set those ID’s as static? Well the different fields can ‘talk’ to each other by using scripts that look for their fellow form-mate’s selected values. These functions can live right on the ASCX pages along with the inputs and collaborate together for powerful functionality like create emails for mailing lists from right within the form, all without even posting back.
From a styling standpoint you can take this a step further too. As mentioned earlier in the article, styles can be linked in the individual forms to style individual custom pieces, but you may want to arrange them in a format that better suits your admin as opposed to how Sitefinity displays it. You can move these items by altering the live .config files associated with the content in the configuration folder of the App_Data/Sitefinity folder in the project (where the data config lives). After a custom field is added for the first time these files will be generated and will allow you to move around and style your fields to your liking.
Note: the different ‘view’ types. This will allow you to separate how your fields are visible depending on the action of the content. For instance wanting to hide certain fields on object creation that would only make sense during an update process. Simply ‘arranging’ the fields in the xml will allow you move fields around, even in the following example into more manageable accordions if you desire to style such.
One thing to note about this is it can be tedious as Sitefinity writes to these files any time you alter custom fields, so I suggest waiting to style the frame of your fields until after you’re done creating them. Once you’ve made your swapping and arranging you can get a much neater admin.
It takes some experimenting, but the advanced custom field creation and styling can bring a lot of exciting new prospects to a once seemingly rigid structure that is the Sitefinity Content Admin. It can also be time consuming, so be sure to be ready for long haul; just keep in mind it’s certainly worth the client’s greatly improved experience in the end.
In my next blog piece, I’ll be talking about Event Decorators and how they allow you to handle many qualities of the Sitefinity Content process on post-back of the admin content management process; including custom data and event handling, task management, and more.