SugarCRM SupportDocumentationSugar DeveloperSugar Developer Guide 7.9ArchitectureQuotes

Quotes

Overview

As of Sugar 7.9.0.0, the quotes module has been moved out of Backward Compatibility mode into Sidecar. Customizations to the Quotes interface will need to be rewritten for the new Sidecar framework as an automated migration of these customizations is not possible. This document will outline common customizations and implementation methods.

Quote Identifiers

Administrators can create custom quote identifiers that are more complex than the default auto-incrementing scheme found in an out of box installation. Utilizing this functionality, we can create numbering schemes that match any business needs.

Creating Custom Identifiers

To create a custom identifier, navigate to Admin > Studio > Quotes > Fields. Next, create a TextField type field named to your liking and check the "Calculated Value" checkbox and click "Edit Formula". Once you see the formula builder, you can choose an example below or create your own. Once created, You can add the new field to your Quote module's layouts as desired.

User Field with Pseudo-Random Values

This example creates a quote number in the format of <user last name>-##### that translates to Smith-87837. This identifier starts with the last name of the user creating it, followed by 5 pseudo-random numbers based on the creation time.

concat(related($created_by_link, "last_name"), "-", subStr(toString(timestamp($date_entered)), 5, 5))

Note: when using Sugar Logic, updates to related fields will update any corresponding Sugar Logic fields. The example being that an update to the Created By last name field will update all related records with a field using this formula.

This example creates a quote number in the format of <billing account name>-#### that translates to Start Over Trust-0001. This number starts with the billing account name followed by a 4 digit auto-incrementing number.

concat(related($billing_accounts, "name"), "-", subStr(toString(add($quote_num, 10000)), 1, 4))

Note: when using Sugar Logic, updates to related fields will update any corresponding Sugar Logic fields. The example being that an update to the Billing Account name will update all related records with a field using this formula.

Record Layout

The following sections outline various changes that can be done to modify the record layout.

Grand Totals Header

The Grand Total Header contains the calculated totals for the quote.

GrandTotalsHeader

Modifying Fields in the Grand Totals Header

To modify the Grand Totals Header fields, you can copy ./modules/Quotes/clients/base/views/quote-data-grand-totals-header/quote-data-grand-totals-header.php to ./custom/modules/Quotes/clients/base/views/quote-data-grand-totals-header/quote-data-grand-totals-header.php or you may create a metadata extension in ./custom/Extension/modules/Quotes/clients/base/views/quote-data-grand-totals-header/. Next, modify the $viewdefs['Quotes']['base']['view']['quote-data-grand-totals-header']['panels'][0]['fields'] index to add or remove your preferred fields.

Example

The example below will add the "Quote Number" field (quotes.quote_num) field to the layout and removes the "Total Discount" (quotes.deal_tot) from the layout.

./custom/modules/Quotes/clients/base/views/quote-data-grand-totals-header/quote-data-grand-totals-header.php

<?php

$viewdefs['Quotes']['base']['view']['quote-data-grand-totals-header'] = array(
    ...
    'panels' => array(
        array(
            'name' => 'panel_quote_data_grand_totals_header',
            'label' => 'LBL_QUOTE_DATA_GRAND_TOTALS_HEADER',
            'fields' => array(
                array(
                    'name' => 'quote_num',
                    'label' => 'LBL_LIST_QUOTE_NUM',
                    'css_class' => 'quote-totals-row-item',
                ),
                array(
                    'name' => 'new_sub',
                    'css_class' => 'quote-totals-row-item',
                ),
                array(
                    'name' => 'tax',
                    'label' => 'LBL_TAX_TOTAL',
                    'css_class' => 'quote-totals-row-item',
                ),
                array(
                    'name' => 'shipping',
                    'css_class' => 'quote-totals-row-item',
                ),
                array(
                    'name' => 'total',
                    'label' => 'LBL_LIST_GRAND_TOTAL',
                    'css_class' => 'quote-totals-row-item',
                ),
            ),
        ),
    ),
);

Modifying Buttons in the Grand Totals Header

The Quotes List Header contains row actions to create quoted line items, comments, and groupings. The actions are identified by the plus icon in the top left of the header. Editing the 'actions' will allow you to add or remove buttons. The following section will outline how these items can be modified.

GrandTotalsActionRow

To modify the Row Actions in the Grand Total Header, you can copy ./modules/Quotes/clients/base/views/quote-data-grand-totals-header/quote-data-grand-totals-header.php to ./custom/modules/Quotes/clients/base/views/quote-data-grand-totals-header/quote-data-grand-totals-header.php or you may create a metadata extension in ./custom/Extension/modules/Quotes/clients/base/views/quote-data-grand-totals-header/. Next, modify the $viewdefs['Quotes']['base']['view']['quote-data-grand-totals-header']['buttons'] index to add or remove your preferred row actions.

Example

The example below will create a new view that extends the QuotesQuoteDataGrandTotalsHeader view and append a button to the Grand Total Header button list.

First, create your custom view type that will extend the QuotesQuoteDataGrandTotalsHeader view.

./custom/modules/Quotes/clients/base/views/quote-data-grand-totals-header/quote-data-grand-totals-header.js

({
    extendsFrom: 'QuotesQuoteDataGrandTotalsHeaderView',

    initialize: function(options) {
        this.events = _.extend({}, this.events, options.def.events, {
            'click [name="gth-custom-button"]': 'buttonClicked'
        });

        this._super('initialize', [options]);
    },

    /**
     * Click event
     */
    buttonClicked: function() {
        app.alert.show('success_alert', {
            level: 'success',
            title: 'Grand Total Header Button was clicked!'
        });
    },
})

This code will append a click event to our button named gth-custom-button and trigger the buttonClicked method. Once completed, add your new button array to the grand total header in the $viewdefs['Quotes']['base']['view']['quote-data-grand-totals-header']['buttons'] index.

./custom/modules/Quotes/clients/base/views/quote-data-grand-totals-header/quote-data-grand-totals-header.php

<?php

$viewdefs['Quotes']['base']['view']['quote-data-grand-totals-header'] = array(
    'buttons' => array(
        array(
            'type' => 'quote-data-actiondropdown',
            'name' => 'panel_dropdown',
            'no_default_action' => true,
            'buttons' => array(
                array(
                    'type' => 'button',
                    'icon' => 'fa-plus',
                    'name' => 'create_qli_button',
                    'label' => 'LBL_CREATE_QLI_BUTTON_LABEL',
                    'acl_action' => 'create',
                    'tooltip' => 'LBL_CREATE_QLI_BUTTON_TOOLTIP',
                ),
                array(
                    'type' => 'button',
                    'icon' => 'fa-plus',
                    'name' => 'create_comment_button',
                    'label' => 'LBL_CREATE_COMMENT_BUTTON_LABEL',
                    'acl_action' => 'create',
                    'tooltip' => 'LBL_CREATE_COMMENT_BUTTON_TOOLTIP',
                ),
                array(
                    'type' => 'button',
                    'icon' => 'fa-plus',
                    'name' => 'create_group_button',
                    'label' => 'LBL_CREATE_GROUP_BUTTON_LABEL',
                    'acl_action' => 'create',
                    'tooltip' => 'LBL_CREATE_GROUP_BUTTON_TOOLTIP',
                ),
                array(
                    'type' => 'button',
                    'icon' => 'fa-plus',
                    'name' => 'gth-custom-button',
                    'label' => 'LBL_GTH_CUSTOM_BUTTON',
                    'acl_action' => 'create',
                    'tooltip' => 'LBL_GTH_CUSTOM_BUTTON_TOOLTIP',
                ),
            ),
        ),
    ),
    ...
);

Finally, create labels under Quotes for the label and tooltip indexes. To accomplish this, create a language extension:

./custom/Extension/modules/Quotes/Ext/Language/en_us.custom-button.php

<?php

$mod_strings['LBL_GTH_CUSTOM_BUTTON'] = 'Custom Button';
$mod_strings['LBL_GTH_CUSTOM_BUTTON_TOOLTIP'] = 'Custom Button Tooltip';

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

List Header

The Quotes List Header is a complex view that pulls data from two different locations. The JavaScript controller is located in ./modules/Quotes/clients/base/views/quote-data-list-header/quote-data-list-header.js and pulls the metadata from ./modules/Products/clients/base/views/quote-data-group-list/quote-data-group-list.php. You should note that ProductBundleNotes combines its description field with Product fields in this list.

ListHeader

Modifying Fields in the List Header

To modify the List Header fields, you can copy ./modules/Products/clients/base/views/quote-data-group-list/quote-data-group-list.php to ./custom/modules/Products/clients/base/views/quote-data-group-list/quote-data-group-list.php or you may create a metadata extension in ./custom/Extension/modules/Products/clients/base/views/quote-data-group-list/. Next, modify the $viewdefs['Products']['base']['view']['quote-data-group-list']['panels'][0]['fields'] index to add or remove your preferred fields.

Example

The example below will remove the "Part Number" (products.mft_part_num) field and replace it with the "Weight" (products.weight) field.

./custom/modules/Products/clients/base/views/quote-data-group-list/quote-data-group-list.php

<?php

$viewdefs['Products']['base']['view']['quote-data-group-list'] = array(
    'panels' => array(
        array(
            'name' => 'products_quote_data_group_list',
            'label' => 'LBL_PRODUCTS_QUOTE_DATA_LIST',
            'fields' => array(
                array(
                    'name' => 'line_num',
                    'label' => null,
                    'widthClass' => 'cell-xsmall',
                    'css_class' => 'line_num tcenter',
                    'type' => 'line-num',
                    'readonly' => true,
                ),
                array(
                    'name' => 'quantity',
                    'label' => 'LBL_QUANTITY',
                    'widthClass' => 'cell-small',
                    'css_class' => 'quantity',
                    'type' => 'float',
                ),
                array(
                    'name' => 'product_template_name',
                    'label' => 'LBL_ITEM_NAME',
                    'widthClass' => 'cell-large',
                    'type' => 'quote-data-relate',
                    'required' => true,
                ),
                array(
                    'name' => 'weight',
                    'label' => 'LBL_WEIGHT',
                    'type' => 'float',
                ),
                array(
                    'name' => 'discount_price',
                    'label' => 'LBL_DISCOUNT_PRICE',
                    'type' => 'currency',
                    'convertToBase' => true,
                    'showTransactionalAmount' => true,
                    'related_fields' => array(
                        'discount_price',
                        'currency_id',
                        'base_rate',
                    ),
                ),
                array(
                    'name' => 'discount',
                    'type' => 'fieldset',
                    'css_class' => 'quote-discount-percent',
                    'label' => 'LBL_DISCOUNT_AMOUNT',
                    'fields' => array(
                        array(
                            'name' => 'discount_amount',
                            'label' => 'LBL_DISCOUNT_AMOUNT',
                            'type' => 'discount',
                            'convertToBase' => true,
                            'showTransactionalAmount' => true,
                        ),
                        array(
                            'type' => 'discount-select',
                            'name' => 'discount_select',
                            'no_default_action' => true,
                            'buttons' => array(
                                array(
                                    'type' => 'rowaction',
                                    'name' => 'select_discount_amount_button',
                                    'label' => 'LBL_DISCOUNT_AMOUNT',
                                    'event' => 'button:discount_select_change:click',
                                ),
                                array(
                                    'type' => 'rowaction',
                                    'name' => 'select_discount_percent_button',
                                    'label' => 'LBL_DISCOUNT_PERCENT',
                                    'event' => 'button:discount_select_change:click',
                                ),
                            ),
                        ),
                    ),
                ),
                array(
                    'name' => 'total_amount',
                    'label' => 'LBL_LINE_ITEM_TOTAL',
                    'type' => 'currency',
                    'widthClass' => 'cell-medium',
                    'showTransactionalAmount' => true,
                    'related_fields' => array(
                        'total_amount',
                        'currency_id',
                        'base_rate',
                    ),
                ),
            ),
        ),
    ),
);

Next, create the LBL_WEIGHT label under Quotes as this is not included in the stock installation. To accomplish this, we will need to create a language extension:

./custom/Extension/modules/Quotes/Ext/Language/en_us.weight.php

<?php

$mod_strings['LBL_WEIGHT'] = 'Weight';

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

Modifying Row Actions in the List Header

The Quotes List Header contains row actions to create and delete QLI groupings. The actions are identified by, the "check all" checkbox and vertical ellipsis or "hamburger" icon buttons. Editing the 'actions' will allow you to add more buttons to (or remove from) the "Group Selected" and "Delete Selected" buttons. The following section will outline how these items can be modified.

ListHeaderActionRow

To modify the Row Actions in the List Header, you can copy ./modules/Quotes/clients/base/views/quote-data-list-header/quote-data-list-header.php to ./custom/modules/Quotes/clients/base/views/quote-data-list-header/quote-data-list-header.php or you may create a metadata extension in ./custom/Extension/modules/Quotes/clients/base/views/quote-data-list-header/. Next, modify the $viewdefs['Quotes']['base']['view']['quote-data-list-header']['selection']['actions'] index to add or remove your preferred actions.

Example

The example below will create a new view that extends the QuotesQuoteDataListHeader view and append a row action to the List Header action list.

First, create your custom view type that will extend the QuotesQuoteDataListHeader view.

./custom/modules/Quotes/clients/base/views/quote-data-list-header/quote-data-list-header.js

({
    extendsFrom: 'QuotesQuoteDataListHeaderView',

    initialize: function(options) {
        this.events = _.extend({}, this.events, options.def.events, {
            'click [name="lh-custom-button"]': 'actionClicked'
        });

        this._super('initialize', [options]);
    },

    /**
     * Click event
     */
    actionClicked: function() {
        app.alert.show('success_alert', {
            level: 'success',
            title: 'List Header Row Action was clicked!'
        });
    },
})

This code will append a click event to our field named lh-custom-button and trigger the actionClicked method. Once completed, add your new row action to the list header in the $viewdefs['Quotes']['base']['view']['quote-data-list-header']['selection']['actions'] index.

./custom/modules/Quotes/clients/base/views/quote-data-list-header/quote-data-list-header.php

<?php

$viewdefs['Quotes']['base']['view']['quote-data-list-header'] = array(
    'selection' => array(
        'type' => 'multi',
        'actions' => array(
            array(
                'name' => 'group_button',
                'type' => 'rowaction',
                'label' => 'LBL_CREATE_GROUP_SELECTED_BUTTON_LABEL',
                'tooltip' => 'LBL_CREATE_GROUP_SELECTED_BUTTON_TOOLTIP',
                'acl_action' => 'edit',
            ),
            array(
                'name' => 'massdelete_button',
                'type' => 'rowaction',
                'label' => 'LBL_DELETE_SELECTED_LABEL',
                'tooltip' => 'LBL_DELETE_SELECTED_TOOLTIP',
                'acl_action' => 'delete',
            ),
            array(
                'name' => 'lh-custom-button',
                'type' => 'rowaction',
                'label' => 'LBL_LH_CUSTOM_ACTION',
                'tooltip' => 'LBL_LH_CUSTOM_ACTION_TOOLTIP',
                'acl_action' => 'edit',
            ),
        ),
    ),
);

Finally, create labels under Quotes for the label and tooltip indexes. To accomplish this, create a language extension:

./custom/Extension/modules/Quotes/Ext/Language/en_us.lh-custom-action.php

<?php

$mod_strings['LBL_LH_CUSTOM_ACTION'] = 'Custom Action';
$mod_strings['LBL_LH_CUSTOM_ACTION_TOOLTIP'] = 'Custom Action Tooltip';

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

Group Header

The Group Header contains the name and options for each grouping of quoted line items.

GroupHeader

 

Modifying Fields in the Group Header

To modify the Group Header fields, you can copy ./modules/ProductBundles/clients/base/views/quote-data-group-header/quote-data-group-header.php to ./custom/modules/ProductBundles/clients/base/views/quote-data-group-header/quote-data-group-header.php or you may create a metadata extension in ./custom/Extension/modules/Products/clients/base/views/quote-data-group-header/. Next, modify the $viewdefs['ProductBundles']['base']['view']['quote-data-group-header'] index to add or remove your preferred fields.

Example

The example below will append the group total (product_bundles.subtotal) field to the Group Header. It's important to note that when adding additional fields, that changes to the corresponding .hbs file may be necessary to correct any formatting issues.

./custom/modules/ProductBundles/clients/base/views/quote-data-group-header/quote-data-group-header.php

<?php

$viewdefs['ProductBundles']['base']['view']['quote-data-group-header'] = array(
    ...
    'panels' => array(
        array(
            'name' => 'panel_quote_data_group_header',
            'label' => 'LBL_QUOTE_DATA_GROUP_HEADER',
            'fields' => array(
                array(
                    'name' => 'name',
                    'type' => 'quote-group-title',
                    'css_class' => 'group-name',
                ),
                'subtotal',
            ),
        ),
    ),
);

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

Modifying Row Actions in the Group Header

The Quotes Group Header contains row actions to add QLIs and comments as well as editing and deleting QLI groupings. The actions are identified by, the plus and vertical ellipsis or "hamburger" icon buttons. The following section will outline how these items can be modified.

GroupHeaderRowActions

To modify the buttons in the Group Header, you can copy ./modules/ProductBundles/clients/base/views/quote-data-group-header/quote-data-group-header.php to ./custom/modules/ProductBundles/clients/base/views/quote-data-group-header/quote-data-group-header.php or you may create a metadata extension in ./custom/Extension/modules/ProductBundles/clients/base/views/quote-data-group-header/. Next, modify the $viewdefs['ProductBundles']['base']['view']['quote-data-group-header']['buttons'] index to add or remove your preferred actions.

Example

The example below will create a new view that extends the ProductBundlesQuoteDataGroupHeader view and append a row action to the Group Header vertical elipsis action list.

First, create your custom view type that will extend the ProductBundlesQuoteDataGroupHeader view.

./custom/modules/ProductBundles/clients/base/views/quote-data-group-header/quote-data-group-header.js

({
    extendsFrom: 'ProductBundlesQuoteDataGroupHeaderView',

    initialize: function(options) {
        this.events = _.extend({}, this.events, options.def.events, {
            'click [name="gh-custom-action"]': 'actionClicked'
        });

        this._super('initialize', [options]);
    },

    /**
     * Click event
     */
    actionClicked: function() {
        app.alert.show('success_alert', {
            level: 'success',
            title: 'Group Header Button was clicked!'
        });
    },
})

This code will append a click event to our field named gh-custom-action and trigger the actionClicked method. Once completed, add your new row action to the appropriate button group in $viewdefs['Quotes']['base']['view']['quote-data-group-header']['buttons']. For this example we will target a row action to the edit drop down that is identified in the arrays as having a name of "edit-dropdown". Once found, add your new array to the buttons index of that array.

./custom/modules/ProductBundles/clients/base/views/quote-data-group-header/quote-data-group-header.php

<?php

$viewdefs['ProductBundles']['base']['view']['quote-data-group-header'] = array(
    'buttons' => array(
        array(
            'type' => 'quote-data-actiondropdown',
            'name' => 'create-dropdown',
            'icon' => 'fa-plus',
            'no_default_action' => true,
            'buttons' => array(
                array(
                    'type' => 'rowaction',
                    'css_class' => 'btn-invisible',
                    'icon' => 'fa-plus',
                    'name' => 'create_qli_button',
                    'label' => 'LBL_CREATE_QLI_BUTTON_LABEL',
                    'tooltip' => 'LBL_CREATE_QLI_BUTTON_TOOLTIP',
                    'acl_action' => 'create',
                ),
                array(
                    'type' => 'rowaction',
                    'css_class' => 'btn-invisible',
                    'icon' => 'fa-plus',
                    'name' => 'create_comment_button',
                    'label' => 'LBL_CREATE_COMMENT_BUTTON_LABEL',
                    'tooltip' => 'LBL_CREATE_COMMENT_BUTTON_TOOLTIP',
                    'acl_action' => 'create',
                ),
            ),
        ),
        array(
            'type' => 'quote-data-actiondropdown',
            'name' => 'edit-dropdown',
            'icon' => 'fa-ellipsis-v',
            'no_default_action' => true,
            'buttons' => array(
                array(
                    'type' => 'rowaction',
                    'name' => 'edit_bundle_button',
                    'label' => 'LBL_EDIT_BUTTON',
                    'tooltip' => 'LBL_EDIT_BUNDLE_BUTTON_TOOLTIP',
                    'acl_action' => 'edit',
                ),
                array(
                    'type' => 'rowaction',
                    'name' => 'delete_bundle_button',
                    'label' => 'LBL_DELETE_GROUP_BUTTON',
                    'tooltip' => 'LBL_DELETE_BUNDLE_BUTTON_TOOLTIP',
                    'acl_action' => 'delete',
                ),
                array(
                    'type' => 'rowaction',
                    'name' => 'gh-custom-action',
                    'label' => 'LBL_GH_CUSTOM_ACTION',
                    'tooltip' => 'LBL_GH_CUSTOM_ACTION_TOOLTIP',
                    'acl_action' => 'edit',
                ),
            ),
        ),
    ),
    ...
);

Finally, create labels under Quotes for the label and tooltip indexes. To accomplish this, create a language extension:

./custom/Extension/modules/Quotes/Ext/Language/en_us.gh-custom-action.php

<?php

$mod_strings['LBL_GH_CUSTOM_ACTION'] = 'Custom Action';
$mod_strings['LBL_GH_CUSTOM_ACTION_TOOLTIP'] = 'Custom Action Tooltip';

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

Group List

The Group List contains the comments and selected quoted line items.

GroupList

Modifying Fields in the Group List

To modify the Group List fields, you can copy ./modules/Products/clients/base/views/quote-data-group-list/quote-data-group-list.php to ./custom/modules/Products/clients/base/views/quote-data-group-list/quote-data-group-list.php or you may create a metadata extension in ./custom/Extension/modules/Products/clients/base/views/quote-data-group-list/. Next, modify the $viewdefs['Products']['base']['view']['quote-data-group-list']['panels'] index to add or remove your preferred fields.

Example

The example below will remove the "Manufacturer Part Number" (products.mft_part_num) and append the "Vendor Part Number" (products.vendor_part_num) field to the Group List.

./custom/modules/Products/clients/base/views/quote-data-group-list/quote-data-group-list.php

<?php

$viewdefs['Products']['base']['view']['quote-data-group-list'] = array(
    'panels' => array(
        array(
            'name' => 'products_quote_data_group_list',
            'label' => 'LBL_PRODUCTS_QUOTE_DATA_LIST',
            'fields' => array(
                array(
                    'name' => 'line_num',
                    'label' => null,
                    'widthClass' => 'cell-xsmall',
                    'css_class' => 'line_num tcenter',
                    'type' => 'line-num',
                    'readonly' => true,
                ),
                array(
                    'name' => 'quantity',
                    'label' => 'LBL_QUANTITY',
                    'widthClass' => 'cell-small',
                    'css_class' => 'quantity',
                    'type' => 'float',
                ),
                array(
                    'name' => 'product_template_name',
                    'label' => 'LBL_ITEM_NAME',
                    'widthClass' => 'cell-large',
                    'type' => 'quote-data-relate',
                    'required' => true,
                ),
                array(
                    'name' => 'vendor_part_num',
                    'label' => 'LBL_VENDOR_PART_NUM',
                    'type' => 'base',
                ),
                array(
                    'name' => 'discount_price',
                    'label' => 'LBL_DISCOUNT_PRICE',
                    'type' => 'currency',
                    'convertToBase' => true,
                    'showTransactionalAmount' => true,
                    'related_fields' => array(
                        'discount_price',
                        'currency_id',
                        'base_rate',
                    ),
                ),
                array(
                    'name' => 'discount',
                    'type' => 'fieldset',
                    'css_class' => 'quote-discount-percent',
                    'label' => 'LBL_DISCOUNT_AMOUNT',
                    'fields' => array(
                        array(
                            'name' => 'discount_amount',
                            'label' => 'LBL_DISCOUNT_AMOUNT',
                            'type' => 'discount',
                            'convertToBase' => true,
                            'showTransactionalAmount' => true,
                        ),
                        array(
                            'type' => 'discount-select',
                            'name' => 'discount_select',
                            'no_default_action' => true,
                            'buttons' => array(
                                array(
                                    'type' => 'rowaction',
                                    'name' => 'select_discount_amount_button',
                                    'label' => 'LBL_DISCOUNT_AMOUNT',
                                    'event' => 'button:discount_select_change:click',
                                ),
                                array(
                                    'type' => 'rowaction',
                                    'name' => 'select_discount_percent_button',
                                    'label' => 'LBL_DISCOUNT_PERCENT',
                                    'event' => 'button:discount_select_change:click',
                                ),
                            ),
                        ),
                    ),
                ),
                array(
                    'name' => 'total_amount',
                    'label' => 'LBL_LINE_ITEM_TOTAL',
                    'type' => 'currency',
                    'widthClass' => 'cell-medium',
                    'showTransactionalAmount' => true,
                    'related_fields' => array(
                        'total_amount',
                        'currency_id',
                        'base_rate',
                    ),
                ),
            ),
        ),
    ),
);

Next, create the LBL_VENDOR_PART_NUM label under Quotes as this is not included in the stock installation. To accomplish this, we will need to create a language extension:

./custom/Extension/modules/Quotes/Ext/Language/en_us.vendor.php

<?php

$mod_strings['LBL_VENDOR_PART_NUM'] = 'Vendor Part Number';

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

Modifying Row Actions in the Group List

The Quotes Group List contains row actions to add/remove QLIs and comments. The actions are identified by, the vertical ellipsis icon buttons. The following section will outline how these items can be modified.

GroupListActionRow

To modify the buttons in the Group List , you can copy ./modules/ProductBundles/clients/base/views/quote-data-group-list/quote-data-group-list.php to ./custom/modules/ProductBundles/clients/base/views/quote-data-group-list/quote-data-group-list.php or you may create a metadata extension in ./custom/Extension/modules/ProductBundles/clients/base/views/quote-data-group-list/. Next, modify the $viewdefs['ProductBundles']['base']['view']['quote-data-group-list']['selection'] index to add or remove your preferred actions.

Example

The example below will create a new view that extends the ProductBundlesQuoteDataGroupList view and append a row action to the Group List's vertical elipsis action list.

First, create your custom view type that will extend the ProductBundlesQuoteDataGroupList view. This will contain the JavaScript for your action.

./custom/modules/ProductBundles/clients/base/views/quote-data-group-list/quote-data-group-list.js

({
    extendsFrom: 'ProductBundlesQuoteDataGroupListView',

    initialize: function(options) {
        this.events = _.extend({}, this.events, options.def.events, {
            'click [name="gl-custom-action"]': 'actionClicked'
        });

        this._super('initialize', [options]);
    },

    /**
     * Click event
     */
    actionClicked: function() {
        app.alert.show('success_alert', {
            level: 'success',
            title: 'List Header Row Action was clicked!'
        });
    },
})

This code will append a click event to our field named gl-custom-action and trigger the actionClicked method. Once completed, add your new row action to the group list in the $viewdefs['ProductBundles']['base']['view']['quote-data-group-list']['selection'['actions'] index.

./custom/modules/ProductBundles/clients/base/views/quote-data-group-list/quote-data-group-list.php

<?php

$viewdefs['ProductBundles']['base']['view']['quote-data-group-list'] = array(
    'selection' => array(
        'type' => 'multi',
        'actions' => array(
            array(
                'type' => 'rowaction',
                'name' => 'edit_row_button',
                'label' => 'LBL_EDIT_BUTTON',
                'tooltip' => 'LBL_EDIT_BUTTON',
                'acl_action' => 'edit',
            ),
            array(
                'type' => 'rowaction',
                'name' => 'delete_row_button',
                'label' => 'LBL_DELETE_BUTTON',
                'tooltip' => 'LBL_DELETE_BUTTON',
                'acl_action' => 'delete',
            ),
            array(
                'type' => 'rowaction',
                'name' => 'gl-custom-action',
                'label' => 'LBL_GL_CUSTOM_ACTION',
                'tooltip' => 'LBL_GL_CUSTOM_ACTION_TOOLTIP',
                'acl_action' => 'edit',
            ),
        ),
    ),
);

Finally, create labels under Quotes for the label and tooltip indexes. To accomplish this, create a language extension:

./custom/Extension/modules/Quotes/Ext/Language/en_us.gh-custom-action.php

<?php

$mod_strings['LBL_GL_CUSTOM_ACTION'] = 'Custom Action';
$mod_strings['LBL_GL_CUSTOM_ACTION_TOOLTIP'] = 'Custom Action Tooltip';

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

The Group Footer contains the total for each grouping of quoted line items.

GroupFooter

To modify the GroupFooter fields, you can copy ./modules/ProductBundles/clients/base/views/quote-data-group-footer/quote-data-group-footer.php to ./custom/modules/ProductBundles/clients/base/views/quote-data-group-footer/quote-data-group-footer.php or you may create a metadata extension in ./custom/Extension/modules/ProductBundles/clients/base/views/quote-data-group-footer/. Next, modify the $viewdefs['ProductBundles']['base']['view']['quote-data-group-footer'] index to add or remove your preferred fields.

Example

The example below will append the bundle stage (product_bundles.bundle_stage) field to the Group Footer. It's important to note that when adding additional fields, that changes to the corresponding .hbs file may be necessary to correct any formatting issues.

./custom/modules/ProductBundles/clients/base/views/quote-data-group-header/quote-data-group-footer.php

<?php

$viewdefs['ProductBundles']['base']['view']['quote-data-group-footer'] = array(
    'panels' => array(
        array(
            'name' => 'panel_quote_data_group_footer',
            'label' => 'LBL_QUOTE_DATA_GROUP_FOOTER',
            'fields' => array(
                'bundle_stage',
                array(
                    'name' => 'new_sub',
                    'label' => 'LBL_GROUP_TOTAL',
                    'type' => 'currency',
                ),
            ),
        ),
    ),
);

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

The Grand Total Footer contains the calculated totals for the quote. It mimics the information found in the Grand Total Header.

GrandTotalsFooter

To modify the Grand Totals Footer fields, you can copy ./modules/Quotes/clients/base/views/quote-data-grand-totals-footer/quote-data-grand-totals-footer.php to ./custom/modules/Quotes/clients/base/views/quote-data-grand-totals-footer/quote-data-grand-totals-footer.php or you may create a metadata extension in ./custom/Extension/modules/Quotes/clients/base/views/quote-data-grand-totals-footer/. Next, modify the $viewdefs['Quotes']['base']['view']['quote-data-grand-totals-footer']['panels'][0]['fields'] index to add or remove your preferred fields.

Example

The example below will remove the "Shipping" field (quotes.shipping) field from the layout.

./custom/modules/Quotes/clients/base/views/quote-data-grand-totals-footer/quote-data-grand-totals-footer.php

<?php

$viewdefs['Quotes']['base']['view']['quote-data-grand-totals-footer'] = array(
    'panels' => array(
        array(
            'name' => 'panel_quote_data_grand_totals_footer',
            'label' => 'LBL_QUOTE_DATA_GRAND_TOTALS_FOOTER',
            'fields' => array(
                'quote_num',
                array(
                    'name' => 'new_sub',
                    'type' => 'currency',
                ),
                array(
                    'name' => 'tax',
                    'type' => 'currency',
                    'related_fields' => array(
                        'taxrate_value',
                    ),
                ),
                array(
                    'name' => 'total',
                    'label' => 'LBL_LIST_GRAND_TOTAL',
                    'type' => 'currency',
                    'css_class' => 'grand-total',
                ),
            ),
        ),
    ),
);

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

Quote PDFs

Ungrouped Quoted Line Items and Notes

As of Sugar 7.9, the quotes module allows users to add quoted line items and notes without first adding a group. Adding at least one group to your quote was mandatory in earlier versions. This document will cover how to update your custom PDF templates to support ungrouped QLIs and notes. Ungrouped items are technically added to a default group. The goal is to exclude this group when no items exist in it.

PDF Manager Templates

In your PDF Manager templates, you may have code similar to what is shown below to iterate over the groups in a quote:

{foreach from=$product_bundles item="bundle"}
    ....
{/foreach}

To correct this for 7.9, we will need to add an if statement to check to see if the group is empty. If it is empty, it will be ignored in your PDF. The benefit is that it will also exclude any other empty groups in your quote and clean the generated PDF.

{foreach from=$product_bundles item="bundle"}
    {if $bundle.products|@count}
        ....
    {/if}
{/foreach}

Smarty Templates

In Smarty templates, you may have code similar to what is shown below to iterate over the groups in a quote:

{literal}{foreach from=$product_bundles item="bundle"}{/literal}
    ...
{literal}{/foreach}{/literal}

To correct this for 7.9, we will need to add an if statement to check to see if the group is empty. If it is empty, it will be ignored in your PDF. The benefit is that it will also exclude any other empty groups in your quote and clean the generated PDF.

{literal}{foreach from=$product_bundles item="bundle"}{/literal}
    {literal}{if $bundle.products|@count}{/literal}
        ...
    {literal}{/if}{/literal}
{literal}{/foreach}{/literal}

Creating Custom PDF Templates

With Sugar, there are generally two routes that can be taken to create custom PDF templates. The first and most recommended route is to use the PDF Manager found in the Admin > PDF Manager. The second route is to extend the Sugarpdf class and write your own template using PHP and the TCPDF library. This method should only be used if you are unable to accomplish your business needs through the PDF Manager.

Creating the TCPDF Template

To create a custom templateThe first step is to create your custom TCPDF template in ./custom/modules/Quotes/sugarpdf/. For our example, we will extend QuotesSugarpdfStandard, found at ./modules/Quotes/sugarpdf/sugarpdf.standard.php, to a new file in ./custom/modules/Quotes/sugarpdf/ to create a custom invoice. The QuotesSugarpdfStandard class sets up our general quote requirements and extends the Sugarpdf class. Technical documentation on templating can be found in the Sugar PDF documentation. Our class will be named QuotesSugarpdfCustomInvoice as the naming must be in the format of <module>Sugarpdf<pdf view>.

./custom/modules/Quotes/sugarpdf/sugarpdf.custominvoice.php

<?php

if (!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');

require_once('modules/Quotes/sugarpdf/sugarpdf.standard.php');

class QuotesSugarpdfCustomInvoice extends QuotesSugarpdfStandard
{
    function preDisplay()
    {
        global $mod_strings, $timedate;
        parent::preDisplay();

        $quote[0]['TITLE'] = $mod_strings['LBL_PDF_INVOICE_NUMBER'];
        $quote[1]['TITLE'] = $mod_strings['LBL_PDF_QUOTE_DATE'];
        $quote[2]['TITLE'] = $mod_strings['LBL_PURCHASE_ORDER_NUM'];
        $quote[3]['TITLE'] = $mod_strings['LBL_PAYMENT_TERMS'];
        $quote[0]['VALUE']['value'] = format_number_display($this->bean->quote_num, $this->bean->system_id);
        $quote[1]['VALUE']['value'] = $timedate->nowDate();
        $quote[2]['VALUE']['value'] = $this->bean->purchase_order_num;
        $quote[3]['VALUE']['value'] = $this->bean->payment_terms;
        // these options override the params of the $options array.
        $quote[0]['VALUE']['options'] = array();
        $quote[1]['VALUE']['options'] = array();
        $quote[2]['VALUE']['options'] = array();
        $quote[3]['VALUE']['options'] = array();

        $html = $this->writeHTMLTable($quote, true, $this->headerOptions);
        $this->SetHeaderData(PDF_HEADER_LOGO, PDF_HEADER_LOGO_WIDTH, $mod_strings['LBL_PDF_INVOICE_TITLE'], $html);
    }

    /**
     * This method build the name of the PDF file to output.
     */
    function buildFileName()
    {
        global $mod_strings;

        $fileName = preg_replace("#[^A-Z0-9\-_\.]#i", "_", $this->bean->shipping_account_name);

        if (!empty($this->bean->quote_num)) {
            $fileName .= "_{$this->bean->quote_num}";
        }

        $fileName = $mod_strings['LBL_INVOICE'] . "_{$fileName}.pdf";

        if (isset($_SERVER['HTTP_USER_AGENT']) && preg_match("/MSIE/", $_SERVER['HTTP_USER_AGENT'])) {
            //$fileName = $locale->translateCharset($fileName, $locale->getExportCharset());
            $fileName = urlencode($fileName);
        }

        $this->fileName = $fileName;
    }
}

Next, register the layout. This is a two step process. The first step is to create ./custom/modules/Quotes/Layouts.php which will map our view action to the physical PHP file.

./custom/modules/Quotes/Layouts.php

<?php

$layouts['CustomInvoice'] = 'custom/modules/Quotes/sugarpdf/sugarpdf.custominvoice.php';

The second step is to update the layouts_dom dropdown list by navigating to Admin > Dropdown Editor. Once there, create a new entry in the list with an Item Name of "CustomInvoice" and a Display Label of your choice. This will create a ./custom/Extension/application/Ext/Language/en_us.sugar_layouts_dom.php file that should look similar to:

./custom/Extension/application/Ext/Language/en_us.sugar_layouts_dom.php

<?php

$app_list_strings['layouts_dom']=array (
  'Standard' => 'Quote',
  'Invoice' => 'Invoice',
  'CustomInvoice' => 'Custom Invoice',
);

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system and navigating to a url in the format of index.php?module=Quotes&record=<record id>&action=sugarpdf&sugarpdf=CustomInvoice will generate the pdf document.

Hiding PDF Buttons

In some circumstances, users may not have a need to generate PDFs from Quotes. If this should occur, a developer can copy ./modules/Quotes/clients/base/views/record/record.php to ./custom/modules/Quotes/clients/base/views/record/record.php if it doesn't already exist. Next, find the array with a name of main_dropwdown in the $viewdefs['Quotes']['base']['view']['record']['buttons'] index. Once found, you will then need to locate the buttons index within that array. You will then need to remove the following arrays from that index:

array(
    'type' => 'pdfaction',
    'name' => 'download-pdf',
    'label' => 'LBL_PDF_VIEW',
    'action' => 'download',
    'acl_action' => 'view',
),
array(
    'type' => 'pdfaction',
    'name' => 'email-pdf',
    'label' => 'LBL_PDF_EMAIL',
    'action' => 'email',
    'acl_action' => 'view',
),

Your file should look similar to what is shown below:

custom/modules/Quotes/clients/base/views/record/record.php

<?php

$viewdefs['Quotes']['base']['view']['record'] = array(
    'buttons' => array(
        array(
            'type' => 'button',
            'name' => 'cancel_button',
            'label' => 'LBL_CANCEL_BUTTON_LABEL',
            'css_class' => 'btn-invisible btn-link',
            'showOn' => 'edit',
            'events' => array(
                'click' => 'button:cancel_button:click',
            ),
        ),
        array(
            'type' => 'rowaction',
            'event' => 'button:save_button:click',
            'name' => 'save_button',
            'label' => 'LBL_SAVE_BUTTON_LABEL',
            'css_class' => 'btn btn-primary',
            'showOn' => 'edit',
            'acl_action' => 'edit',
        ),
        array(
            'type' => 'actiondropdown',
            'name' => 'main_dropdown',
            'primary' => true,
            'showOn' => 'view',
            'buttons' => array(
                array(
                    'type' => 'rowaction',
                    'event' => 'button:edit_button:click',
                    'name' => 'edit_button',
                    'label' => 'LBL_EDIT_BUTTON_LABEL',
                    'acl_action' => 'edit',
                ),
                array(
                    'type' => 'shareaction',
                    'name' => 'share',
                    'label' => 'LBL_RECORD_SHARE_BUTTON',
                    'acl_action' => 'view',
                ),
                array(
                    'type' => 'divider',
                ),
                array(
                    'type' => 'convert-to-opportunity',
                    'event' => 'button:convert_to_opportunity:click',
                    'name' => 'convert_to_opportunity_button',
                    'label' => 'LBL_QUOTE_TO_OPPORTUNITY_LABEL',
                    'acl_module' => 'Opportunities',
                    'acl_action' => 'create',
                ),
                array(
                    'type' => 'divider',
                ),
                array(
                    'type' => 'rowaction',
                    'event' => 'button:historical_summary_button:click',
                    'name' => 'historical_summary_button',
                    'label' => 'LBL_HISTORICAL_SUMMARY',
                    'acl_action' => 'view',
                ),
                array(
                    'type' => 'rowaction',
                    'event' => 'button:audit_button:click',
                    'name' => 'audit_button',
                    'label' => 'LNK_VIEW_CHANGE_LOG',
                    'acl_action' => 'view',
                ),
                array(
                    'type' => 'rowaction',
                    'event' => 'button:find_duplicates_button:click',
                    'name' => 'find_duplicates_button',
                    'label' => 'LBL_DUP_MERGE',
                    'acl_action' => 'edit',
                ),
                array(
                    'type' => 'divider',
                ),
                array(
                    'type' => 'rowaction',
                    'event' => 'button:delete_button:click',
                    'name' => 'delete_button',
                    'label' => 'LBL_DELETE_BUTTON_LABEL',
                    'acl_action' => 'delete',
                ),
            ),
        ),
        array(
            'name' => 'sidebar_toggle',
            'type' => 'sidebartoggle',
        ),
    ),
    ...
);

Once the files are in place, navigate to Admin > Repair > Quick Repair and Rebuild. Your changes will now be reflected in the system.

Last modified: 05/20/2017 01:49pm