Customization Best Practices

Customers wishing to customize functionality from Agent's baseline feature set are welcome to do so. We are planning on releasing new versions of Agent frequently and you'll want to create your customizations in a way that makes it easy to avoid conflicts when merging new baseline features into your customizations.

Avoid editing existing baseline files

The fewer baseline files you modify, the better merging new baseline code into your customizations will go. Here are some tips.

Do not append customizations to baseline files

• Need to enhance a C# class? Create a new class and reference your new type in the baseline code.
• Need to write new back end unit tests? Create new test classes.
• Same advice goes for Javascript. Create new modules and reference them for baseline code (more on this here).

Add new user interfaces to the Custom bottle

Your new custom server side code, tests, javascript modules, and templates need to go somewhere. We have created a custom project where this new content can be placed. This will keep your custom code separate from baseline code.

When to rake

When adding new content to a bottle project before it is ready to be served you'll need to run a rake task before it will be ready for testing. rake bottle_custom or a full rake will ensure new contents to the custom bottle project are ready to test. Subsequent edits to the content files do not require a rake

Tests are great

It is always a good idea to implement tests for both your front end and backend code. For Dovetail Agent tests are included at 3 levels.

1. Backend tests written using NUnit (unit and integration)
2. Frontend tests written using Mocha
3. Acceptance tests written in C# using Storyteller to automate web browsers.

In general you are welcome to add your own tests wherever you like. We do recommend that you do not edit existing test fixtures files.

For backend tests you can add new fixtures to the custom.testing project.

Adding a field to an existing UI

This usually involves a small customization to the server-side model being presented and an update to the model map responsible for projecting data into the model. On the front-end you'll need to then update the templates responsible for the view to include the new field. Our Case Customization Scenario discusses this scenario.

Adding a new user interface to an existing view

You might want to add a region to an existing user interface. The best way to do this without impacting the baseline code is to encapsulate the new user interface into its own Javascript module. The only edits to baseline code is adding region to the current layout for your module to render into and finally a call to your module's show method giving it the region you created and the data the module needs.

This pattern is in use a lot amongst our baseline code. For a great example take a look at how the show case module case.js integrates with the customer view customer.js on the left rail of the show case page.

LayoutView

First there is a hook created for the customer section in the layout template caseLayoutTpl.hbs and the CaseLayout view in case.js. Take a look at Marionette LayoutViews and Regions for more details about how this works.

Module dependency

The customer view is contained in the customer.js module which case.js takes a dependency on. We use ES6 Modules that are transpiled via Webpack for a module system.

Customizing data coming from the backend

New UI means new backend endpoints

If you are creating a new user interface (UI) you will need to create the backend for getting data to your UI and saving changes. Take a look at the Backend introduction.

Customizing existing endpoints

When customizing an existing user interface (UI) you'll likely need to customize the data being consumed and changed by that UI. You have two choices for getting new data into your custom module.

1. Edit the baseline endpoint's output model to include a property for your custom data. You would also then need to ensure that this property is populated by the back end endpoint. This usually involves editing the output model of the endpoint and the model map used to project data into that output model.

2. Create a new endpoint in your custom bottle where your front end can retrieve extra data. This would mean an extra AJAX request based on the current object's identifier to get the needed data.

Let's take a look at how to integrate the second option with your custom UI.

Putting your custom UI together with your custom endpoints.

To avoid changing backend endpoints and other front end code we are attempting to encapsulate new behavior into our custom Javascript module.

Based on the customer module example above your module would be invoked with only the object identifier.

  myCustomModule.show(self.layout.customModule, kase.id);

The show method of your custom module would do an AJAX request for the data required by that section of the page.

This tactic has the advantage in that it affects less baseline code. You now have to do a bit more work creating a new endpoint to handle the AJAX request.

Date and Time handling

Dates in Agent are all in UTC which means before presenting them to the user or before sending them to the server you'll need to convert dates between the user's timezone to the server. We've provided a lot of help for this in have a whole guide on Date and Time Handling.