Showing results for 
Search instead for 
Do you mean 

Step by Step Guide to Custom Form Development with Visual Studio

by Administrator Administrator on ‎12-15-2009 01:48 PM

Today I'd like to extend a huge welcome to Nicolas (Nick) Galler.  Nick is a big part of the Sage SalesLogix community and has a self-proclaimed passion about programming in general, CRM & Sage SalesLogix in particular. Nick is the first of our community members to guest blog here in the Journal and he'll be sharing how to develop custom forms with Visual Studio.  Nick, take it away...



Step by Step Guide to Custom Form Development with Visual Studio

By: Nicolas Galler, Strategic Sales Systems

 

1. Why Custom Forms?

 

While we all love the App Architect and its form editor, sometimes it is necessary to step beyond it to achieve some interesting layouts, use some non-standard controls or client-side script, work around some limitations, reuse some existing HTML or just to speed up development a bit.  Unfortunately it is a bit hard to get started and make sure the custom forms get correctly integrated within the Sage SalesLogix framework, even with previous ASP.NET experience, and if you are not careful it can quickly become hard to maintain. This article is a walk-through on setting up Visual Studio for development on the SalesLogix web site by designing, creating and debugging a relatively simple custom form, and setting up the tools necessary to keep those custom forms synchronized with the SalesLogix project.


The pre-requisites are quite simple:

 

  • You will need Visual Studio version 2005 or above (preferrably 2008)
  • The instructions are written for Sage SalesLogix 7.5.2, but almost everything will also apply to 7.2+
  • A tool for synchronizing files, for example RoboCopy – if you don't have that yet I will get to it
  • Some HTML and CSS experience is necessary.  You just need the basics to get started.  There are some good tutorials at http://www.w3schools.com for example
  • Some knowledge of ASP.NET – no need to be an expert, but if you are totally new to ASP.NET I recommend you follow one of the many available tutorials first, out of SalesLogix.

 

My hope is to show you that daunting as it may seem at first, there is actually not much to do – Visual Studio is a pretty good editor and it will do its best to help you do most of the typing. Before we start, I do need to point out the few serious limitations with using custom smart parts instead of Quickforms.  They are no silver bullet and selecting the wrong one can be a serious impediment, so do keep the following in mind:

 

  • Custom smart parts will generally not take advantage of any new feature added to Quickforms
  • They will quite often take more work to upgrade, because you will have more exposure to any API change, or even to changes in the base SalesLogix style sheet
  • With the increased flexibility it is much more easier to “shoot yourself in the foot” and completely confuse ASP.NET, or create designs that do not display correctly in all browsers
  • The increased flexibility also mean that you are the only one responsible for keeping the code clean and maintainable
    Finally, they will require basic ASP.NET knowledge to even make a small change to, which may make it harder to find a developer to work on, unless your team is 100% web developers.

 

 2    Our Sample Form

 

This is the layout I am aiming for.  It probably looks quite familiar:

 

 

Now, it is possible to get something close to that using a quick form, but making it custom makes it a bit easier to keep a tight layout.  I chose a form with little logic so as to not get mired into discussion on ASP.NET or JavaScript – don't worry, the article will be plenty long enough without it!

 

3    Basic Setup and Layout


First things first, you need to get your SalesLogix project out of the database VFS and onto your local file system.  This is not an absolute requirement but it will make things twice as easy when synchronizing files.  To do so, open the project workspace manager (View → Project Workspace Manager), right click on it and select “Add”, enter a chosen name (e.g. “MyWebClient”) and path (e.g. E:\Projects\MyWebClient\Model), check the box for “Export Files Upon Creation” and click “Create”:

 

 

Do a full build and deploy your site to your local web server.  Then, start Visual Studio (if you are on Vista, you will have to start it as an administrator by right clicking on the shortcut and selecting “Run as Administrator”), and go to “Open Web Site” under the File menu.  Then under “Local IIS” select your web site.

 

 

On the right hand side you should now see a section called “Solution Explorer”.  Navigate to the folder that is to contain your custom smart part, right click it and choose “Add Item”, and select “Web User Control” in the list.  In my case I navigated to SmartParts\Contacts, renamed the old ContactDetails.ascx, and added my replacement.  If you are adding a brand new form and not replacing an existing one, you need to follow the steps at the end of the article (under “Bringing it back to the project”) at this point.


Open your new control.  Depending on your configuration, Visual Studio may open it in the design or the HTML view.  Because the SalesLogix web controls are not very designer friendly, I recommend using the HTML view exclusively.  You can change the default under the editor options of Visual Studio (Tools → Options → HTML Designer).

First you need to add “Register” declarations for the SalesLogix controls – this is what lets you use controls such as Lookups and Picklists in your form.  To this end, open another user control (doesn't really matter which) and copy/paste the first few lines (all the lines that start with “<%@Register”, but not the first one).  Your file should look like this: 

 

Switch to the code view (you can press F7, or open the .cs file in the solution explorer) and change the super class (where it says “System.Web.UI.UserControl”) to “EntityBoundSmartPart”.  As you type this you will notice that the “EntityBoundSmartPart” part is not colored (meaning Visual Studio is not recognizing it as a class) however there is a small, red rectangle near the end of the word. 

 

 

This is your cue that Visual Studio wants to help you.  You can put your mouse over that rectangle or use the keyboard shortcuts “Ctrl+.” (hold control key and press period key – though it might be a different shortcut if you are on a non-US version of Visual Studio, I guess).  This will offer you to import the relevant Sage namespace – hit enter and it will add it to the “using” list.  For some reason if you are in VB instead of C# you have to first go to the next line then come back to be able to get this auto-fix feature.  But other than that it is probably the most awesome Visual Studio shortcut.  Now the text is highlighted but you can see a small, blue rectangle on the left side of the word.  This is also a cue that Visual Studio wants to help you.  Press “Ctrl+.” again and it will offer to implement the class – you just have to fill in the blank.  I add a “CurrentEntity” method at this time which is going to make my life easier later on:

 

 

 

Switch back to the design view (which is still empty) and let's start putting together a rudimentary design.  For now I just want to do the general layout.  If you are an HTML wiz you can probably just zoom through that but I like to take my time.  At this point this is what I have on my form:

 

Note the sss_custom class.  Just something I use to be able to apply my own CSS to the form later on.  You can make up your own name obviously.  Also note that I am not using localization (the <%$ %> type tags).  A big advantage of the quickforms is they make localization very easy.  It is not quite as quick to do in regular ASP.NET so I just skip it.  If you need to show the interface in more than one language look up “ASP.NET localization” and follow the instructions – it is really not tricky, just tedious.
Now reload the browser (no need to rebuild, redeploy, or wait for the web site to restart) and you should see something similar to this:

 

 

Obviously we have a few things missing – but we're getting there.  First I would like to get the toolbar back.  You can write it by hand or copy/paste it from another entity form.  Being rather lazy I chose the second method and pasted the following text in my form:

 

 

Back on the code side, change the base class from EntityBoundSmartPart to EntityBoundSmartPartInfoProvider and add an override for “GetSmartPartInfo” (what you do here is you type “override”, press the space key, then it will list the available methods – you just pick the GetSmartPartInfo one) and add a bit of boiler plate code (not sure why the smart part does not do that by default.  But I guess it just can't be that smart):

 

 

To be honest, because it is so boiler plate you'll probably want to put it in a “utility” class – that is what I do.  I am leaving that part out to make it simpler though.  Reload the form and you should get the toolbar.  If you made a typo you will get instant feedback, no need for re-log, etc (though you need to know that every time you make a change ASP.NET needs to recompile the page, this is very fast but after a certain number of recompile it will restart – in order to limit memory fragmentation – and at that time you will have to re-log).  Of course some of the toolbar buttons don't do anything at this point, we'll get to those later.

 

4    Toolbar Buttons

 

For new, custom buttons, or for the existing toolbar buttons like the Save and Delete buttons, the process is the same – you need to add the event binding in the OnWireEventHandler method.  Start by creating an override for it... again, if you just type “overr”, Visual Studio will help you complete the rest... then create the bindings.  You don't have to type a whole lot because Visual Studio will do most of the work for you – just “cmdS”, accept auto-completion, type += , accept auto-completion, press tab a few times, and presto, you get your method.

 

Then you fill in with the desired code for example just “CurrentEntity.Save()” in this case.  This is the final result for my event handlers:

 

 5    Let's Get Some Data

 

Now we need to get to the data-binding part.  This is the one area where I will want to use an external class of mine, just because data binding is so tedious to set up with the default SalesLogix API.  But first let me show you what it looks like with the SalesLogix API:

 

 

The problem of course is you will not get any help from Visual Studio on how to come up with the “FirstName” and “NameFirst” strings.  So I use a little helper class that gives me the auto-complete, taking advantage of Visual Studio 2008 and .NET 3.5.  I blogged about it before (Strongly Typed Databindings in SlxWeb), though  it had some issue on version 7.5, as the site was running on ASP.NET 2.0 by default.  It works great on 7.5.2.  If you using VS 2005, or are not on 7.5.2 yet, sorry, you might be better off using the “text” version above, unless you want to mess with your web.config file.  If you are on 7.5.2, create a class called “TypedWebEntityBindingGenerator” under the App_Code folder of your web site (just right click on App_Code in your solution and select “Add New Item” then “Class”) and paste the following (you can put it somewhere else if you prefer):

 

I won't go over the details on how this works because it is besides the point.  Anyway, this lets you write stuff like this, and get the Visual Studio auto-completion every step of the way:

 

 

As usual, reload the browser, and make sure the contact's first name is showing up.  By the way, now that we are talking about data bindings, you may notice some properties are missing and be tempted to add them to App Architect, which requires you to re-build and re-deploy.  Don't do that yet, because it might overwrite your stuff!  I'll show you what we can do about that later on.

 

6    Finish Up the Layout, a.k.a., HTML Slinging


OK, now you may be thinking, this is an awful lot of work just to show the contact first name, and you would be right, of course.  But there is a good reason we go through all that, and it will get a bit quicker now that we get into the layout proper.  Time to sling some HTML!  I find this goes pretty fast because ASP.NET will do the auto-complete for you.  But I still have to peek at the existing Quickform sometimes to find out how to form a particular control.  Keep refreshing your browser as you do it to make sure it looks OK.  I practically refresh mine after placing every control.  But then, maybe I just like the instant gratification it gives me.  You can wait a bit longer.

 

Well this is the result.  It is a bit cramped but then so is the original screen.  I think it is rather faithful to the original myself:

 


One thing I like to do, is set up a minimum width on the columns, so that they don’t get all squished up if they users are running in a very low resolution – the form will just have a scrollbar in that case.  But on the other hand if the user has a very large resolution the form will expand to the available space.

 

It goes pretty fast once you are used to it.  Some controls take a bit more effort... e.g. lookups... but for the most part it is relatively straightforward.  For example, this is the code for the first column:
 

By the way this is what the design view looks like in Visual Studio... now you know why I am not using it:

 

 

And now time to fix all these databindings.  Fortunately with the intellisense that goes pretty fast too.  If you are missing some properties, do not add them to App Architect yet – read the next section first.  Here are the bindings for the first column:

 

 

7    Debugging / Troubleshooting


This is really similar to the way you would troubleshoot a quickform, or indeed any ASP.NET form.  The main differences are:

 

  • The code should actually be legible (and if it isn't, you only have yourself to blame for it, hah!)
  • You do not have to keep track of what you are changing so as to be able to replicate it in the quickform designer, since you are working on the live design (see the next session for how we will bring it back to the project automatically)

 

There are a few ways to launch the debugger – what I do is, I run everything under IIS (so it is pretty much the same as running a Saleslogix production site), then when I need to debug I go under Debug → Attach to Process and attach Visual Studio to the w3wp.exe process.  Make sure you check the “Show processes for all users” and “Show processes in all sessions” boxes, and debugging set to True in your web.config.

 

If you have a syntax or compilation error you will get a message telling you where it is and you can fix it right away – no need to go back to the quickform and figure out in which snippet the error is:

 

 

 

8    Bringing it Back to the Project

 

Even though it is so much fun to work in Visual Studio eventually you need to bring it back to your SalesLogix project in App Architect, in order to be able to re-deploy it. 

There are 3 parts to this challenge:

 

  • You need to copy any file that was manually added to the web site to your project in SalesLogix – this will be a manual, one-time process, unless you happened to put all these files under a specific folder, in which case you could automate it with RoboCopy as well
  • You need to manually adjust the smart part mapping in your portal configuration to point to the custom smart part (also a one-time process)
  • You need to copy any modified file to the SalesLogix project – this part can be automated with RoboCopy, as explained below

 

Be careful – do not deploy before updating your files in SalesLogix, otherwise your changes will be overwritten!  Not that it ever happened to me, of course.  Ahemm. 

 

The first part is pretty easy if you have been keeping track.  Just copy the files using the Windows File Explorer.  Note that App Architect will usually crash when you do that – just close it for now.   In my case that would be SmartParts\Contacts\ContactDetails.ascx, SmartParts\Contacts\ContactDetails.ascx.cs, and App_Code\TypedWebEntityBindingGenerator.cs.

 

The second part is also standard stuff, you just need to open App Architect, go to the correct page under the portal, remove the existing (quickform) smart part if present, then add your custom one.  If you copied the file correctly in the previous step it should be shown, as in the figure below:
 

 

For the third part, you can really use anything you want to copy the files, but you need to be careful NOT to copy any file that is NOT already in the project.  In my opinion this is really the only tricky part in the whole set up so let me expand a bit.  If you were to just xcopy the entire SlxClient folder back to your SupportFiles folder under your project, the next time you do a deploy from App Architect, it will take all these files, and move them to the deployment target folder.  This all sounds great, until you realize that in so doing, it will overwrite any file that was just generated by App Architect.  For example, if you now make a change to the AccountDetails quickform, and try to re-deploy, App Architect will copy the previous version of that generated quickform, which you saved to SupportFiles.  Confusing?  A little bit.  But it makes sense when you think about it.


Therefore I use a tool (made by Microsoft) called RoboCopy.  I think this may be standard on recent version of Windows, but for Windows 2003 it is part of the resource kit.  Just Google “download robocopy” and download it.  Then create a .bat file under your project folder in SalesLogix (for example at E:\Projects\MyClient\SlxWeb\ImportCustomWebFiles.bat) and use the following code in it (adjusting paths as needed):

 

The “/xl” means you will be copying only files that are present on both sides.  The “/xo” means you will be copying only files that are more recent than the version under SupportFiles (if your timestamps are a bit wacky you may have to remove that one the first time).  The “/s” means to do a recursive copy.  You can add “/L” the first time which will do a fake copy, just to make sure.  Try it out, and don't forget to manually copy the files that have been added to the web site (the first time).  You can then run this bat file every time you make a change in Visual Studio and want to save it to the SalesLogix project.  Build, redeploy, and make sure your stuff is still there.  You may want to take a backup of your web folder the first time!


9    And back to the database VFS...


If you prefer to keep your project in the database, you can bring it back once you are all done with the “Import” option of the Project Workspace Manager.  It is very straightforward though it does take a little while to run.


Alternatively, you can create a bundle and apply it to your database project – this is a good way to make sure your bundle is complete.

 

10    A few final words

 

“When should I use a custom form instead of a quick form” is a recurring question on the SalesLogix forums.  There is no set answer for this though – I suspect it is going to depend mostly on how familiar you are with HTML and ASP.NET.  In the end much as you may not want to hear it the answer is probably going to be for you to try it out and decide for yourself whether it saves you time and makes the solution more maintainable.  Even so, this is just another tool in your toolbox – that doesn't make it right for every problem!  Keep in mind the few pros and cons presented in the first paragraph.  And if you can keep the logic separated as far as possible using business rules instead of including it into your ASP.NET code-behind you will have a much easier time switching back and forth.


There is also a form of hybrid approach I did not cover: starting with a quick form and converting it to a custom form later on.  My feeling is that it will yield hard to maintain code but I invite you to try it out and decide whether it works for you.  Once again, it is all about choice.

 

Comments
by Silver Contributor ngaller
on ‎12-15-2009 03:29 PM

I hope you enjoy this post, if you have the courage to read it in its entirety!  Feel free to drop me a line if you have any question or issue with the sample code.

 

Thanks
by Bronze Elite Contributor
on ‎12-16-2009 05:17 AM

Thanks Nick,

 

I was toying with the idea of going down this road. You've succesfully convinced me that we're in big trouble if we have to do anything fancy for our clients -- unless we're all web developers. Which, of course, we're not.

by
on ‎12-16-2009 05:43 AM

Excellent Article Nick. Sometimes I like to start with a standard smart part for templating the UI and then go through a refactor process and clean up. I really like your binding solution and might put it into my day to day tool box. I also use a set of custom libraries for the setup of toolbars and other ancillary functionality to ensure that I can spend more time on the business domain and not on all of the build up code.

 

 

 

by Bronze Elite Contributor
on ‎12-17-2009 09:53 AM
Maybe someone could publish a public repository of these wonderful things! Smiley Wink
by Silver Contributor ngaller
on ‎12-21-2009 09:18 AM

Mike, you are 100% right, of course.  It's a problem because you can hardly expect all devs to be master of HTML and Javascript and SQL and know the SalesLogix schema inside and out.  I wonder if an option would be to concentrate the effort of SalesLogix devs on the business logic (and throw together a proof of concept either in Visual Studio - you could even use windows forms for this - or as a quickform) then have a dedicated web developer on the team polish it off in ASP.NET (without concerning himself with any of the logic)?

by Astute Commentator ZSantiaga
on ‎05-29-2011 06:20 PM

Nick, 

I am working through your excellent article to learn how to create custom SLX Web Client pages.

 

Will you please explain the boiler plate code line:

     var container = ContactDetails_RTools;

 

Where does the ContactDetails_RTools value come from and how would I know what to set the container value to if I were creating a Ticket form?

 

Many thanks!

by JasonHuber
‎09-25-2011 03:55 PM - edited ‎09-25-2011 03:55 PM

The ContactDetails_RTools is what Nick (and it in the default product) called his tools container. It is in section 3.

 

It holds the groupnavigator and the save buttons etc.

 

I agree. Excellent tutorial.

Register Read Guidelines Request Partner or Employee Access

What's New in 8.1

Labels