Subscribe 1.0 Subscribe Form

Parameters

There are several parameters available for the subscribe_form tag.

{exp:subscribe:subscribe_form zone_name="bubba" form_name="This Subscription" return="my/template" onsubmit="some_javascript()" show_if_subscribed="no" allow_id_by_ip="yes" mailing_lists="yes" weblog="main_blog|another_blog" status="open" author="benji" category="5|6"}

In the above example, a given user, upon submitting the form, will be subscribed to the zone called bubba. They will see entries from the weblogs main_blog or another_blog and these entries will be filtered by the status open, the author benji and further, by categories 5 or 6. if the user is not a member or not logged in, the allow_id_by_ip parameter will allow them to subscribe to the zone. If any mailing lists have been provided for this subscription, the user will be subscribed to those as well.

The Subscribe module allows you to indicate weblogs, statuses, categories and mailing lists through the module's control panel (CP) or dynamically with each form. When you supply subscription filters in the subscribe form, these override those you have set in the CP. To add these filters to a form, simply add fields to the form as indicated below.

zone_name=

zone_name = "some_name"

The 'zone_name' parameter establishes which of the subscriptions that you created in the CP to use.

Note: This is a required parameter.

form_name =

form_name = "a_name"

The 'form_name' parameter allows you to name the subscribe form. This name will also be used as the id of the form for DOM targeting.

return =

return = "my/template"

The 'return' parameter determines where to send users once they have submitted the form.

onsubmit =

onsubmit = "some_javascript()"

The 'onsubmit' parameter allows for javascript to be triggered upon the submission of the form.

show_if_subscribed =

show_if_subscribed = "yes"

The 'show_if_subscribed' parameter will show the subscribe form again even if the user is already subscribed. If the user susmits the form, their subscription is changed to the new settings provided. The new settings replace the old. If this parameter is not provided, the default behavior is to not show the form to current subscribers.

allow_id_by_ip =

allow_id_by_ip = "my/template"

The 'allow_id_by_ip' parameter allows the module to store the user's subscription by their IP address. If the user has no IP address is not logged in and this parameter is not supplied, the form will not appear.

mailing_lists =

mailing_lists = "yes"

The 'mailing_lists' parameter will subscribe the user to the mailing lists provided. The default is to not subscribe users to provided mailing lists.

weblog =

weblog = "some_weblog"

The 'weblog' parameter allows you to dynamically add weblogs to the subscription. Separate multiple values with the pipe "|" character.

status =

status = "some_status"

The 'status' parameter allows you to dynamically add statuses to the subscription. Separate multiple values with the pipe "|" character.

author =

author = "some_author_username"

The 'author' parameter allows you to dynamically add authors to the subscription. Separate multiple values with the pipe "|" character.

category =

category = "my/template"

The 'category' parameter allows you to dynamically add categories to the subscription. Separate multiple values with the pipe "|" character.

Variable Pairs

The following variable pairs are available with the {exp:subscribe:unsubscribe_form} tag.

subscription_weblogs

{subscription_weblogs}{/subscription_weblogs}

The 'subscription_weblogs' variable pair will allow you to show information about the weblogs that have been attached to the subscription. The following variables are available:

The backspace parameter is available with this variable pair.

subscription_statuses

{subscription_statuses}{/subscription_statuses}

The 'subscription_statuses' variable pair will allow you to show information about the statuses that have been attached to the subscription. The following variables are available:

The backspace parameter is available with this variable pair.

subscription_authors

{subscription_authors}{/subscription_authors}

The 'subscription_authors' variable pair will allow you to show information about the authors that have been attached to the subscription. The following variables are available:

The backspace parameter is available with this variable pair.

subscription_mailing_lists

{subscription_mailing_lists}{/subscription_mailing_lists}

The 'subscription_mailing_lists' variable pair will allow you to show information about the mailing lists that have been attached to the subscription. The following variables are available:

The backspace parameter is available with this variable pair.

Conditionals

The following conditionals are available with the {exp:subscribe:unsubscribe_form} tag.

if subscribed

{if subscribed}{/if}

In the event that a user is either logged in or their IP address is available and if they have subscribed to the indicated subscription, the contents of this conditional will be shown.

if not_subscribed

{if not_subscribed}{/if}

In the event that a user is either logged in or their IP address is available and if they have not subscribed to the indicated subscription, the contents of this conditional will be shown.

if subscription_weblogs

{if subscription_weblogs}{/if}

If weblogs have been specified as part of this user's subscription, the contents of this conditional will be shown.

if subscription_statuses

{if subscription_statuses}{/if}

If statuses have been specified as part of this user's subscription, the contents of this conditional will be shown.

if subscription_authors

{if subscription_authors}{/if}

If authors have been specified as part of this user's subscription, the contents of this conditional will be shown.

if subscription_categories

{if subscription_categories}{/if}

If categories have been specified as part of this user's subscription, the contents of this conditional will be shown.

if subscription_mailing_lists

{if subscription_mailing_lists}{/if}

If mailing lists have been specified as part of this user's subscription, the contents of this conditional will be shown.

Form Fields

The following form fields can be used inside the {exp:subscribe:subscribe_form} tag.

email

<input type="text" name="email" value="" />

The 'email' field captures the user's email address. If the field is not provided and the user is logged in, their email address of record is used.

weblog

<input type="checkbox" name="weblog[]" value="some_weblog" /> Some Weblog

The 'weblog' field will capture the weblogs to which the user wishes to subscribe. The name of the field must be weblog[]. This allows your users to subscribe to multiple weblogs. If you do not include this field, the user will be subscribed to the weblogs you specified in the CP for this subscription. No weblogs need be specified.

status

<input type="checkbox" name="status[]" value="some_status" /> Some Status

The 'status' field will capture the statuses to which the user wishes to subscribe. The name of the field must be status[]. This allows your users to subscribe to multiple statuses. If you do not include this field, the user will be subscribed to the statuses you specified in the CP for this subscription. No statuses need be specified.

author

<input type="checkbox" name="author[]" value="some_author_username" /> Some Author

The 'author' field will capture the authors to which the user wishes to subscribe. The name of the field must be author[]. This allows your users to subscribe to multiple authors. If you do not include this field, the user will be subscribed to the authors you specified in the CP for this subscription. No authors need be specified.

Note: If you use the CP to specify authors for a subscription, you will only see those authors who have been added to the public author list.

category

<input type="checkbox" name="category[]" value="1" /> Some Category

The 'category' field will capture the categories to which the user wishes to subscribe. The name of the field must be category[]. This allows your users to subscribe to multiple categories. If you do not include this field, the user will be subscribed to the categories you specified in the CP for this subscription. Categories must be specified numerically. No categories need be specified.