SDK_training

BBCRM SDK – UI Models

If you’re starting out customizing BBCRM, or even if you’ve been doing so for several years, it’s not unusual to run into frustrations that you feel should be solvable, but that you can’t find a ready answer for among the excellent BBCRM customization resources already out there.  If you’re not already aware, the website www.bbdevnetwork.com provides a great technical reference along with a reasonably well-trafficked Q&A site.  Even so, sometimes it’s hard to find the answer you’re looking for.

This blog introduces a series of posts with practical advice and guidance based on real-world customization development and several years of questions from BBCRM SDK trainings I’ve conducted.  Please feel free to contact me if I can clarify or explain any of this–or if you’ve found alternative ways to address the topic.

Adding a New UI Model

To add a UI model to an existing SDK XML spec, use the following steps as a guideline:

  1. First make sure the XML spec you are creating a UI model for has been loaded to the database, as the UI model wizard will read the spec from the database, not your filesystem.
  2. Add a new item to your UI model project, use the “UI Model Wizard” template in Visual Studio (note the “Name” field doesn’t matter as it will be ignored by the wizard):
  3. In the “Spec file” field, navigate to the XML spec you wish to create a UI model for (this will auto-fill several additional fields in the wizard window):
    1. If you’re using C# templates, you may want to use the “Namespace (optional)” field to set the namespace for the generated .cs files. For example, if your .cs files are going to be generated in the folder “SDKTraining.UIModel\MyUIModel”, you may want to set your namespace to “SDKTraining.UIModel.MyUIModel” since, by default, C# will use the folder’s name as part of the namespace.  If you do this, note that the initially-generated namespace on the .cs files and in your XML spec’s <UIModel> “AssemblyName” and “ClassName” attributes will initially be incorrect.  However, if you manually correct it, in the future the “Refresh UI Model” functionality should work correctly.
  4. Most fields can be left as default values. Be sure to check the “Generate Html file for the model” if you wish to alter the default form HTML (typically you’ll want to).
  5. Click “OK” if everything looks correct. Typically you won’t need to modify default values, other than checking the “Generate Html file for the model” box.
    1. If prompted with a dialog about “Inconsistent Line Endings”, click “Yes”:
  6. After the UI model is created, note new content has been added to the XML spec you’re creating a UI model for:
  7. Take the following steps on the modified XML spec:
    1. Correct the “<ExternalResource>” tag to reflect the folder you’re using to hold your HTML files. For example:
    2. Make sure to save the modified spec and run “Load Spec” after fixing the XML spec.
    3. Double-check that the generated HTML file is in the correct folder, if it isn’t, move it to the correct folder in “Solution Explorer”:
  1. Build the UI model project. If you don’t already have post-build events configured to automatically copy DLL and HTML files to appropriate folders, make sure you manually take the following steps:
    1. Copy the UI model DLL file to your application’s “vroot\bin\custom” folder:
    2. Copy the HTML files to your application’s “vroot\browser\htmlforms\custom” folder:

Refreshing an Existing UI Model

After a UI model has been created, special steps must be taken to update the UI model if the XML spec’s fields change at all.

  • Make sure the modified XML spec has been loaded to the CRM via Load Spec.
  • Open the XML spec, from the “Tools” menu run “Refresh UI Model” (make sure your cursor is within the window for the XML file, as the “Refresh UI Model” tool appears to use the window with focus when determining which UI model to refresh):
  • This will refresh the *.CodeGen.* files, which you can see by selecting “Show All Files” for the UI model project in “Solution Explorer”:
  • This will NOT refresh the HTML file*, so any modifications to the fields will need to be manually added to the HTML file.    (* Occasionally you are prompted whether to refresh the HTML file or not.  I haven’t figured out what triggers this prompt, but if you are prompted, respond with “Yes/No” accordingly).

HTML Component Caching

  • Similar to the CRM application caching that will cache spec XML metadata on the server, the browser will aggressively cache HTML components associated with UI models on the client side. To work around this, you can disable caching in your browser while the browser is in “Dev” mode.
    • For Chrome, open developer mode with F12 and open the settings, and check “Disable cache (while DevTools is open)”, this will disable the cache as long as you’re running developer tools:
    • For Firefox, there is a similar setting in the F12 developer tools mode:

Using Javascript (including jQuery) in UI Model HTML

You can reference Javascript with your UI model HTML files.  The Blackbaud-provided instructions are on this page: https://www.blackbaud.com/files/support/guides/infinitydevguide/Subsystems/webshell-javascript/Content/WebShell/coWebshellWritingJSforUIModelDataForm2.htm

Placing Data Form Extension Fields on Existing Forms

If you create a data form extension for an existing data form, generally you are limited to placing any custom fields either “AfterParent” or on a new tab (see Creating a Data Form Extension).  Note the below guidance is an approach that is more likely to break due to patch/upgrade than using the built-in custom field placement.  If you use this approach, make sure to include it as a checklist item to review after applying patches/upgrades.  To place a form field in a location within the existing HTML:

  • Create a data form extension for the existing data form.
  • Add a UI model to your add form.
  • In your HTML for the UI model, reference a javascript file, e.g:
  • In your javascript file, create a immediately invoked function expression that finds the right spot in the add form and inserts arbitrary HTML:
  • Using selectors (see above screen-cap), you can find the location within the existing HTML where you wish to make modifications.

Share this post