TemplateParser::TemplateParserJob Class
The TemplateParser transforms a message with a given template. More...
| Header: | #include <TemplateParser/TemplateParserJob> |
| CMake: | find_package(KPim6TemplateParser REQUIRED)target_link_libraries(mytarget PRIVATE KPim6::TemplateParser) |
| Inherits: | QObject |
Public Functions
| TemplateParserJob(const std::shared_ptr<KMime::Message> &amsg, const TemplateParser::TemplateParserJob::Mode amode, QObject *parent = nullptr) | |
| virtual | ~TemplateParserJob() override |
| void | process(const std::shared_ptr<KMime::Message> &aorig_msg, qint64 afolder = -1) |
| void | process(const QString &tmplName, const std::shared_ptr<KMime::Message> &aorig_msg, qint64 afolder = -1) |
| void | processWithIdentity(uint uoid, const std::shared_ptr<KMime::Message> &aorig_msg, qint64 afolder = -1) |
| void | processWithTemplate(const QString &tmpl) |
| void | setAllowDecryption(const bool allowDecryption) |
| void | setIdentityManager(const KIdentityManagementCore::IdentityManager *ident) |
| void | setReplyAsHtml(bool replyAsHtml) |
| void | setSelection(const QString &selection) |
| void | setWordWrap(bool wrap, int wrapColWidth = 80) |
Signals
| void | parsingDone(bool cursorPositionWasSet) |
| void | parsingFailed() |
Detailed Description
\parIntroduction The TemplateParser transforms a message with a given template. A template contains text and commands, such as %QUOTE or %ODATE, which will be replaced with the real values in process().
\parBasics The message given in the templateparser constructor amsg, is the message that is being transformed. aorig_msg is the original message to which actions are performed. The message text in amsg will be replaced by the processed text of the template, but other properties, such as the attachments or the subject, are preserved.
There are two different kind of commands: Those that work on the message that is to be transformed and those that work on an 'original message'. Those that work on the message that is to be transformed have no special prefix, e.g. '%DATE'. Those that work on the original message have an 'O' prefix, for example '%ODATE'. This means that the %DATE command will take the date of the message passed in the constructor, the message which is to be transformed, whereas the %ODATE command will take the date of the message that is being passed in process(), the original message.
\parThe process() The process() function takes aorig_msg as parameter. This aorig_msg is the original message from which various commands in templates with prefix 'O' extract the data and adds to the processed message. This function finds the template and passes them to processWithTemplate(), where templates are processed and its value is added to the processed message.
\parReply To/Forward Plain Text Mails Plain Text mails are the mails with only text part and no html part. While creating reply/forward to mails, processWithTemplate() processes all the commands and then appends its values to plainBody and htmlBody. This function then on the basis of whether the user wants to use plain mails or HTML mails, clears the htmlBody, or just passes both the plainBody and htmlBody unaltered.
\parReply To/Forward HTML Mails By HTML mails here, we mean multipart/alternative mails. As mentioned above, all commands in the TemplateParser appends text, i.e. plain text to plainBody and html text to htmlBody in the function processWithTemplate(). This function also takes a decision of clearing the htmlBody on the basis of fact whether the user wants to reply/forward using plain mails or multipart/alternative mails.
\parWhen "TO" and when "NOT TO" make multipart/alternative Mails User is the master to decide when to and when not to make multipart/alternative mails. <b>For user who <u>don't prefer</u> using HTML mails</b> There is a TemplateParserSettings::self()->replyUsingHtml() (in GUI as Settings->Configure KMail-> Composer->General->"Reply using HTML if present"), which when not true (checkbox disabled in UI), will clear the htmlBody. An another option within the standard templates, %FORCEDPLAIN command raises the flag, ReplyAsPlain. This flag when raised in processWithTemplate() takes care that the processed message will contain text/plain part by clearing the htmlBody.
Once the htmlBody is cleared, plainBody and an empty htmlBody is passed to addProcessedBodyToMessage(). Here since the htmlBody is empty, text/plain messages are assembled and thus user is not dealing with any kind of HTML part.
<b>For user who <u>do prefer</u> using HTML mails</b> The setting discussed above as "Reply using HTML if present" (when checked to true), passes the htmlBody to addProcessedBodyToMessage() without doing any changes. An another option %FORCEDHTML within standard templates command raises the flag ReplyAsHtml. This flag when raised in processWithTemplate() takes care that the htmlBody is passed to addProcessedBodyToMessage() unaltered.
Since htmlBody received by addProcessedBodyToMessage() is not empty, multipart/alternative messages are assembled.
Note: Resolving conflict between TemplateParserSettings "replyUsingHtml" and FORCEDXXXX command. The conflict is resolved by simply giving preference to the commands over TemplateParserSettings.
\parMake plain part mMsg is the reply message in which the message text will be replaced by the processed value from templates.
In case of no attachments, the message will be a single-part message. A KMime::Content containing the plainBody from processWithTemplate() is created. Then the encodedBody(), contentType (text/plain) of this KMime::Content is set in the body and the header of mMsg.
\parMake multipart/alternative mails First of all a KMime::Content (content) is created with a content-type of multipart/alternative. Then in the same way as plain-part is created in above paragraph, a KMime::Content (sub-content) containing the plainBody is created and added as child to the content. Then a new KMime::Content (sub-content) with htmlBody as the body is created. The content-type is set as text/html. This new sub-content is then added to the parent content. Now, since the parent content (multipart/alternative) has two sub-content (text/plain and text/html) to it, it is added to the reply message (mMsg).
\todoWhat is the usecase of the commands that work on the message to be transformed? In general you only use the commands that work on the original message...
Member Function Documentation
[explicit] TemplateParserJob::TemplateParserJob(const std::shared_ptr<KMime::Message> &amsg, const TemplateParser::TemplateParserJob::Mode amode, QObject *parent = nullptr)
Constructor amsg KMime message amode parsing mode parent parent object
[override virtual noexcept] TemplateParserJob::~TemplateParserJob()
Destructor
[signal] void TemplateParserJob::parsingDone(bool cursorPositionWasSet)
Emitted when parsing is done cursorPositionWasSet whether cursor position was set
[signal] void TemplateParserJob::parsingFailed()
Emitted when parsing fails
void TemplateParserJob::process(const std::shared_ptr<KMime::Message> &aorig_msg, qint64 afolder = -1)
Processes the template with the original message aorig_msg original KMime message afolder folder ID (optional)
void TemplateParserJob::process(const QString &tmplName, const std::shared_ptr<KMime::Message> &aorig_msg, qint64 afolder = -1)
Processes the template by name tmplName template name aorig_msg original KMime message afolder folder ID (optional)
void TemplateParserJob::processWithIdentity(uint uoid, const std::shared_ptr<KMime::Message> &aorig_msg, qint64 afolder = -1)
Processes with specific identity uoid unique identity object ID aorig_msg original KMime message afolder folder ID (optional)
void TemplateParserJob::processWithTemplate(const QString &tmpl)
Processes with template text tmpl template text
void TemplateParserJob::setAllowDecryption(const bool allowDecryption)
Sets whether decryption is allowed allowDecryption whether to allow decryption
void TemplateParserJob::setIdentityManager(const KIdentityManagementCore::IdentityManager *ident)
Sets the identity manager ident identity manager
void TemplateParserJob::setReplyAsHtml(bool replyAsHtml)
Sets whether reply should be formatted as HTML replyAsHtml whether to use HTML format
void TemplateParserJob::setSelection(const QString &selection)
Sets the selection for template processing selection selected text
void TemplateParserJob::setWordWrap(bool wrap, int wrapColWidth = 80)
Sets word wrap settings wrap whether to wrap words wrapColWidth column width for wrapping