Apply Custom Formatting to Fields

Sometimes users need to apply custom formatting to fields. In this article, we will look at a couple of examples of how this can be done.

To learn more options, see the full list of properties for each field type in the corresponding class in the Fields namespace.

How to Apply Custom Formatting to Field Result

Aspose.Words provides API for custom formatting of field’s result. You can implement IFieldResultFormatter interface to control how the field result is formatted. You can apply numeric format switch, i.e. # “#.##”, date/time format switch, i.e. @ “dd.MM.yyyy”, and number format switch, i.e. * Ordinal.

The following code example shows how to apply custom formatting for the field result:

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

auto field = builder->InsertField(u"=-1234567.89 \\# \"### ### ###.000\"", nullptr);
doc->get_FieldOptions()->set_ResultFormatter(System::MakeObject<FieldResultFormatter>(u"[{0:N2}]", nullptr));

field->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.FormatFieldResult.docx");

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
class FieldResultFormatter : public IFieldResultFormatter
{
public:
    enum class FormatInvocationType
    {
        Numeric,
        DateTime,
        General,
        All
    };

private:
    class FormatInvocation : public System::Object
    {
    public:
        ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType get_FormatInvocationType()
        {
            return pr_FormatInvocationType;
        }

        SharedPtr<System::Object> get_Value()
        {
            return pr_Value;
        }

        String get_OriginalFormat()
        {
            return pr_OriginalFormat;
        }

        String get_NewValue()
        {
            return pr_NewValue;
        }

        FormatInvocation(ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType formatInvocationType, SharedPtr<System::Object> value,
                         String originalFormat, String newValue)
            : pr_FormatInvocationType(((ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType)0))
        {
            pr_Value = value;
            pr_FormatInvocationType = formatInvocationType;
            pr_OriginalFormat = originalFormat;
            pr_NewValue = newValue;
        }

    private:
        ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType pr_FormatInvocationType;
        SharedPtr<System::Object> pr_Value;
        String pr_OriginalFormat;
        String pr_NewValue;
    };

public:
    FieldResultFormatter(String numberFormat, String dateFormat, String generalFormat)
        : mFormatInvocations(MakeObject<System::Collections::Generic::List<SharedPtr<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>>>())
    {
        mNumberFormat = numberFormat;
        mDateFormat = dateFormat;
        mGeneralFormat = generalFormat;
    }

    String FormatNumeric(double value, String format) override
    {
        if (String::IsNullOrEmpty(mNumberFormat))
        {
            return nullptr;
        }

        String newValue = String::Format(mNumberFormat, value);
        get_FormatInvocations()->Add(MakeObject<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>(
            ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::Numeric, System::ObjectExt::Box<double>(value), format, newValue));
        return newValue;
    }

    String FormatDateTime(System::DateTime value, String format, CalendarType calendarType) override
    {
        if (String::IsNullOrEmpty(mDateFormat))
        {
            return nullptr;
        }

        String newValue = String::Format(mDateFormat, value);
        get_FormatInvocations()->Add(MakeObject<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>(
            ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::DateTime,
            System::ObjectExt::Box<String>(String::Format(u"{0} ({1})", value, calendarType)), format, newValue));
        return newValue;
    }

    String Format(String value, GeneralFormat format) override
    {
        return Format(System::ObjectExt::Box<String>(value), format);
    }

    String Format(double value, GeneralFormat format) override
    {
        return Format(System::ObjectExt::Box<double>(value), format);
    }

    int CountFormatInvocations(ExDocumentBuilder::FieldResultFormatter::FormatInvocationType formatInvocationType)
    {
        if (formatInvocationType == ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::All)
        {
            return get_FormatInvocations()->get_Count();
        }

        std::function<bool(SharedPtr<FormatInvocation> f)> hasValidFormatInvocationType = [&formatInvocationType](SharedPtr<FormatInvocation> f)
        {
            return f->get_FormatInvocationType() == formatInvocationType;
        };

        return get_FormatInvocations()->LINQ_Count(hasValidFormatInvocationType);
    }

    void PrintFormatInvocations()
    {
        for (const auto& f : get_FormatInvocations())
        {
            std::cout << (String::Format(u"Invocation type:\t{0}\n", f->get_FormatInvocationType()) +
                          String::Format(u"\tOriginal value:\t\t{0}\n", f->get_Value()) +
                          String::Format(u"\tOriginal format:\t{0}\n", f->get_OriginalFormat()) +
                          String::Format(u"\tNew value:\t\t\t{0}\n", f->get_NewValue()))
                      << std::endl;
        }
    }

private:
    String mNumberFormat;
    String mDateFormat;
    String mGeneralFormat;
    SharedPtr<System::Collections::Generic::List<SharedPtr<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>>> mFormatInvocations;

    SharedPtr<System::Collections::Generic::List<SharedPtr<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>>> get_FormatInvocations()
    {
        return mFormatInvocations;
    }

    String Format(SharedPtr<System::Object> value, GeneralFormat format)
    {
        if (String::IsNullOrEmpty(mGeneralFormat))
        {
            return nullptr;
        }

        String newValue = String::Format(mGeneralFormat, value);
        get_FormatInvocations()->Add(MakeObject<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>(
            ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::General, value, System::ObjectExt::ToString(format), newValue));
        return newValue;
    }
};

How to evaluate IF condition

If you want to evaluate IF condition after mail merge, you can use the EvaluateCondition method that immediately returns the result of the expression evaluation.

The following code example shows how to use this method:

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto builder = MakeObject<DocumentBuilder>();

auto field = System::DynamicCast<FieldIf>(builder->InsertField(u"IF 1 = 1", nullptr));
FieldIfComparisonResult actualResult = field->EvaluateCondition();

std::cout << System::EnumGetName(actualResult) << std::endl;

How to Apply Custom Formatting to Time Field

By default Aspose.Words updates TIME field with current culture short time format. If you want to format the TIME field according to your requirement, you can achieve this by implementing IFieldUpdateCultureProvider interface.

The following code examples shows how to apply custom formatting to the TIME field:

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

builder->InsertField(FieldType::FieldTime, true);

doc->get_FieldOptions()->set_FieldUpdateCultureSource(FieldUpdateCultureSource::FieldCode);
doc->get_FieldOptions()->set_FieldUpdateCultureProvider(MakeObject<WorkingWithFields::FieldUpdateCultureProvider>());

doc->Save(ArtifactsDir + u"WorkingWithFields.FieldUpdateCulture.pdf");

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
class FieldUpdateCultureProvider : public IFieldUpdateCultureProvider
{
public:
    SharedPtr<System::Globalization::CultureInfo> GetCulture(String name, SharedPtr<Field> field) override
    {
        ASPOSE_UNUSED(field);
        if (name == u"ru-RU")
        {
            auto culture = MakeObject<System::Globalization::CultureInfo>(name, false);
            SharedPtr<System::Globalization::DateTimeFormatInfo> format = culture->get_DateTimeFormat();
            format->set_MonthNames(MakeArray<String>({u"месяц 1", u"месяц 2", u"месяц 3", u"месяц 4", u"месяц 5", u"месяц 6", u"месяц 7", u"месяц 8",
                                                      u"месяц 9", u"месяц 10", u"месяц 11", u"месяц 12", u""}));
            format->set_MonthGenitiveNames(format->get_MonthNames());
            format->set_AbbreviatedMonthNames(MakeArray<String>(
                {u"мес 1", u"мес 2", u"мес 3", u"мес 4", u"мес 5", u"мес 6", u"мес 7", u"мес 8", u"мес 9", u"мес 10", u"мес 11", u"мес 12", u""}));
            format->set_AbbreviatedMonthGenitiveNames(format->get_AbbreviatedMonthNames());
            format->set_DayNames(MakeArray<String>(
                {u"день недели 7", u"день недели 1", u"день недели 2", u"день недели 3", u"день недели 4", u"день недели 5", u"день недели 6"}));
            format->set_AbbreviatedDayNames(MakeArray<String>({u"день 7", u"день 1", u"день 2", u"день 3", u"день 4", u"день 5", u"день 6"}));
            format->set_ShortestDayNames(MakeArray<String>({u"д7", u"д1", u"д2", u"д3", u"д4", u"д5", u"д6"}));
            format->set_AMDesignator(u"До полудня");
            format->set_PMDesignator(u"После полудня");
            const String pattern = u"yyyy MM (MMMM) dd (dddd) hh:mm:ss tt";
            format->set_LongDatePattern(pattern);
            format->set_LongTimePattern(pattern);
            format->set_ShortDatePattern(pattern);
            format->set_ShortTimePattern(pattern);
            return culture;
        }
        else if (name == u"en-US")
        {
            return MakeObject<System::Globalization::CultureInfo>(name, false);
        }
        else
        {
            return nullptr;
        }
    }
};