How to Use Custom Placeholders

In Docentric print destinations you can use placeholders. Custom placeholders are report specific, and they are needed if the set of Standard placeholders is not sufficient to meet your needs.

Learn more about Standard placeholders >>

No matter if you are using Free or Full Edition, you can use both Standard and Custom placeholders. Moreover, we recommend you to install an additional model containing so called Docentric SSRS Replicas that already provide certain Custom placeholders for common reports such as Sales invoice and Purchase order.
Learn more >>

To implement Custom placeholders from scratch you will need to extend the Docentric’s base DSP class (DocDataSourceProviderSrsReporting), which is also called Default DSP class, and override the overrideReportRunSettings() method.

Besides overriding the overrideReportRunSettings() method, you have to decorate the same method with the DocPlaceholderAttribute attributes. For each of Custom placeholders, one DocPlaceholderAttribute attribute needs to be introduced, as shown in the following example.

If you have installed Docentric SSRS Replicas, and you need to add an additional report specific placeholder, you will be able to do more easily by following the same pattern described here but in the existing report's DSP class, which is a part of the installed model.

Define and replace Custom placeholders with the corresponding values

Let’s say that for Purchase order you want to provide some Custom placeholders as an addition to Standard placeholders:

@PurchId@
Note: It’s easier to use a Custom placeholder than the Standard one @FIELD_PurchId@; that’s why we introduced it.
@VendAccount@
@VendContactName@
@ResponseEndDate@

These Custom placeholders will be available for use in the File and Email print destinations.

You can use Visual Studio template of DSP class called DSP Class for Print Destination Placeholders.

Take a look at this custom DSP class (DTPurchPurchaseOrderDSP_OverrideRRS) for the Purchase order report:

class DTPurchPurchaseOrderDSP_OverrideRRS extends DocDataSourceProviderSrsReporting
{
    // NOTE: This is a global variable fetched in the onSelectedRdpTableRecord() method
    // and used in the overrideReportRunSettings() method to manage custom placeholders.
    PurchTable purchTable;

 
    public ClassDescription description()
    {
        return 'Purchse Order DSP';
    }

    // NOTE: This method is executed when a record is selected from each of RDP tables.
    protected void onSelectedRdpTableRecord(Common _rdpTableRecord, TableName _rdpTableName)
    {
        super(_rdpTableRecord, _rdpTableName);
            
        if (_rdpTableName == tableStr(PurchPurchaseOrderHeader))
        {
            PurchPurchaseOrderHeader purchOrderHeader = _rdpTableRecord;

            // Fetch and store the related purchTable.
            purchTable = purchTable::find(purchOrderHeader.PurchId);
        }
    }


    // List of defined custom placeholders for the report:
    #define.PurchId('PurchId')
    #define.VendAccount('VendAccount')
    #define.VendContactName('VendContactName')
    #define.ResponseEndDate('ResponseEndDate')

    // NOTE: This method is executed after all RDP table records are selected (and the report data
    // source is built), which means that the corresponding PurchTable record is stored into a global
    // variable and can be used in this method to replace all defined custom placeholders.
    [DocPlaceholderAttribute(#PurchId, 'PO - Purch ID'),
     DocPlaceholderAttribute(#VendAccount, 'PO - Vendor Account ID'),
     DocPlaceholderAttribute(#VendContactName, 'PO - Vendor Contact Name'),
     DocPlaceholderAttribute(#ResponseEndDate, 'PO - Response Date')]
    public DocPlaceholderManager overrideReportRunSettings(
        DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)
    {
        // NOTE: Call super() because of standard placeholders such as @WORKER@ and @USEREMAIL@.
        DocPlaceholderManager placeholderMng = super(_reportRunContext, _replaceStandardPlaceholders);
            
        // NOTE: Make sure that the purchTable is a global class variable fetched in
        // the addDataFieldsForRdpTableRecord() or onSelectedRdpTableRecord() method.
                
        // -- Placeholder @VendContactName@
        str vendContactPersonName = purchTable.contactPersonName();
        if (!vendContactPersonName)
        {
            vendContactPersonName = 'Dear Mr./Mrs.';
        }
        placeholderMng.replacePlaceholderInCurrentPrintDest(#VendContactName, vendContactPersonName);
                
        // -- Placeholder @PurchId@
        placeholderMng.replacePlaceholderInCurrentPrintDest(#PurchId, purchTable.PurchId);
                
        // -- Placeholder @ResponseEndDate@
        placeholderMng.replacePlaceholderInCurrentPrintDest(#ResponseEndDate, systemDateGet() + 7);

        // -- Placeholder @VendAccount@
        placeholderMng.replacePlaceholderInCurrentPrintDest(#VendAccount, purchTable.OrderAccount);
            
        return placeholderMng;
    }
}

class DTPurchPurchaseOrderDSP_OverrideRRS extends DocDataSourceProviderSrsReporting

{

// NOTE: This is a global variable fetched in the onSelectedRdpTableRecord() method

// and used in the overrideReportRunSettings() method to manage custom placeholders.

PurchTable purchTable;

public ClassDescription description()

{

return 'Purchse Order DSP';

}

// NOTE: This method is executed when a record is selected from each of RDP tables.

protected void onSelectedRdpTableRecord(Common _rdpTableRecord, TableName _rdpTableName)

{

super(_rdpTableRecord, _rdpTableName);

if (_rdpTableName == tableStr(PurchPurchaseOrderHeader))

{

PurchPurchaseOrderHeader purchOrderHeader = _rdpTableRecord;

// Fetch and store the related purchTable.

purchTable = purchTable::find(purchOrderHeader.PurchId);

}

// List of defined custom placeholders for the report:

#define.PurchId('PurchId')

#define.VendAccount('VendAccount')

#define.VendContactName('VendContactName')

#define.ResponseEndDate('ResponseEndDate')

// NOTE: This method is executed after all RDP table records are selected (and the report data

// source is built), which means that the corresponding PurchTable record is stored into a global

// variable and can be used in this method to replace all defined custom placeholders.

[DocPlaceholderAttribute(#PurchId, 'PO - Purch ID'),

DocPlaceholderAttribute(#VendAccount, 'PO - Vendor Account ID'),

DocPlaceholderAttribute(#VendContactName, 'PO - Vendor Contact Name'),

DocPlaceholderAttribute(#ResponseEndDate, 'PO - Response Date')]

public DocPlaceholderManager overrideReportRunSettings(

DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)

{

// NOTE: Call super() because of standard placeholders such as @WORKER@ and @USEREMAIL@.

DocPlaceholderManager placeholderMng = super(_reportRunContext, _replaceStandardPlaceholders);

// NOTE: Make sure that the purchTable is a global class variable fetched in

// the addDataFieldsForRdpTableRecord() or onSelectedRdpTableRecord() method.

// -- Placeholder @VendContactName@

str vendContactPersonName = purchTable.contactPersonName();

if (!vendContactPersonName)

{

vendContactPersonName = 'Dear Mr./Mrs.';

}

placeholderMng.replacePlaceholderInCurrentPrintDest(#VendContactName, vendContactPersonName);

// -- Placeholder @PurchId@

placeholderMng.replacePlaceholderInCurrentPrintDest(#PurchId, purchTable.PurchId);

// -- Placeholder @ResponseEndDate@

placeholderMng.replacePlaceholderInCurrentPrintDest(#ResponseEndDate, systemDateGet() + 7);

// -- Placeholder @VendAccount@

placeholderMng.replacePlaceholderInCurrentPrintDest(#VendAccount, purchTable.OrderAccount);

return placeholderMng;

}

Custom image placeholders

You can also email reports with images from the database in the email body using Custom image placeholders.
Image placeholders are defined using a different attribute - DocPlaceholderImageAttribute:

DocPlaceholderImageAttribute(#SalesTakerImage, 'SO - Sales Taker Picture', 80, 80)

1	DocPlaceholderImageAttribute(#SalesTakerImage, 'SO - Sales Taker Picture', 80, 80)

Also, for replacing an image placeholder with the image content loaded, e.g. from the database, we need to use a different method of Placeholder manager - placeholderMng.replacePlaceholderImage():

if (_reportRunContext.parmPrintDestination() == DocPrintDestination::Email)
{
    // -- Placeholder @SalesTakerImage@
    if (DocPlaceholderManager::findPlaceholder(_reportRunContext.emailPrintDestSettings().parmEmailBody(), #SalesTakerImage))
    {
        HcmWorker worker = HcmWorker::find(this.custConfirmJour().WorkerSalesTaker);
        if (worker)
        {
            Bitmap workerImage = worker.personImage();
            if (workerImage)
                placeholderMng.replacePlaceholderImage(#SalesTakerImage, workerImage);
        }
    }
}

if (_reportRunContext.parmPrintDestination() == DocPrintDestination::Email)

{

// -- Placeholder @SalesTakerImage@

if (DocPlaceholderManager::findPlaceholder(_reportRunContext.emailPrintDestSettings().parmEmailBody(), #SalesTakerImage))

{

HcmWorker worker = HcmWorker::find(this.custConfirmJour().WorkerSalesTaker);

if (worker)

{

Bitmap workerImage = worker.personImage();

if (workerImage)

placeholderMng.replacePlaceholderImage(#SalesTakerImage, workerImage);

}

Learn more on how to use Custom image placeholders >>

Set up the custom DSP class to be used in Docentric report setup

In order to set up the Purchase order report to use this custom DSP class (DTPurchPurchaseOrderDSP_OverrideRRS) with the overridden overrideReportRunSettings() method, you have to add Purchase order to Docentric report setup (if you haven't done this yet). Next, you need to select this new custom DSP class to be used for Purchase order instead of the Default DSP class.

Learn how to add an SSRS report to Docentric report setup >>

Now we can use both Standard and these four Custom placeholders in the File and Email print destination settings for the Purchase order report.

CONTENTS

How to Use Custom Placeholders

IN THIS ARTICLE

Define and replace Custom placeholders with the corresponding values

Custom image placeholders

Set up the custom DSP class to be used in Docentric report setup

See also

IN THIS ARTICLE