Class Inx_Api_Property_FormatChoicePropertyFormatter

Description

The Inx_Api_Property_FormatChoicePropertyFormatter is used for converting the mail format property to and from the internal string representation.

The Inx_Api_Property_FormatChoicePropertyFormatter is used for converting the mail format property to and from the internal string representation. For this property, there is no dedicated value holder like the Inx_Api_Property_ApprovalPropertyValue. Instead, the formatter itself contains all relevant data:

  • The formatting (choice) strategy: Defines how mailings shall be formatted.
  • The default format: Defines which format shall be used by default.
  • The attribute id: Defines the recipient attribute which shall be used to determine which format to use.
  • The patterns: Define which attribute value will trigger the use of a specific format.
The formatting (choice) strategy may be one of the following constants:

  • MAILING_FORMAT_STRATEGY: The editor may freely choose the mail format for each individual mailing. Used by formatMailingChoice().
  • FIXED_STRATEGY: Only one specific mail format may be used. Used by formatFixedChoice($sFormat).
  • ATTRIBUTE_STRATEGY: A recipient attribute is used to determine the mail format. Used by formatAttributeChoice($iAttributeId, $sDefaultFormat, $sPlainTextPattern, $sHtmlTextPattern, $sMultipartPattern).
The default format is used by the FIXED_STRATEGY and the ATTRIBUTE_STRATEGY. The possible formats are:

  • PLAIN_TEXT_FORMAT: Mailings will contain plain text only.
  • HTML_TEXT_FORMAT: Mailings will contain HTML text only.
  • MULTIPART_FORMAT: Mailings will contain both, plain and HTML text parts.

<strong>Note:</strong> When using the ATTRIBUTE_STRATEGY it is recommended to create multipart mailings only. However, it is still possible to create plain or HTML text mailings. Be aware that in such a case, all recipients will receive the mailing in the same format (which is plain or HTML text).

The attribute strategy requires an attribute id, a default mail format and attribute value patterns that determine which mail format to use. If the value of an attribute matches the pattern, the format associated to this pattern will be chosen. If the value matches none of the specified patterns, the default format will be used. The pattern of the default format is automatically set to null.

The patterns are <strong>not</strong> patterns in the ordinary sense. No operators or wildcards are allowed and the value is case sensitive and without quotes. Let's say we use the following patterns:

  • Plain text pattern: plain%
  • HTML text pattern: html
  • Multipart pattern (default): multipart
If the attribute value is equal to plain, the recipient will get a multipart mailing as the % wildcard is considered an ordinary character. If it is equal to html, the recipient gets the HTML flavour. However, if the attribute value is equal to HTML, the recipient will also get a multipart mailing, as the patterns are case sensitive. The multipart pattern may also be set to null as multipart is the default format and therefore the pattern is set to null anyway.

The following snippet shows how to retrieve and parse the mail format property of the specified list:

 $oListContext = $oSession->getListContextManager()->findByName("Desired list");
 $oProperty = $oListContext->findProperty(Inx_Api_Property_PropertyNames::MAIL_FORMAT_CHOICE);

 $oFormatChoicePropertyFormatter = Inx_Api_Property_FormatChoicePropertyFormatter::parse($oProperty);
 echo "Format strategy: ".$oFormatChoicePropertyFormatter->getChoiceStategy()."<br>";
 echo "Default format:  ".$oFormatChoicePropertyFormatter->getDefaultFormat()."<br>";
 echo "Attribute id:    ".$oFormatChoicePropertyFormatter->getAttributeId()."<br>";
 echo "HTML pattern:    ".$oFormatChoicePropertyFormatter->getPattern(
 	Inx_Api_Property_FormatChoicePropertyFormatter::HTML_TEXT_FORMAT)."<br>";

To give the editor free choice to use any mail format she or he considers appropriate, use the formatMailingChoice() method. The following snippet shows how this can be achieved:

 $oListContext = $oSession->getListContextManager()->findByName( "Desired list" );
 $oProperty = $oListContext->findProperty( Inx_Api_Property_PropertyNames::MAIL_FORMAT_CHOICE );

 $oProperty->updateInternalValue( Inx_Api_Property_FormatChoicePropertyFormatter::formatMailingChoice() );
 $oProperty->commitUpdate();

The opposite strategy is to restrict all mailings of a list to a certain mail format. The following snippet shows how to restrict the mailing format of the specified list to the multipart format:

 $oListContext = $oSession->getListContextManager()->findByName( "Desired list" );
 $oProperty = $oListContext->findProperty( Inx_Api_Property_PropertyNames::MAIL_FORMAT_CHOICE );

 $oProperty->updateInternalValue( Inx_Api_Property_FormatChoicePropertyFormatter::formatFixedChoice(
 	Inx_Api_Property_FormatChoicePropertyFormatter::MULTIPART_FORMAT ) );
 $oProperty->commitUpdate();

The final strategy is to choose the mailing format based on the value of a recipient attribute. The following snippet shows how to send HTML mailings to recipients with the attribute value html, plain text mailings to recipients with the attribute value plain and multipart mailings to all other recipients:

 $oListContext = $oSession->getListContextManager()->findByName( "Desired list" );
 $oRecipientMetaData = $oSession->createRecipientContext()->getMetaData();
 $oProperty = $oListContext->findProperty( Inx_Api_Property_PropertyNames::MAIL_FORMAT_CHOICE );

 $iAttributeId = $oRecipientMetaData->getUserAttribute( "format" )->getId();
 $sPlainTextPattern = "plain";
 $sHtmlTextPattern = "html";

 $sStrategy = Inx_Api_Property_FormatChoicePropertyFormatter::formatAttributeChoice( $iAttributeId,
 		Inx_Api_Property_FormatChoicePropertyFormatter::MULTIPART_FORMAT, $sPlainTextPattern, $sHtmlTextPattern, null );
 $oProperty->updateInternalValue( $sStrategy );
 $oProperty->commitUpdate();

For more information on properties in general, see the Inx_Api_Property_Property documentation.

  • version: $Revision: 9497 $ $Date: 2007-12-19 17:03:25 +0200 (Tr, 19 Grd 2007) $ $Author: aurimas $
  • see: Inx_Api_Property_Property

Located in /Api/Property/FormatChoicePropertyFormatter.php (line 128)


	
			
Class Constant Summary
 HTML_TEXT_FORMAT = "text/html"
 MULTIPART_FORMAT = "multipart"
 PLAIN_TEXT_FORMAT = "text/plain"
 PREFIX = "EmailFormat["
 SUFFIX = "]"
Variable Summary
Method Summary
static string formatAttributeChoice (int $iAttributeId, string $sDefaultFormat, string $sPlainTextPattern, string $sHtmlTextPattern, string $sMultipartPattern)
static string formatFixedChoice (string $sFormat)
static string formatMailingChoice ()
Inx_Api_Property_FormatChoicePropertyFormatter __construct ()
string getDefaultFormat ()
string getPattern (string $sFormat)
Variables
int $iAttributeId (line 191)

The attribute that controls which format to choose.

The attribute that controls which format to choose.

  • access: protected
int $iChoiceStategy (line 184)

The strategy used to choose the mailing format.

The strategy used to choose the mailing format.

  • access: protected
string $sFormat (line 219)

The default mailing format.

The default mailing format.

  • access: protected
string $sHtmlTextPattern (line 205)

The HTML text pattern.

The HTML text pattern.

  • access: protected
string $sMultipartPattern (line 212)

The multipart pattern.

The multipart pattern.

  • access: protected
string $sPlainTextPattern (line 198)

The plain text pattern.

The plain text pattern.

  • access: protected
Methods
static method formatAttributeChoice (line 417)

Creates the internal string value for the ATTRIBUTE_STRATEGY using the given recipient attribute id, default mailing format and patterns.

Creates the internal string value for the ATTRIBUTE_STRATEGY using the given recipient attribute id, default mailing format and patterns. For a description of the pattern syntax, see the documentation of this class. The default mailing attribute may be one of:

  • PLAIN_TEXT_FORMAT
  • HTML_TEXT_FORMAT
  • MULTIPART_FORMAT

  • return: the internal string value for the ATTRIBUTE_STRATEGY.
  • access: public
static string formatAttributeChoice (int $iAttributeId, string $sDefaultFormat, string $sPlainTextPattern, string $sHtmlTextPattern, string $sMultipartPattern)
  • int $iAttributeId: the id of the recipient attribute used to determine the mailing format.
  • string $sDefaultFormat: the default mailing format.
  • string $sPlainTextPattern: the plain text pattern. May be null if this is the default format.
  • string $sHtmlTextPattern: the HTML text pattern. May be null if this is the default format.
  • string $sMultipartPattern: the multipart text pattern. May be null if this is the default format.
static method formatFixedChoice (line 393)

Creates the internal string value for the FIXED_STRATEGY using the given default mailing format.

Creates the internal string value for the FIXED_STRATEGY using the given default mailing format. The default format may be one of:

  • PLAIN_TEXT_FORMAT
  • HTML_TEXT_FORMAT
  • MULTIPART_FORMAT

  • return: the internal string value for the FIXED_STRATEGY.
  • access: public
static string formatFixedChoice (string $sFormat)
  • string $sFormat: the default mailing format.
static method formatMailingChoice (line 376)

Creates the internal string value for the MAILING_FORMAT_STRATEGY.

Creates the internal string value for the MAILING_FORMAT_STRATEGY.

  • return: the internal string value for the MAILING_FORMAT_STRATEGY.
  • access: public
static string formatMailingChoice ()
static method parse (line 241)

Parses the given property and extracts the format choice policy into a new Inx_Api_Property_FormatChoicePropertyFormatter for easy retrieval.

Parses the given property and extracts the format choice policy into a new Inx_Api_Property_FormatChoicePropertyFormatter for easy retrieval. Only the Inx_Api_Property_PropertyNames::MAIL_FORMAT_CHOICE property is allowed. Using any other property will trigger an Inx_Api_IllegalArgumentException.

  • return: an Inx_Api_Property_FormatChoicePropertyFormatter which can be used for easy retrieval of the property values.
  • throws: Inx_Api_IllegalArgumentException if the given property is not an Inx_Api_Property_PropertyNames::MAIL_FORMAT_CHOICE property.
  • access: public
  • property $oProperty: the property to parse.
Constructor __construct (line 225)

Default constructor which may only be used by derived classes.

Default constructor which may only be used by derived classes.

  • access: protected
Inx_Api_Property_FormatChoicePropertyFormatter __construct ()
getAttributeId (line 331)

Returns the id of the recipient attribute used to determine the mailing format.

Returns the id of the recipient attribute used to determine the mailing format. If the choice strategy is not ATTRIBUTE_STRATEGY, 0 will be returned.

  • return: the id of the recipient attribute used to determine the mailing format, or 0 if none is needed.
  • access: public
int getAttributeId ()
getChoiceStategy (line 320)

Returns the formatting (choice) strategy.

Returns the formatting (choice) strategy. May be one of:

  • MAILING_FORMAT_STRATEGY
  • FIXED_STRATEGY
  • ATTRIBUTE_STRATEGY

  • return: the formatting (choice) strategy.
  • access: public
int getChoiceStategy ()
getDefaultFormat (line 366)

Returns the default mailing format.

Returns the default mailing format. The default format is only used by the choice strategies FIXED_STRATEGY and ATTRIBUTE_STRATEGY.

  • return: the default mailing format, if any, null otherwise.
  • access: public
string getDefaultFormat ()
getPattern (line 348)

Returns the pattern for the given mailing format.

Returns the pattern for the given mailing format. Patterns are only used by the choice strategy ATTRIBUTE_STRATEGY.

  • return: the pattern for the given format, if any, null otherwise.
  • access: public
string getPattern (string $sFormat)
  • string $sFormat: the mailing format for which the pattern shall be returned. May be one of:
    • PLAIN_TEXT_FORMAT
    • HTML_TEXT_FORMAT
    • MULTIPART_FORMAT
Class Constants
ATTRIBUTE_STRATEGY = 2 (line 154)

Strategy constant which is used to determine the mail format based on the value of a recipient attribute.

Strategy constant which is used to determine the mail format based on the value of a recipient attribute.

FIXED_STRATEGY = 1 (line 147)

Strategy constant which restricts the mail format to exactly one specified format.

Strategy constant which restricts the mail format to exactly one specified format.

HTML_TEXT_FORMAT = "text/html" (line 169)

Constant for the HTML text pattern.

Constant for the HTML text pattern.

MAILING_FORMAT_STRATEGY = 0 (line 140)

Strategy constant which lets the editor freely choose the appropriate mail format.

Strategy constant which lets the editor freely choose the appropriate mail format.

MULTIPART_FORMAT = "multipart" (line 176)

Constant for the multipart pattern.

Constant for the multipart pattern.

PLAIN_TEXT_FORMAT = "text/plain" (line 162)

Constant for the plain text pattern.

Constant for the plain text pattern.

PREFIX = "EmailFormat[" (line 130)
SUFFIX = "]" (line 132)

Documentation generated on Thu, 17 Sep 2015 14:27:24 +0200 by phpDocumentor 1.3.2