10 Customizing the Billing Care Account Home Page

Learn how to use the Oracle Communications Billing Care SDK to customize the Billing Care account home page.

Topics in this document:

• Customizing the Billing Care Account Home Page

• About Customizing the Billing Care Home Tab

• About Customizing the Bills Graph

Customizing the Billing Care Account Home Page

You can customize the Billing Care account home page in the following ways:

• Add links to the Billing Care Home tab for switching between a summary and detailed view of a customer's account balance. See "About Customizing the Billing Care Home Tab".

• Customize the data displayed in the Bills graph. See "About Customizing the Bills Graph".

About Customizing the Billing Care Home Tab

The Billing Care Home tab provides a high-level overview of an account's assets, account history, current balances, and News Feed of account and status change activity. The Bill Unit section of the Home tab displays detailed information about the amount due for a bill, such as the amount past due, the unallocated payments, the unallocated accounts receivable, the amount owed for this billing cycle, and the total due.

You can customize the Billing Care Home tab to display:

• Summary account balance information in its Bill Unit section

• Detailed account balance information in its Bill Unit section

• Links for switching between the summary and detailed views on the Home tab

For example, Figure 10-1 shows a Home tab with links for switching between summary and detailed views of a bill unit.

Figure 10-1 Home Tab with Sample Summary and Detailed Links

Description of "Figure 10-1 Home Tab with Sample Summary and Detailed Links"

Adding the ability to switch between the summary view and the detailed view requires you to create the resources used by the Bill Unit section. For example, you need to create multiple views, a view model, and a custom CSS file for displaying a bill unit's account balance information correctly. See "Customizing Billing Care" for more information about customizing Billing Care resources

The Billing Care SDK includes sample Home tab customizations, including a README.txt file explaining the samples, in the SDK_home/samples/HomeTabCustomization directory, where SDK_home is the directory in which you installed the Billing Care SDK. Use these samples when developing your own customizations.

Customizing the Billing Care Home Tab

To customize the Billing Care Home tab to display summary and detailed bill unit information:

1. Create a view that contains links to the summary and detailed views. See "Creating a Summary and Detailed Link View".

2. Create a view for displaying summary information for all bill units in an account. See "Creating an All Bill Units Summary View".

3. Create a view for displaying summary information for a single bill unit. See "Creating a Bill Unit Summary View".

4. Create a custom view model for the Billing Care Home tab. See "Creating a HomeTabBillUnitsViewModel".

5. Override the registry values for the Billing Care Home tab. See "Configuring the Custom Home Tab in the Registry".

6. Modify the appearance of the Billing Care Home tab. See "Overriding the Billing Care Home Tab Theme".

Creating a Summary and Detailed Link View

Create a view that displays the links to your summary bill unit view and detailed bill unit view. These links should appear at the top of the Billing Care Home tab. See "About Views" for more information about views.

To create a view that displays the Summary and Detailed links:

1. Create a switchLinkView.html file in the myproject/projectname/web/custom/templates/ directory.

2. Add criteria to the view for displaying a Summary link and a Detailed link. For example:

   <div id="switchViewHeader" class="bu-switch-view-section">
      <div id="switchLinks" style="display:flex; justify-content:space-around">
         <a href="javascript:void(0);" id="summary_link" class="sidebar-news-feed-link" data-bind="click: $root.viewSwitched">Summary</a>  
         <a href="javascript:void(0);" id="detailed_link" class="sidebar-news-feed-link" data-bind="click: $root.viewSwitched">Detailed</a>
      </div>
   </div>

3. Save the file in your NetBeans IDE project.

Creating an All Bill Units Summary View

Billing Care uses an HTML view file to render the Bill Unit section of the Home tab. When an account contains multiple bill units, the Bill Unit section displays a panel that details the amount due for all bill units. You can create a custom view that displays summary information for all bill units, such as the total account balance for all bill units.

A sample allBillUnitSummaryView.html file is provided in the SDK_home/samples/HomeTabCustomization/web/custom/templates directory. Use this sample to create a view for displaying summary information for all bill units in an account.

To create a view for displaying summary balance information for all bill units in an account:

1. Create an allBillUnitSummaryView.html file in the myproject/web/custom/js/viewmodels/templates/area/ directory, where area is the customization type.

2. Define the fields to display in the summary view for all bill units in an account.

   For example, this shows how to add a Total Account Balance field that displays the total account balance for all bill units.

   Note:

   In this example, the Total Account Balance field is the custom field. The other code is mandatory for the Billing Care SDK to work and should not be changed.

   <div class="css_table streatch_width marginTop10px"> 
      <div class="css_table marginBottom10px">    
         <div class="css_row"> 
            <h3 class="css_cell text_left_align tab_heading marginBottom6px" 
               role="heading" id="homeTab_AllBillUnitsWithCnt" 
               data-bind = "text : '<%= homeTab.ALL_BILL_UNITS %> (' + numBillingUnits() + ')' " >
            </h3>      
         </div>
      </div>
   
      <!-- Custom field : START -->  
      <div class="tab-area-table-section-3-left tab-area-table-section-3-left-no-margin marginTop10px marginBottom10px">   
         <div class="tab-area-table-left fontBold">Total Account Balance   
         </div>   
         <div class="tab-area-table-right-note">   
         </div>                                     
         <div class="tab-area-table-right redColor numberFormat" 
            id="totalAccountBalance" data-bind="text : totalAccountBalance">
         </div>  
      </div>
      <!-- Custom field : END --> 
    
      <div id="bu_footer_all" class="css_row streatch_width tab-area-section-more tab-area-section-more-2" data-bind="visible : showAllBUFooter ">   
         <a role="button" id="makePymt" title="<%= homeTab.MAKE_PAYMENT_TITLE %>" 
            tabindex="0" class="cmd-button"    
            data-bind="click : openMakePaymentsDlg ,event: {keypress : openMakePaymentsDlgOnKeypress},authorize_command:{make:'hide', resource:PAYMENT_RESOURCE, action:MAKE_ACTION}">    
            <%= homeTab.MAKE_PAYMENT %>   
         </a>     
      </div> 
   </div>

3. Save the file in your NetBeans IDE project.

Creating a Bill Unit Summary View

Billing Care uses an HTML view file to render the Bill Unit section of the Home tab. When an account contains a single bill unit, the Bill Unit section displays a detailed view of the amount due for the bill unit. You can create a custom view for the Bill Unit section that displays summary information for a bill unit, as shown in Figure 10-2.

Figure 10-2 Bill Unit Summary Information

Description of "Figure 10-2 Bill Unit Summary Information"

A sample BillUnitSummaryView.html file is provided in the SDK_home/samples/HomeTabCustomization/web/custom/templates directory. Use this sample to create a view for displaying summary information for a bill unit.

To create a view for displaying summary balance information for a bill unit:

1. Create a BillUnitSummaryView.html file in the myproject/web/custom/js/viewmodels/templates/area/ directory, where area is the customization type.

2. Add criteria to the view for displaying summary account balance information, such as the amount due and total due.

3. Save the file in your NetBeans IDE project.

Overriding the Billing Care Home Tab Theme

You must override the appearance of the Billing Care Home tab to make room for the new Detailed and Summary links you created in "Creating a Summary and Detailed Link View". See "Customizing Billing Care Themes and Logo" for more information about CSS files.

A sample override CSS file named override.css is provided in the SDK_home/samples/Themes/css directory, where SDK_home is the directory in which you installed the SDK. Use this sample to create a custom CSS file.

To override the theme used by the Billing Care Home tab:

1. Create an override.css file in the myproject/web/css directory, where myproject is the NetBeans IDE project directory containing your Billing Care customizations.

2. Add entries to the CSS file for overriding styles in the Billing Care Home tab.

   .bu-switch-view-section {
      border-bottom: 1px solid #CCC4C4;
      padding: 10px 0 10px 0;
      width: 100%;
   }

3. In the customRegistry.js file, add an entry under cssFiles for your override CSS file in the others parameter. For example:

   var CustomRegistry= {
      cssFiles: {
         themeCss: 'css/theme_default.css',           
         others: ['css/override.css']
      };

Configuring the Custom Home Tab in the Registry

After creating the required views and custom view model, create a custom module entry in the customRegistry.js file to use when opening the Billing Care Home tab. Billing Care uses the custom views and view model instead of the default entries when rendering the Home tab.

A sample customRegistry.js file is provided in the SDK_home/samples/HomeTabCustomization/web/custom directory, where SDK_home is the Billing Care SDK installation directory. Use this sample to create the customRegistry.js file with your custom views.

To add an entry in the customRegistry.js file:

1. Create a customRegistry.js file in myproject/web/custom by copying the reference registry file.

2. Define the custom views and view models in the file. For example:

   var CustomRegistry = {
      homeTabBillUnits: {
         viewmodel: 'custom/viewmodels/CustomHomeTabBillUnitsViewModel.js'
      },
      summaryViews: {
         switchView: 'text!../custom/templates/switchLinkView.html',
         allBUSummaryView: 'text!../custom/templates/allBillUnitSummaryView.html',
         individualBUSummaryView: 'text!../custom/templates/billUnitSummaryView.html',
      },
   };

3. Save the file in your NetBeans IDE project.

Creating a HomeTabBillUnitsViewModel

Billing Care uses the HomeTabBillUnitsViewModel.js file to define what fields to display in the Billing Care Home tab. The fields defined in the view model are bound in the HTML file used to render the custom view or page. See "About View Models" for more information about Billing Care view models.

A sample CustomHomeTabBillUnitsViewModel.js file is provided in the SDK_home/samples/HomeTabCustomization/web/custom/viewmodels directory. Use this sample create a custom view model.

To create a custom view model for the Billing Care Home tab:

1. Create a CustomHomeTabBillUnitsViewModel.js file in the myproject/web/custom/js/viewmodels/customHomeTab directory, where myproject is the folder containing your NetBeans IDE project.

2. Define the custom fields in this file, as required.

3. Save the file in your NetBeans IDE project.

About Customizing the Bills Graph

The Bills graph provides a visual overview of account activity, including billing and customer interactions. The horizontal axis shows information about the last 12 bills and the bill in progress. The vertical axis shows account information regarding customer communication and A/R.

You can customize the information displayed in the Bills graph based on your requirements.

Customizing Bills Graph

To customize the Bills graph:

1. Create a custom view model to define the override for the default Home tab. See "Creating Custom Home Tab View Model".

2. Create a custom view model to define the override for the Bills graph based on your requirements. For example, create a file named CenterViewModel.js in the myproject/web/custom/viewmodels directory, where myproject is the folder containing your NetBeans IDE project. See "About View Models" for more information on creating view models.

3. Create a custom view model HTML template for overriding the Bills graph. See "Creating Custom View Model HTML Template for Customizing Bills Graph".

4. Create a customRegistry.js file configuring Billing Care to use your custom view models. See "Configuring Custom View Models for Customizing Bills Graph in the Registry".

5. Package and deploy your customization to your Billing Care domain using one of the methods described in "Using an Exploded Archive during Customization" or "Packaging and Deploying Customizations".

Creating Custom Home Tab View Model

Billing Care uses HomeTabBillUnitsViewModel to determine how to the display the Home tab. To change the Home tab, create a custom view model, such as CustomHomeTabBillUnitsViewModel, that contains overrides for the default display.

To create a custom Home tab view model:

1. Create the CustomHomeTabBillUnitsViewModel.js file in the myproject/web/custom/viewmodels/homeTab directory.

2. Open the CustomHomeTabBillUnitsViewModel.js file using a text editor and add the following code:

   define([ 
       'jquery', 
       'underscore', 
       'knockout', 
       'knockout-mapping', 
       Registry.base.viewmodel, 
       'viewmodels/hometab/HomeTabBillUnitsViewModel' 
   ], 
       function ($, _, ko, komapping, BaseViewModel, HomeTabBillUnitsViewModel) 
   { 
         function CustomHomeTabBillUnitsViewModel() { 
          HomeTabBillUnitsViewModel.apply(this, arguments); 
          var self = this; 
          
          /* This function overrides OOTB renderGraph function to replace the 
   Bills graph and balances 
           * section from the desired custom view. 
           */ 
          self.renderGraph = function () { 
              
              /* This is the function which renders the custom View model ( 
   referred to CenterSectionViewModel in the CustomRegistry) 
               * replacing the bills graph section. 
              */ 
              self.renderCenterSection(); 
              
              /* This is the function which renders the custom View ( referred 
   to customView in the CustomRegistry balances entry) 
               * replacing the OOTB balances section. 
              */ 
              self.renderBalances(); 
    
          }; 
          
          self.renderCenterSection = function(){ 
            // The centerSection is the CustomRegistry entry which refers to the 
   Custom section replacing OOTB Bills Graph Section. 
              require([CustomRegistry.centerSection.viewmodel, 
   CustomRegistry.centerSection.view], 
                function (CurrentViewModel, page) { 
                    var template = _.template(page); 
                    // HTML id where the Bills and Graph is attached to DOM is 
   "chartContent" 
                    // The custom view needs to be attached to same place for 
   replacing OOTb Bills Graph section 
                    var mainDiv = document.getElementById("chartContent"); 
                    $(mainDiv).empty(); 
                    var viewElem = $(mainDiv).get(0); 
                    ko.cleanNode(viewElem); 
                    $(mainDiv).append(template); 
                    var currentVM = new CurrentViewModel(); 
                    // This initialize method will contain basic steps to render 
   the CustomViewModel 
                    currentVM.initialize();                                     
                    ko.applyBindings(currentVM, viewElem); 
                });                     
          }; 
         } 
         CustomHomeTabBillUnitsViewModel.prototype = new 
   HomeTabBillUnitsViewModel(); 
         return CustomHomeTabBillUnitsViewModel; 
       } 
   );

3. Save the file in your NetBeans IDE project.

Creating Custom View Model HTML Template for Customizing Bills Graph

Billing Care uses an HTML view file to customize the Bills graph in the Home tab. The template file contains the override for the Bills graph as defined in the custom view model.

To create a custom view model HTML template for customizing the Bills graph:

1. Create the centerView.html file in the myproject/web/custom/templates directory.

2. Define the override for the center section of the Home tab by using the centerView.html file.

3. Save the file in your NetBeans IDE project.

Configuring Custom View Models for Customizing Bills Graph in the Registry

Create custom entries in your customRegistry.js file. Billing Care uses the custom view models instead of the default entries and renders the custom Bills graph in the Home tab.

To configure the custom view model entries to customize the Bills Graph section in the registry:

1. Create a customRegistry.js file in myproject/web/custom/ directory.

2. Define the custom view models in this file:

   var CustomRegistry = { 
     homeTabBillUnits: { 
      viewmodel: 'custom/viewmodels/homeTab/CustomHomeTabBillUnitsViewModel.js' // 
   CustomViewModel which will handle replacing of the OOTB Hometab bills graph 
   with custom view 
     }, 
     centerSection : { 
      view: 'text!../custom/templates/centerView.html', // This is the custom 
   view which would replace the OOTB bills graph section 
      viewmodel: 'custom/viewmodels/CenterViewModel.js' // This is the custom 
   view model which handles rendering of custom view replacing the OOTB bills 
   graph section 
     } 
   };

3. Save the file in your NetBeans IDE project.