Public Submissions

LiveWhale comes with functionality that allows visitors to your public web site to suggest news stories, events, and images to your website (or just events, in the case of LiveWhale Calendar). These items are added to a special “Public” group in the back-end for you to review, edit, and publish when ready.

Publicly submitted data will not show up on the public web site unless:

  • a widget or calendar explicitly requests it (<arg id="show_public">true</arg>)
  • or, the data is copied to or shared with another group.

Setting up a submission form

Event submission form

A default event submission form is included with Livewhale and LiveWhale Calendar at /livewhale/theme/core/templates/submit_event.php, which you can copy, edit, and include in your website. The form will include captchas if configured for your site.

There are a set of default form fields that are included in this form. Here is the full set of supported fields:

Field Name Notes
Contact Name (required) name
Contact Email (required) email
Title (required) event_title
Start Date (required) event_date Add class="lw_date" for datepicker
Start Time event_time Add class="lw_time" for timepicker
End Date (LiveWhale 1.7+) event_date2 Add class="lw_date" for datepicker
End Time event_time2 Add class="lw_time" for timepicker
Summary (LiveWhale 1.7+) event_summary Supports multiple lines with <textarea>
Description event_description Supports multiple lines with <textarea>
Contact Info event_contact_info Supports multiple lines with <textarea>
Cost (LiveWhale 1.7+) event_cost Added as cost type “Other,” supports multiple lines with <textarea>
Location event_location
Web Address event_location Added as Related Content
Event Types Use <xphp var="event_types"/> Selector will only show starred event types
Tags event_tags Separated by commas
Photo Use <input type="hidden" class="lw_upload"/>
Photo Caption event_image_caption
Photo Keywords event_image_keywords
Photo Credit event_image_credit
Submit to calendar (if configured) submission_group
Online Events (LiveWhale 1.7.1+) See Online Events documentation for fields

Advanced: Create and accept your own custom submission variables using the onAfterPublicSubmission handler.

News story submission form

A default news submission form is included with Livewhale at /livewhale/theme/core/templates/submit_news.php, which you can copy, edit, and include in your website. The form will include captchas if configured for your site.

Or, you can model a news story submission form after the default event submission form, removing the date, time, and event type fields and substituting in the following field names:

  • Story Title (news_headline)
  • Story Summary (news_summary)
  • Story Body (news_body)
  • URL of Story (gets added to story as Related Content)
  • Tags (news_tags)
  • Image (leave the same default lw_upload code)
  • Image Caption (news_image_caption)
  • Image Credit (news_image_credit)
  • Image Keywords (news_image_keywords)
  • Contact Name (required)
  • Contact Email (required)
  • Contact Phone Number

and editing the form action to <form method="post" action="/live/public/submit/news">.

Image submission form

A default image submission form is included with Livewhale at /livewhale/theme/core/templates/submit_image.php, which you can copy, edit, and include in your website. The form will include captchas if configured for your site.

Or, you can model an image submission form after the default event submission form, removing everything except the following fields:

  • Image (leave the same default lw_upload code)
  • Description (image_description)
  • Image Caption (image_caption)
  • Image Credit (image_credit)
  • Image Keywords (image_keywords)
  • Contact Name (required)
  • Contact Email (required)
  • Contact Phone Number

and editing the form action to <form method="post" action="/live/public/submit/image">.

Choosing which group will receive submissions

By default, all content will be submitted to the “Public” group. You may choose to send news and events to other groups (images must always go to the “Public” group for approval) using the below options.

  • You can set one group for all submissions by editing the HTML form to include
    <input type="hidden" name="submission_group" value="123" \> and replacing 123 with the group ID of your chosen group.

  • Or, you might want to submit to the current group of wherever you’ve included the form. You can use <input type="hidden" name="submission_group" value="<xphp var="group_gid" \> in the HTML form to do that.

  • Or, you can have your users choose which group to submit to. Find the widget type="public" in the HTML form and use the following option:

    1
    2
    3
    <widget type="public" priority="high">
    <arg id="enable_group_selector">true</arg>
    </widget>

    then, add to your form

    1
    2
    3
    4
    <tr>
    <td class="labels"><strong>Submit to group</strong>:</td>
    <td class="inputs"><xphp var="submission_group"/></td>
    </tr>

    This will show a drop-down menu of all groups. To choose which groups should be available in that drop-down, edit the public LiveWhale config (/livewhale/client/public.config.php) and set

    $_LW->CONFIG['PUBLIC_GROUPS']=array(123, 124, 125);

    to include only the group IDs you want.

    Since LiveWhale 1.7, you can instead configure a list of groups you don’t want included in the drop-down, if that’s easier than having to add new groups to the PUBLIC_GROUPS array:

    $_LW->CONFIG['EXCLUDE_PUBLIC_GROUPS']=array(200, 201, 202);

Requiring fields in public submission form

By default, name and email are required fields for all public submissions. If you submit an image, caption is required. You can require additional fields in your public submission form by adding a custom validation handler.

Receiving notifications of public submissions

If you’re submitting to the “Public” group: You can choose who will receive email notifications of public submissions by editing the global LiveWhale config (/livewhale/client/public.config.php) and setting

$_LW->CONFIG['PUBLIC_NOTIFICATIONS_EMAIL']='';

If you’re submitting to another group: Anyone who can publish dynamic content in a group (i.e., Publishers, Curators, and Administrators in LiveWhale Calendar) will be sent notifications when a story or event has been submitted to their group.

Sending confirmation emails

Since LiveWhale 1.7, you can send your visitors an email confirmation of their submission by setting the form field send_email in your form. You can allow them to choose to receive it with a checkbox.

1
2
3
4
<label>
<input type="checkbox" name="send_email" value="1" />
Receive an email confirmation of your submission?
</label>

Or use a hidden input to send the email for all submissions.

1
2
<!-- always send a confirmation email -->
<input type="hidden" name="send_email" value="1" />

Setting a custom Thank You page

For an individual form

Since LiveWhale 1.7, you can set (or override) a custom thank you page on a per-form basis by adding a hidden input “thanks_url” to the form itself:

<input type="hidden" name="thanks_url" value="https://myschool.edu/thanks" />

Globally

To set a global thank you page for all public submission forms, open the public LiveWhale config (/livewhale/client/public.config.php) using an FTP client or via the command line. To specify the URL you should be taken to after filling out a public submission form, enter it like this:

$_LW->CONFIG['PUBLIC_THANKS_URL']='/thanks.php';

If none is supplied, the default is /_ingredients/templates/details/submit_thanks.php.

Receiving custom fields from a public submission form

You may have custom fields on your events, news, or images, and you can also receive values for those custom fields using your public submission forms.

In LiveWhale 1.7+, you can add inputs to your form with name="custom_my_variable_name" and LiveWhale will automatically set the custom field “my_variable_name” with that value for any inputs prefixed with custom_.

In LiveWhale 1.6.2 and before, receiving and setting custom fields is done using the onAfterPublicSubmission handler in a custom module.