Customizing Controls in Brazos UI the Right Way

Follow

Overview

Though we believe that Brazos UI is robust enough to meet the overwhelming majority of use cases, you may find yourself in a situation where the available controls in Brazos UI don't seem to fit your needs. There are a number of escalating steps to take when you run into this situation to ensure the best outcomes, ranging from us assisting with your design and needs all the way up to you personally doing the development work to extend a control. In any of the available options, BP3 is here to help to make sure you get the best outcomes.

Let's Work Together

Regardless of how you anticipate the development path will proceed for a new or modified control, your first course of action should always be to open a help ticket. Submitting a help ticket is important for both you and us in a number of ways. While we are constantly improving Brazos UI, one of the ways we prioritize modifications and additions to the toolkit is by knowing what our customers need. By submitting a help ticket, you let us know what functionalities and controls are important to you and your business. The more information we have, the better Brazos UI gets!

Submitting a Better Help Ticket

When contacting us with a control request, it's best to give us two important bits of information:

Explain your use case.

Do this first! It's tempting to leap ahead and describe what you want for a new or modified control. However, by focusing on a potential solution rather than the goal we may end up solving the wrong problem. There is also a handy side effect that in the act of articulating the bigger picture and goal of the project you yourself may begin to see other options! We want to make sure that any new or modified control addresses the problem that precipitated its creation in the first place. More importantly though, our team is very good at identifying ways to utilize existing Brazos UI controls with BPM's features to achieve the outcome you need.

Explain your desired solution.

Once you've explained your larger goal, then you should describe your envisioned solution. While we pride ourselves on our expertise and problem solving skills, you do know your specific users and their needs better than us.

With a help ticket in play, we can then determine the best course of action.

Evolving Brazos UI

The ideal outcome would be to design a solution that utilizes the existing Brazos UI controls. The results are essentially immediate; no time needs to be spent on control development by us or you so implementation of the solution is much faster. Don't forget too that CSS styling of Brazos UI components is always available and doesn't change any of the underlying code. Maintaining a support contract with BP3 is a great way to get fast help with this!

When meeting your goals doesn't appear to be possible through that avenue, an existing control may need modification or an entirely new control may need to be developed. When modifications or new controls are determined to be the next course of action, we will file a feature request with the dev team. There are several outcomes from a feature request: development is scheduled, the feature request is considered reasonable but implementation is delayed (perhaps indefinitely), or the request is deemed out of scope. The first option is clearly best, but we are here to help with managing the others as well.

We Do the Development

BP3 developing the control is the best option for several reasons:

  • BP3 does the work. You save effort by not having to develop and test the control yourself. Our team is also very good at what they do. Familiarity with the tools and frameworks used in Brazos UI improves the quality and efficiency in generating or modifying a control.
  • A control that is officially incorporated into Brazos UI is now also supported by BP3. Besides assistance through help tickets, the control is now part of the development cycle. This means the control will receive review and improvements as part of the regular releases. You are relieved of the burden of spending the time and effort to maintain the control over time.
  • BP3-developed controls will integrate seamlessly with our existing components. Look and feel are important visual components, but the BPM developers will also get to use familiar configuration options without you needing to mimic the Brazos UI styles.

BP3 development of a modified or new Brazos UI control is “paid” for in one of three ways:

  1. Time. A change that is easily implemented and with broad interest is likely to be taken up by the dev team quickly. More complicated changes that are of limited use and have not been previously requested may be placed in the queue but with a low priority. If you have the time, this is may be the cheapest of options, but you should always look at the larger picture and weigh the impact of waiting on your users and business. Note that if we see many different users needing a similar solution, then it will receive higher priority for implementation. This is why you are asked to submit your requests as help tickets. A feature request that was delayed or on hold will be revisited with each request that comes in (we consider requests by organization, not user so don't just have everyone on your team submit the same help ticket!).
  2. Support Contracts. Brazos support comes in three levels: silver, gold, and platinum. One facet of the support tiers is with feature requests; the platinum support level receives the highest priority when it comes to feature requests. This is just one of the perks of an improved support contract.
  3. Custom Work Contract. We don't typically want or need to resort to a-la-carte development contracting, but this may be an option for a control that is of high priority for you but also narrowly focused in its use. In these cases it may not make sense to include the control in the wider Brazos UI toolkit and so developing a custom deliverable may be the preferred approach.

You Do the Development – with BP3's Guidance

As a last resort when time is not on your side or the request is deemed out of scope, you may find yourself in a situation where you need to modify or develop a control yourself. We'd recommend a work contract instead of developing it yourself, but doing the work yourself with an ongoing support contract is still of value even at this point. While supplementing or extending Brazos UI is not a “supported feature,” we can still assist to help you succeed. There are, however, some dos and don'ts when diving into control creation and modification.

New Controls

The best approach to integrate a brand new control that will play nicely alongside Brazos UI is to create a new coach view.

  • Create Bootstrap-style controls using the included libraries - The main components you should need for this are Bootstrap and jQuery. You can find the specific versions utilized by Brazos UI in the “Brazos UI Third Party Software Licenses and Notices.txt” file. This is included as a Managed File contained in the Brazos UI Toolkit. It is important to develop your control using the same versions and to avoid including these components again.
  • Other JavaScript libraries that may be of interest are referenced in the license and notices file.
    • Note: UsingJavaScript libraries not already part of the Brazos UI toolkit may or may not present conflicts and adversely affect the larger suite of Brazos UI controls. It is acceptable for you to try them, but we will not be able to offer assistance in troubleshooting them.
  • Place it within your Process App or into a Toolkit. The choice between the two depends on how widely this control will be used. Note you don't need to have an explicit dependency on Brazos UI for the control to work; your control should be fully functional in any coaches containing the Brazos UI Template.

Extending Controls

The recommended way to extend existing controls is to wrap the selected control in a new coach view.

  1. Create a new coach view and drag the control to be modified into it.
  2. Map the original control's bindings and configuration options to the new control. This allows all the original functionality to still be used. Make sure you include the visibility and other metadata configurations.
  3. Customize the control actions using the event handlers in the new coach view.
  4. (Optional) Include non-standard JavaScript libraries with the specific control or with an extended version of the Brazos UI Template.

Extending a control via a coach view wrapper has the advantages of automatically incorporating bug fixes and feature upgrades when new versions of the Brazos UI Toolkit are released. Therefore you only need to maintain the features of the enhancement (and perhaps, rarely, mapping new configuration options). The one drawback is that the extra coach view layer decreases performance slightly, but this should not even be noticeable on small coaches.

Don'ts

The don'ts are mostly summarized by: Don't directly modify the Brazos UI Toolkit. This isn't BP3 being overprotective of our product, we're looking out for your best interests when it comes to ongoing maintenance. Specifically:

  • You should not extend controls by changing them directly. Neither should you add new controls into the Brazos UI Toolkit. If you modify a component of the Brazos UI Toolkit directly, you will loose those modifications upon version upgrade. You then have the burden of having to transfer those changes into the new version.
  • It is also not ideal to copy a control and then modify it. It may seem innocuous to copy a component and then extend it, but when you do that you miss out on easy incorporation of bug fixes and features. So either your control falls behind because you make no changes or you have to manually rework it with every release. That being said, it is possible this may be the only option when extending functionality with a coach view wrapper doesn't work.

Control Extension Example

Let’s consider the following example: we need to add functionality that highlights an Input Integer when the bound value goes over a threshold.

Create your wrapper coach view called “Input Integer with Soft Validation”:

In the newly created coach view, drag the control that you want to extend:

In order to make sure we don’t lose any of the old Input Integer functionality in this new coach view, we need to expose all of the configuration options in the wrapper. Starting with the General Attributes, map the label, help text, visibility, and label visibility of the Input Integer to the applicable attributes in the wrapper coach view (located in Configuration Options -> General Options):

 

Next, we need create a binding variable and map it to the binding of the binding of the Input Integer:

 

Finally, we need to map each of the configuration options. Click on the “Configuration” tab of the Input Integer and for each option, click the blue circle to trigger a Javascript binding and click the yellow arrows to the right of the configuration option. This will create a configuration option in your wrapper coach view that matches the Input Integer config option and map the values to each other. Do this for all the configuration options:

Now we have our wrapper coach view set up and we’re ready to make our customizations. We know that we’ll need an additional configuration option for a threshold value. Any value over our threshold value will cause the input field to be highlighted. I’ve called this option “threshold” and made it an Integer:

Next, we need to write the behavior that will actually make the field highlight when we need it to. In the change event of the behavior tab, add the following code:

if (event && event.property == this.context.binding.property) {
  var shouldWarn = event.newVal > this.context.options.threshold.get("value");
  var $controlGroup = $(".control-group", this.context.element);
  $controlGroup.toggleClass("warning", shouldWarn);
}

This code is fairly straightforward. It adds a warning class which highlights the control group if the new value of our binding is greater than our threshold value.

We can now test the new control by dropping it onto a blank Brazos Template, picking a binding and a threshold value, and running it.

 

And there we have it - a wrapped Brazos control with only a few lines of code to add a fairly robust feature.

Have more questions? Submit a request

Comments

Powered by Zendesk