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:

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 ALT Description ( news_image_alt, LiveWhale 2.18.0+)
• 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 ALT Description ( image_alt, LiveWhale 2.18.0+)
• 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:

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

  then, add to your form

  <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']=[123, 124, 125];

  to include only the group IDs you want.

  You can also 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']=[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

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.

<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.

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

Setting a custom Thank You page

For an individual form

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.

Pre-defined options on the public submission form

Location options

In most default submission forms, locations are entered as plain text:

<input type="text" name="event_location" id="event_location"/>

You also have the option to offer a dropdown of saved locations that users can choose from.

<xphp var="locations" />

This dropdown will, by default, show all available locations as well as an “Other” option that opens a free text field to add your own location.

• You can hide the “Other” option by hiding/removing option.location_other via CSS.
• You can customize which group(s) locations display by adding <arg id="locations_group">My Group</arg> to the <widget type="public"> settings at the top of the submission form. In fact, any settings that begin with locations_ in that space will be passed through to the widget that generates <xphp var="locations" /> .
• If you’d like even more robust customization, you can even use your own <widget type="locations"> code instead of the saved XPHP variable, basing it on the contents of /livewhale/core/modules/public/public.widget.public.php

Tag options

In most default submission forms, tags were entered as plain text:

<input type="text" name="event_tags" id="event_tags"/>

 You also have the option to offer checkboxes of saved tags that users can choose from.

<xphp var="tags" />

These checkboxes will, by default, show all starred tags as well as an “Other” option that opens a free text field to add your own location.

• You can hide the “Other” option by hiding/removing li.tag_other via CSS.
• You can customize which group(s) tags display by adding <arg id="tags_group">My Group</arg> to the <widget type="public"> settings at the top of the submission form. In fact, any settings that begin with tags_ in that space will be passed through to the widget that generates <xphp var="tags" /> .
• If you’d like even more robust customization, you can even use your own <widget type="tags"> code instead of the saved XPHP variable, basing it on the contents of /livewhale/core/modules/public/public.widget.public.php

Adding WYSIWYG options to the public submission form

For certain fields like the summary, description, or contact information, you may want to include more WYSIWYG options for your editors to use. This can be done by first adding the class=wysiwyg to your submit_event.html for the desired text area:

<textarea name="event_description" class="wysiwyg"></textarea>

You’ll also need to include the following scripts towards the end of the HTML <body> as well:

<script src="/livewhale/thirdparty/tinymce/tinymce.min.js"></script> 
<script type="text/javascript">
tinymce.init({
        selector: 'textarea.wysiwyg',
        menubar: false,
        plugins: 'autolink lists link paste',
        toolbar: 'bold italic link | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | removeformat',
});
</script>

(Note: CMS users can add the script directly to the page using the “Add custom Code” option on the page editor. For LiveWhale Calendar, you can add it into your submit_event.html template or similar.)

You then should have something like this on your Public Submission form:

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.

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_ .