Overview
This article shows you a few hands-on examples of JavaScript and CSS templates and sample codes that will enable you to apply custom Javascript and CSS to your FogBugz instance. The examples include Case Page, Drop-Down Menus and FogBugz Entities.
Introduction
Once you have read how to configure and enable customizations and how to write customizations, this is the third step in your learning about FogBugz Customizations.
Description
The examples listed below are aimed to provide you a more deep-dive into how FogBugz customizations work, by using some hands-on examples and providing detailed explanations about the whys of the implementations.
Check our Useful Customizations Repository
Before you start creating your own FogBugz customization to implement client-side changes, it is recommended that you take a look at our list of useful and popular customizations first to see if someone has already encountered and addressed the same needs. Even if you do not find what you are looking for, you will be able to find items that may serve as a good starting point.
Case Page
The first and often used customization is the Case Page Customization Template used for the case page. This template has all the structure you need to detect the version of the page you are on, and the active case editing or viewing mode. If you need to work on the drop-down fields (e.g., Project and Area), see the next section for Drop-Down Menus.
Drop-Down Menus
Drop-down menus in the old UI use the FogBugz droplist library. You will notice that on the page, there is a <select> tag with <option> elements like in a standard HTML menu. However, this is hidden, and the library uses them to manage a custom element. If you want to change the value of one, for example on the edit page of a project, ignore the <input type=text> tag and work on the <select> tag:
// for the primary contact field on the edit project page, the id is 'ixPersonOwner'. change the selection:
$('#ixPersonOwner').selectedIndex = -1;
$('#ixPersonOwner').find('option[value=3]').attr('selected','selected');
// tell FogBugz to re-generate the text input based on the modified <select>
// (make sure to use the actual element, not the jQuery array
DropListControl.refresh($('#ixPersonOwner')[0]);
FogBugz Ocelot's case page uses a new droplist library. Like in the old library, there is a text-type <input> tag. However, there is no <select> element, and the value is stored in a hidden input. Work on the <div>, which has its ID set to the internal name of the case field you want to use, e.g., the project ID, ixProject. When you select the field with jQuery, the droplist object to be used in your code is accessible by calling the .droplist() on that jQuery object. The whole progression should look like this:
var theField = $('#ixProject');
// get the actual droplist object:
var theDropList = theField.droplist();
// get the currently selected value:
var selectedIxValue = theDropList.val();
// if you want to apply styles and classes to the field, you don't need to use
// jQuery to go find it. it's right on the field:
var theInputTag = theField.input;
// we have the 'ix' value of the field above. Use the droplist library to get
// the display name for it:
var selectedText = theDropList.getChoiceFromValue(selectedIxValue).text;
// enable or disable the drop-down:
theDropList.enable(); theDropList.disable();
// change the value:
// if you know the 'ix' value you want change to, set it with .val(ix):
// var ixProject = 15;
theDropList.val(ixProject);
// the available choices for the droplist are in config.choices:
console.table(theDropList.config.choices);
// loop the choices, e.g. if you want to find the ix for a given text
for (i=0; i<theDropList.config.choices.length; i++) {
var choice = theDropList.config.choices[i];
console.log("ix: " + choice.value + ", text: '" + foo.text + "'");
}
In the old library, you could hook the changes into a droplist using the onchange event:
$('#ixPersonOwner').change(function() { console.log("primary contact drop-down changed"); });
Like most of the new Ocelot UI, the droplist library uses events fired on the <body>:
function handleChange(event) {
var theField = event.target;
var theDropList = theField.droplist();
console.log('droplist with id ' + theField.id + ' changed to ix ' + theDropList.val() +
' / text "' + theDropList.getChoiceFromValue(theDropList.val()).text + '"');
}
$('body').on("droplistUserInput", function(event) {
handleChange(event);
});
FogBugz Entities
FogBugz has many entities that you are familiar with from working with cases: Bugs (cases), Projects, Areas, Categories, etc. Internally, these all have a set of properties that follow naming conventions. For example, each entity has a numeric ID: ix, followed by the entity name. The display name starts with s, which is followed by the entity name.
Example : Project has ixProject as its ID and sProject as its name, and Category has ixCategoryand sCategory.
Cases opened via email in your FogBugz account probably have their category set as ixCategory = 3 and sCategory = “Inquiry”. Information about all of the entities is available in JavaScriptLand in the fb.db object. Here is a sample function to demonstrate working with the lists, where we look up an ixProject from a sProject:
function getIxProjectFromSProject (sProject) {
var ixProject = -1;
for (i=0; i<fb.db.Project.length; i++) {
var project = fb.db.Project[i];
if (project.sProject == sProject) {
ixProject = project.ixProject;
break;
}
}
return ixProject;
}
Below is a sample script that sets the category of the case being edited/created to “Inquiry” when the “Inbox” is the project. You can modify it using code like getIxProjectFromSProject to look up the ix's by name if you wish. Remember to use the basic pubsub method in “Structure” above so that your $(‘body’).on code runs after the Ocelot case page is fully rendered. You might want to use the larger template script in the Case Page section above.
$(function() {
var ixProjectInbox = 2;
var ixCategoryInquiry = 3;
var checkForProjectInbox = function(event) {
if (event.target.id == "ixProject") {
var dropList = event.droplist;
if (dropList.val() == ixProjectInbox) {
var categoryDroplist = $('#ixCategory').droplist();
categoryDroplist.val(ixCategoryInquiry);
}
}
}
fb.pubsub.subscribe({
'/nav/end': function(event) {
$('body').on("droplistUserInput", function(event) { checkForProjectInbox(event); });
}
});
});
Migrating from Bug Monkey
Before the new Ocelot UI, FogBugz included an optional plugin called Bug Monkey which worked the same way Customizations do now. When you switch to Ocelot, your customizations come along, but they will need changes if they ran on the case page or the list page. Since these two pages have changed in the new UI, you will need to update your customizations to look for the correct DOM elements and use new JS events and APIs.
Note: The DOM, JavaScript events (such as '/nav/end') and JavaScript objects and APIs (like fb.config and fb.api) are not public and stable APIs. Expect them to change without prior notice.