Giveaway API

With the API you can extend the entrant and giveaway models and handle some system events. For example, you can add a required Twitter Name field to the signup form.

Module CMS actions

The module provides a single action giveaway:landing, which is a base action for all giveaway landing pages. This action generates the following PHP variables.

• $fatal_error - string. If this variable is not null, no data but the variable content should be displayed on the page.
• $giveaway - the giveaway object. This variable can be empty (null) in case if the giveaway was not found or if the giveaway is not published.
• $giveaway_meta_tags - string, contains the Open Graph meta tags string.
• $giveaway_image - string, contains the giveaway image URL. You can use it in the src attribute of the img tag.
• $is_started - boolean, determines whether the giveaway has started.
• $is_ended - boolean, determines whether the giveaway has ended.
• $mode - string, specifies the page mode - 'signup' or 'dashboard'.

Dashboard mode variables

The following available are generated when the page runs in the dashboard mode.

• $just_confirmed - boolean, indicates that the entrant has just confirmed his registration by clicking the confirmation link in the registration email message. If this variable is TRUE, the $confirmation_message variable content should be displayed.
• $confirmation_message - string, contains the confirmation message which you can specify on the Messages tab of the Create/Edit Giveaway form.
• $entrant - the entrant object.
• $share_link_short - string, shortened Share URL.
• $share_link - string, original Share URL.
• $entry_count - integer, number of the entrant's entries.
• $twitter_button - string, contains the Twitter share button code.
• $facebook_button_link - string, contains the A tag string for creating a custom Facebook share link.
• $facebook_button - string, contains the Facebook share button code.
• $linkedin_button_link - string, contains the A tag string for creating a custom LinkedIn share link.
• $linkedin_button - string, contains the LinkedIn share button code.
• $googleplus_button - string, contains GooglePlus button code.

Signup mode variables

The following available are generated when the page runs in the signup mode.

• $signup_error - string, contains the signup error message.
• $signup_success - boolean, gets TRUE value on successful signup.
• $show_terms - boolean, determines whether the Terms and Conditions text and I Agree checkbox should be displayed.
• $terms_status - boolean, determines whether the I Agree checkbox has been checked before the visitor clicked Submit button.
• $captcha - string, contains HTML code for displaying reCAPTCHA widget.

Expected signup mode fields

The signup form should contain the following controls.

• agree - the checkbox input name. The checkbox should be displayed only if $show_terms variable is TRUE.
• email - the Email input name. This is a required field.
• signup - name of the Submit button.

If you use a custom module which adds extra fields to the entrant model and you need those fields to be presented on the sign up form, use the following format for naming the field input elements: api_fields[custom_field_name]. Example:

Your Twitter name: <input 
	type="text" 
	value="<?= h(post_array_item('api_fields', 'xxx_twitter_name')) ?>" 
	name="api_fields[xxx_twitter_name]"/>

Handling API events

The general process of handling LemonStand system events is explained in this documentation article.

You can download a template module which handles some Giveaway module events here: giveawayapitest.zip. The module adds the following events to the system:

• giveaway:onExtendEntrantModel - allows to extend the entrant model. New columns should be added to the giveaway_entrants table. The handler should accept 2 parameters: the entrant model object and the form execution context string.
• giveaway:onExtendEntrantForm - allows to add new controls to the entrant popup form. The handler should accept 2 parameters: the entrant model object and the form execution context string.
• giveaway:onGetEntrantFieldOptions - handling this event is required if you add drop-down menu or radio buttons to the entrant form. The handler should accept 1 parameter - the field name and return an associative array of options.
• giveaway:onBeforeEntrantSignup - triggered before new entrant signs up. The handler should accept the following parameters: giveaway object, entrant object, giveaway page URL. Throw an exception in the handler if you need to stop the sign up process and display a message to the entrant.
• giveaway:onAfterEntrantSignup - triggered after new entrant signed up. The handler should accept the following parameters: giveaway object, entrant object, giveaway page URL.
• giveaway:onEntrantConfirmed - triggered after an entrant confirmed his registration. The handler should accept 2 parameters - the giveaway object and the entrant object.
• giveaway:onEntryAdded - triggered after an entry is added to an entrant. The handler should accept 2 parameters - the entrant object and the entry object.

Previous: Picking winners
Return to Giveaway module