h4. Examples

h5. Example 1: Text input box

bc(language-markup). <txp:com_connect_text label="Your name" />

h5. Example 2: Range slider

bc(language-markup). <txp:com_connect_text type="range" label="UK shoe size" min="1" max="15" />

h5. Example 3: Telephone input with validation

Create a telephone field with a "validation pattern for UK telephone number":http://html5pattern.com/Phones format:

bc(language-markup). <txp:com_connect_text type="tel" label="Telephone" pattern="^\s*(?(020[7,8]{1})?[ ]?[1-9]{1}[0-9{2}[ ]?[0-9]{4})|(0[1-8]{1}[0-9]{3})?[ ]?[1-9]{1}[0-9]{2}[ ]?[0-9]{3})\s*$" required="1" />

h3(#cc_email). com_connect_email tag

bc(language-markup). <txp:com_connect_email />

@@ field for user's email address.

The entered email address will automatically be validated to make sure it is of the form "abc@xxx.yyy[.zzz]". On non-Windows servers, a test will be done to verify that an A or MX record exists for the domain. Neither test prevents spam, but it does help detect accidental typing errors.

h4. Attributes

; @autocomplete="value"@ : Indicates whether the value of the control can be automatically completed by the browser. Possible values are: @off@ (the browser does not automatically complete the entry) or @on@ (the browser can automatically complete the value based on values that the user has entered during previous uses). Default is unset. ; @break="tag"@ : Break tag between the @@ and @@ field. Default is @
@. Use @break=""@ to put the label and input field on the same line. ; @class="space-separated values"@ : Set the CSS @class@ name of the tag. Default: @comEmail@. To remove @class@ attribute from the element entirely, use @class=""@. ; @default="value"@ : Default value when no input is provided. ; @html_form="id"@ : The HTML @id@ of the @@ tag to which the field is attached. Associated with the contained form by default. ; @label="text"@ : Text label displayed to the user. Default is @Email@. ; @label_position="text"@ : Position of the label in relation to the @@ field. Available values: @before@ or @after@. Default is @before@. ; @max="integer"@ : Maximum input value length in characters, using the HTML5 @maxlength@ attribute. Default is @100@. To remove @maxlength@ attribute from the element entirely (not recommended), use @max=""@. ; @min="integer"@ : Minimum input value length in characters, using the HTML5 @minlength@ attribute. Default is unset, i.e., no minimum limit. ; @name="value"@ : Field name, as used in the HTML @@ tag. ; @placeholder="text"@ : Text to show as a guide, when the @@ field is empty. ; @required="boolean"@ : Whether this field must be filled out. Available values: @1@ (yes) or @0@ (no). Default is whatever is set in the @txp:com_connect@ tag's @required@ attribute - if neither attribute is set then default is @1@. ; @send_article="boolean"@ : Whether this field is used as the recipient email address when using the send_article function. Available values: @1@ (yes) or @0@ (no). Default is @0@. ; @size="value"@ : The size, in characters, of the @@ field.

h4. Examples

h5. Example 1: Standard email field

bc(language-markup). <txp:com_connect_email label="Your email address" />

h3(#cc_textarea). com_connect_textarea tag

bc(language-markup). <txp:com_connect_textarea />

Creates a @@.

h4. Attributes

; @autocomplete="value"@ : Indicates whether the value of the control can be automatically completed by the browser. Possible values are: @off@ (the browser does not automatically complete the entry) or @on@ (the browser can automatically complete the value based on values that the user has entered during previous uses). Default is unset. ; @break="tag"@ : Break tag between the @@ and @@. Default is @<br />@. Use @break=""@ to put the @<label>@ and @<input>@ field on the same line. ; @class="space-separated values"@ : Set the CSS @class@ name of the @<textarea>@. Default: @comTextarea@. To remove @class@ attribute from the element entirely, use @class=""@. ; @cols="integer"@<br/>Number of columns, in characters, of the @<textarea>@. Default is @58@. ; @default="value"@ : Default value when no input is provided. ; @html_form="id"@ : The HTML @id@ of the @<form>@ tag to which the @<textarea>@ is attached. Associated with the contained form by default. ; @label="text"@ : Text label displayed to the user. Default is @Message@. ; @label_position="text"@ : Position of the label in relation to the @<textarea>@ field. Available values: @before@ or @after@. Default is @before@. ; @max="integer"@ : Maximum input value length in characters, using the HTML5 @maxlength@ attribute. Default is @10000@. To remove @maxlength@ attribute from the element entirely (not recommended), use @max=""@. ; @min="integer"@ : Minimum input value length in characters, using the HTML5 @minlength@ attribute. Default is unset, i.e., no minimum limit. ; @name="value"@ : Field name, as used in the HTML @<input>@ tag. ; @placeholder="text"@ : Text to show as a guide to users, when the @<textarea>@ is empty. ; @required="boolean"@ : Whether this field must be filled out. Available values: @1@ (yes) or @0@ (no). Default is whatever is set in the @txp:com_connect@ tag's @required@ attribute - if neither attribute is set then default is @1@. ; @rows="integer"@ : Number of rows, in characters, of the @@. Default is @8@. ; @wrap="value"@ : Governs word-wrap. Available values: @hard@ or @soft@. If this attribute is not specified, @soft@ is its default value.

h4. Examples

h5. Example 1: Standard textarea

Create a text area that is 40 characters wide, 10 lines high, with a customised label:

bc(language-markup). <txp:com_connect_textarea cols="40" rows="10" label="Your question" />

h3(#cc_submit). com_connect_submit tag

bc(language-markup). <txp:com_connect_submit />

Creates a submit button. When used as a container tag, a @@ element will be used instead of an @@ element.

h4. Attributes:

; @class="space-separated values"@ : Set the CSS @class@ name of the tag. Default: @comSubmit@. To remove @class@ attribute from the element entirely, use @class=""@. ; @html_form="id"@ : The HTML @id@ of the @@ tag to which the button is attached. Associated with the contained form by default. ; @label="text"@ : Text shown on the submit button. Default is @Send@.

h4. Examples

h5. Example 1: Standard submit button

bc(language-markup). <txp:com_connect_submit />

h5. Example 2: Submit button with custom text

bc(language-markup). <txp:com_connect_submit label="To the moooon" />

h5. Example 3: Usage as a container tag

This allows you to use Textpattern tags and HTML markup in the submit button:

bc(language-markup). txp:com_connect_submitSend question</txp:com_connect_submit>

h5. Example 4: Image button

As example 3 above, but using an image as the button:

bc(language-markup). txp:com_connect_submit </txp:com_connect_submit>

h3(#cc_select). com_connect_select tag

bc(language-markup). <txp:com_connect_select />

Container tag that creates a drop-down selection @@ list, or scrolled @@ list box (by utilising the @size@ attribute).

h4. Attributes

; @break="tag"@ : Break tag between the label and @@ field. Default is @@. Use @break=""@ to put the label and input field on the same line. ; @class="space-separated values"@ : Set the CSS @class@ name of the list. Default: @comSelect@. To remove @class@ attribute from the element entirely, use @class=""@. ; @delimiter="character"@ : Separator character between list items if using the @options@ attribute. Default is @,@ (comma). Ignored if this tag is used as a container. ; @label="text"@ : Text label displayed to the user. Default is @Option@. ; @label_position="text"@ : Position of the label in relation to the @@ field. Available values: @before@ or @after@. Default is @before@. ; @html_form="id"@ : The HTML @id@ of the @@ tag to which the @@ is attached. Associated with the contained form by default. ; @multiple="boolean"@ : Whether to allow multiple selections to be made from the set of options. Default: unset. ; @name="value"@ : Field name, as used in the HTML @@ tag. ; @options="comma-separated values"@ : List of items (previously @list@) to show in the select box. Surround the first entry with @{Braces}@ to indicate it is an 'empty' placeholder. Alternatively, the @<txp:com_connect_option />@ tag may be used inside this tag's container. ; @required="boolean"@ : Whether this field must be filled out. Available values: @1@ (yes) or @0@ (no). Default is whatever is set in the @txp:com_connect@ tag's @required@ attribute - if neither attribute is set then default is @1@. ; @selected="value"@ : List item that is selected by default. ; @size="value"@ : If the @@ is to be presented as a scrolled list box, this attribute represents the number of rows in the list that should be visible at one time. Default is unset (i.e. a drop-down selection @@ list).

h4. Examples

h5. Example 1: Single drop-down select list

A list labeled 'Department', containing three options and a blank option shown by default and labelled with 'Choose dept', forcing the user to make a selection.

bc(language-markup). <txp:com_connect_select label="Department" options="{Choose dept},Marketing,Sales,Support" />

h5. Example 2: Using the com_connect option tag

Same as the above example, but with 'Sales' selected by default.

bc(language-markup). <txp:com_connect_select label="Department" selected="Sales"> <txp:com_connect_option label="{Choose dept}" /> <txp:com_connect_option label="Marketing" /> <txp:com_connect_option label="Sales" /> <txp:com_connect_option label="Support" /> </txp:com_connect_select>

The advantage to use the option tag is that you can name the options independently of the label. You could also add a boolean @selected@ attribute to the individual option tag, instead of to the containing select tag.

h5. Example 3: Multiple select

bc(language-markup). <txp:com_connect_select label="Ice cream flavours" multiple> <txp:com_connect_option label="{Choose your favourites}" /> <txp:com_connect_option label="Vanilla" /> <txp:com_connect_option label="Strawberry" /> <txp:com_connect_option label="Raspberry" /> <txp:com_connect_option label="Chocolate" /> <txp:com_connect_option label="Mint choc-chip" name="mint-with-chocolate-chips" /> </txp:com_connect_select>

h3(#cc_option). com_connect_option tag

bc(language-markup). <txp:com_connect_option />

Creates a drop-down selection option. May be used as a single (self-closing) or container tag. Also see @com_connect_select@ tag above.

h4. Attributes

; @class="space-separated values"@ : Set the CSS @class@ name of the option. Default: @comOption@. To remove @class@ attribute from the element entirely, use @class=""@. ; @label="text"@ %(warning)required% : Text label of this option displayed to the user. Surround the label with {braces} to indicate it is an empty placeholder at the start of the list. Note if you use this braces syntax, the value will be forced to @value=""@, i.e. any supplied value will be ignored. ; @selected="boolean"@ : Whether this item is selected, May also be specified in the container tag's @selected@ attribute. Available values: @1@ (yes) or @0@ (no). ; @value="text"@ : The value associated with this option when submitted. Default is the label.

h5. Example 1: Drop-down select list containing three options

bc(language-markup). <txp:com_connect_select label="Department"> <txp:com_connect_option label="Marketing" /> <txp:com_connect_option label="Sales" /> <txp:com_connect_option label="Support" /> </txp:com_connect_select>

h5. Example 2: Pass different values instead of label

'Sales' is selected by default.

bc(language-markup). <txp:com_connect_select label="Department"> <txp:com_connect_option value="contact-marketing">Marketing</txp:com_connect_option> <txp:com_connect_option value="contact-sales" selected>Sales</txp:com_connect_option> <txp:com_connect_option value="contact-support">Support</txp:com_connect_option> </txp:com_connect_select>

h3(#cc_checkbox). com_connect_checkbox tag

bc(language-markup). <txp:com_connect_checkbox />

Creates a checkbox.

h4. Attributes

; @break="tag"@ : Break tag between the checkbox button and label. Default is one space. Use @break="br"@ to put the checkbox and label on separate lines. ; @checked="boolean"@ : Whether this box is checked when first displayed. Available values: @1@ (yes) or @0@ (no). Default is @0@. ; @class="space-separated values"@ : Set the CSS @class@ name of the option. Default: @comCheckbox@. To remove @class@ attribute from the element entirely, use @class=""@. ; @html_form="id"@ : The HTML @id@ of the @@ tag to which the checkbox is attached. Associated with the contained form by default. ; @label="text"@ : Text label displayed to the user. Default is @Checkbox@. ; @label_position="text"@ : Position of the label in relation to the @@ field. Available values: @before@ or @after@. Default is @after@. ; @name="value"@ : Field name, as used in the HTML @@ tag. ; @required="boolean"@ : Whether this checkbox must be filled out. Available values: @1@ (yes) or @0@ (no). Default is whatever is set in the @txp:com_connect@ tag's @required@ attribute - if neither attribute is set then default is @1@. ; @value="text"@ : Value to send in the email if the option is checked. Uses yes/no if not set.

h4. Examples

h5. Example 1: Accept terms of service

Shrink-wrap agreement which must be checked by the user before the email will be sent.

bc(language-markup). <txp:com_connect_checkbox label="I accept the terms and conditions" />

h5. Example 2: Optional checkboxes

bc(language-markup). With which operating systems are you familiar?
<txp:com_connect_checkbox label="Windows" required="0" />
<txp:com_connect_checkbox label="Unix/Linux/BSD" required="0" />
<txp:com_connect_checkbox label="macOS" required="0" />

h3(#cc_radio). com_connect_radio tag

bc(language-markup). <txp:com_connect_radio />

Creates a radio button.

h4. Attributes

; @break="tag"@ : Break tag between the radio button and label. Default is one space. Use @break="br"@ to put the radio button and label on separate lines. ; @checked="boolean"@ : Whether this radio option is checked when the form is first displayed. Available values: @1@ (yes) or @0@ (no). Default is @0@. ; @class="space-separated values"@ : Set the CSS @class@ name of the radio button. Default: @comRadio@. To remove @class@ attribute from the element entirely, use @class=""@. ; @group="text"@ %(warning)required% : Text used in the email to describe this group of radio buttons. This attribute value is remembered for subsequent radio buttons, so you only have to set it on the first radio button of a group. Default is @Radio@. ; @html_form="id"@ : The HTML @id@ of the @@ tag to which the radio button is attached. Associated with the contained form by default. ; @label="text"@ %(warning)required% : Text label displayed to the user as radio button option. ; @name="value"@ %(warning)recommended% : Field name, as used in the HTML @@ tag. This attribute value is remembered for subsequent radio buttons, so you only have to set it on the first radio button of a group. If it hasn't been set at all, it will be derived from the @group@ attribute. ; @required="boolean"@ : Whether this radio set must be filled out. Available values: @1@ (yes) or @0@ (no). Default is whatever is set in the @txp:com_connect@ tag's @required@ attribute - if neither attribute is set then default is @1@. You should set the @required@ attribute on only the first radio button of the group, or set the same identical attribute value on all radio buttons in the group. ; @value="text"@ : Value to send in the email if the option is checked. Uses label if not set.

h4. Examples

h5. Example 1: Radio set

Group mutually exclusive radio buttons by setting the @group@ attribute on the first radio button in a group. Only the chosen radio button from each group will be used in the email message. The message will be output in the form @group: label@ for each of the chosen radio buttons.

bc(language-markup). <txp:com_connect_radio label="Medium" group="I like my steak" /> <txp:com_connect_radio label="Rare" /> <txp:com_connect_radio label="Well done" /> <txp:com_connect_radio label="Wine" group="With a glass of" /> <txp:com_connect_radio label="Beer" /> <txp:com_connect_radio label="Water" />

h3(#cc_secret). com_connect_secret tag

bc(language-markup). <txp:com_connect_secret />

This tag has no effect on the form or HTML output, but will include additional information in the email. It can be used as a single (self-closing) tag or as a container tag.

h4. Attributes

; @label="text"@ : Used to identify the field in the email. Default is @Secret@. ; @name="text"@ : Used internally. Set this only if you have multiple 'secret' form elements with identical labels. ; @value="value"@ : Some text you want to add to the email.

h4. Examples

h5. Example 1: As a single (self-closing) tag

bc(language-markup). <txp:com_connect_secret value="The answer is 42" />

h5. Example 2: As a container tag

bc(language-markup). <txp:com_connect_secret label="Dear user"> Please provide a useful example for this tag! </txp:com_connect_secret>

h3(#cc_serverinfo). com_connect_serverinfo tag

bc(language-markup). <txp:com_connect_serverinfo />

This tag has no effect on the form or HTML output, but will include additional information in the email based on the PHP @$_SERVER@ variable.

h4. Attributes

; @label="text"@ : Used to identify the field in the email. Defaults to the value of the @name@ attribute. ; @name="value"@ %(warning)required% : Name of the server variable. See the "PHP manual":https://php.net/manual/reserved.variables.php#reserved.variables.server for a full list.

h4. Examples

h5. Example 1: Add the IP address of the visitor to the email

bc(language-markup). <txp:com_connect_serverinfo name="REMOTE_ADDR" label="IP number" />

h5. Example 2: Add the name of the visitor's browser to the email

bc(language-markup). <txp:com_connect_serverinfo name="HTTP_USER_AGENT" label="Browser" />

h3(#cc_send_article). com_connect_send_article tag

bc(language-markup). <txp:com_connect_send_article />

Use this tag in your individual article form, where you want the "send article" link to be displayed.

h4. Attributes

; @linktext="text"@ : Text displayed for the link. Default is @send article@.

h4. Examples

h5. Example 1: On an article form

bc(language-markup). <txp:com_connect_send_article linktext="Send this article" />

h3(#cc_fields). com_connect_fields tag

bc(language-markup). <txp:com_connect_fields />

Iterate over the set of submitted fields. Only really of use in the designated @body_form@ to format the user-supplied content in the email body.

h4. Attributes

; @break="text or tag"@ : Break tag or text to use as a separator between each item. Default is @, @. Use @break=""@ to remove the effect of this attribute. ; @class="space-separated values"@ : Set the CSS @class@ name of the wraptag. Default: unset. ; @label="text"@ : Comma-separated list of field labels to iterate over. ; @name="text"@ : Comma-separated list of field names to iterate over. ; @wraptag="tag"@ : HTML tag (without angle brackets) to wrap the set of fields. Default: unset.

Note that @label@ and @name@ may be used individually or in tandem. If both are omitted, the entire set of fields are iterated.

h4. Examples

h5. Example 1: Create an unordered list of submitted fields

bc(language-markup). <txp:com_connect_fields wraptag="ul" break="li"> <txp:com_connect_label /> = <txp:com_connect_value /> </txp:com_connect_fields>

h3(#cc_mime). com_connect_mime tag

bc(language-markup). <txp:com_connect_mime />

Use this in the body_form to delineate sections of the message for use in plaintext email clients and/or html-capable email clients.

h4. Attributes

; @type="value"@ : The type of content that follows the tag. Choose from @text@ (plaintext), @html@, or @end@ (to signify the end of the blocks).

h4. Examples

h5. Example 1: Plaintext and HTML body content

bc(language-markup). <txp:com_connect_mime type="text" /> <txp:com_connect_fields break=""> <txp:com_connect_label />: <txp:com_connect_value /> </txp:com_connect_fields> <txp:com_connect_mime type="html" /> <txp:com_connect_fields wraptag="ul" break="li"> <txp:com_connect_label /> = <txp:com_connect_value /> </txp:com_connect_fields> <txp:com_connect_mime type="end" />

Note that there are three uses of the new txp:com_connect_mime tag:

• One to signify the start of the plaintext content (@type="text"@).
• One to signify the start of the html content (@type="html"@).
• One to signify the end of all the content (@type="end"@).

Whether you use one or both of the text/html types, you require the 'end' or you’ll just get garbage messages.

h3(#cc_label). com_connect_label tag

bc(language-markup). <txp:com_connect_label />

Return the label for the given attribute name.

h4. Attributes

; @name="text"@ : The name of the field for which you wish to retrieve the label. If used within a @txp:com_connect_fields@ container, the @name@ is optional and will return the current field in the set.

h3(#cc_value). com_connect_value tag

bc(language-markup). <txp:com_connect_value />

Return the value of the given attribute, by name or its label.

h4. Attributes

; @break="text or tag"@ : Break tag or text to use as a separator between each item, if the value is a multiple (e.g. a multi-select option list). Default is @, @. Use @break=""@ to remove the effect of this attribute. ; @class="space-separated values"@ : Set the CSS @class@ name of the wraptag. Default: unset. ; @label="text"@ : The label of the field for which you wish to retrieve the value. ; @name="text"@ : The name of the field for which you wish to retrieve the value. ; @wraptag="tag"@ : HTML tag (without angle brackets) to wrap the field. Default: unset.

If used within a @txp:com_connect_fields@ container, the @name@ and @label@ are optional and the tag will use the current field in the set.

h3(#cc_if). com_connect_if tag

bc(language-markup). <txp:com_connect_if />

Conditional tag for checking variable conditions, either by name or label.

h4. Attributes

; @label="text"@ : The label of the field you wish to check. ; @name="text"@ : The name of the field you wish to check. ; @value="text"@ : The value against which to test the given field. Leave blank to just test if there is any value assigned to the field.

If used within a @txp:com_connect_fields@ container, the @name@ and @label@ are optional and the tag will test the current field in the set.

h4. Examples

h5. Example 1: Take action if the visitor has entered a particular value

bc(language-markup). <txp:com_connect_if name="delivery" value="courier"> <txp:com_connect_label name="delivery" />: <txp:com_connect_value name="delivery" /> </txp:com_connect_if>.

h2(#advanced). Advanced examples

h3(#advanced1). Separate input and error forms

Using @show_input@ and @show_error@ to display the form and error messages on different parts of a page. A form is used to make sure the contents of both forms are identical, otherwise they would be seen as two independent forms. The first form only shows errors (no input), the second form only shows the input fields (no errors).

bc(language-markup).

<txp:com_connect form="contact_form" show_input="0" />

Apart from the @show_error@ and @show_input@ attributes, all other attributes must be 100% identical in both forms, otherwise they would be seen as two unrelated forms.

h3(#advanced2). User selectable subject field

Specify the @subject_form@ attribute and create a form which includes a @com_connect_select@ tag:

bc(language-markup). <txp:com_connect to="you@example.com" subject_form="my_subject_form" /> <txp:com_connect_text label="Name" />
<txp:com_connect_email />
<txp:com_connect_select label="Choose Subject" options=",Question,Feedback" />
<txp:com_connect_textarea label="Message" />
</txp:com_connect>

Create a Textpattern form called "my_subject_form", containing:

bc(language-markup). txp:php global $com_connect_form; echo$com_connect_form['Choose Subject']; </txp:php>

The @label@ used in the @com_connect_select@ tag must be identical to the corresponding variable in the @subject_form@. Here we used @Choose subject@.

If you'd prefer to add a common prefix for all subjects, use a @subject_form@ containing:

bc(language-markup). txp:php global $com_connect_form; echo 'My common prefix - ' .$com_connect_form['Choose Subject']; </txp:php>

h3(#advanced3). User selectable recipient, without showing email address

Specify the @to_form@ attribute and create a form which includes a @com_connect_select@ tag:

bc(language-markup). <txp:com_connect to_form="my_com_connect_to_form"> <txp:com_connect_text label="Name" />
<txp:com_connect_email />
<txp:com_connect_select label="Department" options=",Support,Sales" />
<txp:com_connect_textarea label="Message" />
</txp:com_connect>

Create a Textpattern form called "my_com_connect_to_form", containing:

bc(language-markup). txp:php global $com_connect_form; switch($com_connect_form['Department'][0]) { case 'Support': echo 'crew@example.com'; break; case 'Sales': echo 'showmethemoney@example.com'; break; default: echo 'someone@example.com'; } </txp:php>

The @label@ used in the @com_connect_select@ tag must be identical to the corresponding variable in the @to_form@. Here we used @Department@.

A 'default' email address in the @to_form@ is specified to ensure that a valid email address is used in cases where you add or change a select/radio option and forget to update the @to_form@.

p(alert-block warning). Warning: Never use tags like @com_connect_text@, @com_connect_email@ or @com_connect_textarea@ for setting the recipient address, otherwise your form can be abused to send spam to any email address!

h2(#styling). Styling

The form itself has a default @class@ of @comConnectForm@ set on the @@ HTML tag.

If a @thanks_form@ template is used, the wrapper around that template has a default @class@ of @comThanks@.

The list of error messages (if any) has a default @class@ of @comError@ set on the @ul@ HTML tag that encloses the list of errors. This class name may be overridden using the @classes@ attribute of the @com_connect@ tag.

All form elements and corresponding labels have the following classes (or ids) set by default:

One of @comText@, @comEmail@, @comTextarea@, @comSelect@, @comOption@, @comRadio@, @comCheckbox@ or @comSubmit@. By default, it should be obvious which @class@ is used for which form element (and corresponding label). You can override these names by using your own @class@ attribute.

@comRequired@ and/or @errorElement@, depending on whether the form element is required, an error was found in whatever the visitor entered, or both. Override these using the @classes@ attribute in the @com_connect@ tag.

An individual @id@ or @class@ set to the value of the @name@ attribute of the corresponding tag. When styling forms based on this @class@, you should explicitly set the @name@ attribute because automatically generated names may change in newer com_connect versions.

h2(#api). com_connect's API

The plugin API of com_connect, originally developed by Tranquillo, allows other plugins to interact with contact forms. This permits extra functionality such as combatting comment spam, HTML email, newsletter delivery and so forth to be bolted onto the base plugin.

Four callback events exist in com_connect:

• @comconnect.submit@ is called after the form is submitted and the values are checked if empty or valid email addresses, but before the mail is sent.
• @comconnect.form@ lets you inject content (fields) in the contact form as displayed to the visitor.
• @comconnect.render@ lets you inject or alter markup of the entire @@. Useful for editing things like @enctype@ (e.g. for file attachment modules that link into this plugin).
• @comconnect.deliver@ is called immediately prior to delivery and advertises the intended payload so you may manipulate it. For example, you could do something as simple as adding CC: or BCC: fields. Or change the MIME type header to @text/html@ and add some HTML content based on the given body data, then let com_connect handle the mailing. Or you could intercept the entire mail process, handle mailing yourself with a third party system, and tell com_connect to skip its internal mailing process.

For reference here are the commands that will be interesting to plugin developers:

bc(language-php).. // This will call your function before the form is submitted so you can analyse the submitted data register_callback('abc_myfunction', 'comconnect.submit');

// This will call your function and add the output (use @return $mystuff;@) to the contact-form. register_callback('abc_myotherfunction2', 'comconnect.form');

// To get hold of the form-variables you can use global com_connect_form; // With the following two lines you can tell com_connect if your plugin found spam. $evaluator =& get_comconnect_evaluator();

// The passed value must be non-zero to mark the content as spam. // Value must be a number between 0 and 1. $evaluator -> add_comconnect_status(1);

p. Multiple plugins can be active at the same time and each of them can mark the submitted content as spam and prevent the form from being submitted.

h4. Examples

bc(language-php).. register_callback('pap_comconnect_form','comconnect.form'); register_callback('pap_comconnect_submit','comconnect.submit');

function pap_comconnect_form() { $field = '<div style="display:none">'. finput('text','phone',ps('phone'),'','','','','','phone').'<br />'. finput('text','mail',ps('mail'),'','','','','','mail').'</div>'; return$field; }

function pap_comconnect_submit() { $checking_mail_field = trim(ps('mail'));$checking_phone_field = trim(ps('phone')); $evaluation =& get_comconnect_evaluator();

// If the hidden fields are filled out, the contact form won't be submitted!
if ($checking_mail_field != '' or $checking_phone_field != '') {
    $evaluation -> add_comconnect_status(1);
}

return;

}

p. For the delivery callback, you signal back to the plugin your intentions so that com_connect knows what to do after your delivery plugin has executed. Return the following strings:

• @comconnect.send@ (or no return value) to allow com_connect to continue mailing the content.
• @comconnect.skip@ to skip com_connect's mailing (i.e., the third party handles the mail process) and return 'success' to the visitor.
• @comconnect.fail@ to skip com_connect's mailing and return 'fail' to the visitor.

Or simply @exit@ your plugin to halt the entire operation so no com_connect feedback is given.

h2(#faq). Frequently asked questions

h5. How do I remove the legend and fieldset surrounding the contact form?

Set the @label@ attribute to an empty value (@label=""@) in the @com_connect@ tag.

h5. No email is sent. How do I diagnose and fix the problem?

First try a simple contact form, using only the @com_connect@ tag with the @to@ attribute set to a valid email address. If that doesn't send email, fill out the 'SMTP envelope sender address' field in Textpattern's Admin>Preferences. If that doesn't help either, take a look at your mail server log files to see what the problem is.

h5. Which tag do I use to create the submit button?

Just use normal HTML code to create a submit button. For historical reasons this plugin still provides the @com_connect_submit@ tag, but it provides little extra functionality.

h5. How can I get a unique (order) number in the subject of each email?

Try using the "rvm_counter":http://vanmelick.com/txp tag in the @subject@ attribute of the @com_connect@ tag.

h5. I want to use the contact form in an article list (one form for each article), but how do I make each form unique?

You can make each form unique by making one of its attribute values unique. See previous question for an example of how to do this with the @subject@ attribute.

h5. Send article: can I let people specify multiple recipients?

No. The 'send article' functionality is spammy enough as it is right now.

h5. Send article: can I show the contact form without having to click a link first?

Sure, put this just above the @com_connect@ tag:

bc(language-markup). txp:php$_GET['com_connect_send_article']='yes';</txp:php>

h5. How can I use this form to upload files?

You can't, but have a look at the "ext_file_attach":https://github.com/Bloke/ext_file_attach/releases/ module, or "mem_form":https://bitbucket.org/Manfre/txp-plugins/downloads/ plugins.

h5. Can I use this plugin to send HTML email?

Yes.

h5. Can I use this plugin to send newsletters?

Not without a plugin, such as "mem_postmaster":https://bitbucket.org/Manfre/txp-plugins/downloads/.

h5. I have a question that's not listed here

First read the plugin documentation (the page you're on right now) once more. If that doesn't answer your question, visit the "Textpattern forum":https://forum.textpattern.io.

h2. Authors/credits

• zem wrote the zem_contact 0.6 plugin on which this plugin was initially based.
• Mary completely revised the plugin code.
• Stuart turned it into a plugin, added a revised help text and additional code. Maintained all plugin versions until 4.0.3.17.
• wet added the @com_connect_radio@ tag.
• Tranquillo added the anti-spam API and @zem_contact_send_article@ functionality.
• aslsw66, jdykast and others provided additional code.
• Ruud cleaned up and audited the code to weed out bugs and completely revised the help text. Maintained all versions until 4.0.3.20.
• Bloke was the maintainer of v4.5.0.0.
• Adopted as a community plugin and now maintained by the core development team.
• Supported and tested to destruction by the Textpattern community. Many thanks to "all additional contributors":https://github.com/textpattern/com_connect/graphs/contributors.