Outlast Apps - Modular Apps
General setup
Follow these steps to enable an Outlast Modular App:
- Declare the baseapp as a local variable in the controller:
/* @var zajapp_app_base_base|zajapp_app_base_photo $baseapp */ private $baseapp;
- Add the load script and options setup to the
__load()section of your app controller:// Verify the app $this->zajlib->outlastapp->verify(); // Create my base application $this->baseapp = $this->zajlib->reroute('app/base/base/start/', array('photo', 'voterate')); $this->baseapp->set_options(array( 'vote'=>true, // Vote enabled? 'close'=>true, // Will close voting on the date set in the admin (if it is set) 'crop'=>false, // Crop enabled for photo? 'pageid'=>'12345678', // The Facebook page id (required for off-site like-gates) )); - Replace with the proper
__error()method:public function __error($request, $params){ return call_user_func_array(array(&$this->baseapp,$request),$params); }
Various ways of getting FacebookUser
Typically when you want FacebookUser data you first want the user to log in. There are a few ways to do this:
Client side (with url):
oa.accept('{{oaappctl}}page=method_on_success', '{{oaappctl}}page=optional_on_fail');
Client side (with callback functions):
oa.accept(function(){ /** success **/ }, function(){ /** cancelled **/ });
Server side (forces login first):
$this->baseapp->login();
Server side (does not force login, facebookuser is empty if failed):
$this->baseapp->get_fbuser();
Base app
The base application is available to all modular apps.
Options
No options.
Pages
login
The login page allows you to authenticate a Facebook application from PHP instead of the usual oa.accept() Javascript method. By default, the login page will authenticate the user and return to the same page. Here’s an example:
start
Used during the startup phase. See setup above.
get_options / set_options
You can use this do set or get options at runtime. For set_options() you need to pass and associated array.
$this->baseapp->set_options(array( 'option_key'=>'value!' );
terms
Typically you should use oa.terms() to invoke the terms and conditions popup. You can also use the following code to invoke a terms and conditions modal popup:
Elfogadom a <a class='underline' onclick="zaj.ajax.get('{{oaappctl}}page=terms');">játékszabályt</a>
Or in a separate window:
Elfogadom a <a class='underline' onclick="zaj.window('{{oaappctl}}page=terms');">játékszabályt</a>
apprequest
This method handles the recording of app requests so they are also stored in the local database. You should normally use the oa.request javascript method to send and record app requests.
oa.request('Title of request', 'Message of request', 'http://example.com/url/to/direct/request/recipients/', function(r){ /* r is an array of userids or it is null if the user cancelled. */ });
Quiz (OaQuizQuestion/ OaQuizResponse)
The quiz module allows you to set up questionaires and/or surveys for users.
Options
multiple_entries_allowed – boolean – false – If set to true, users can enter multiple times. minimum_score – integer – 0 – The minimum score required to allow entry. The default is 0 which means all entries are allowed. survey – boolean – false – If set to true, all responses will always be correct. This only affects the admin interface. ignore_entries_before – integer – 0 – Ignore old entries before this date. You can use this to start new rounds after a specific date. The format is Unix timestamp and you can use our timestamp generator if needed. Default is 0 which means none are ignored. quiz_all_required – boolean – false – All questions must be answered for the entry to be accepted. quiz_email_required – boolean – false – Require and validate email field during entry. If set to false email will still be saved and validated, but only if the field is sent in the request. quiz_questions_template – string – /app/base/quiz/questions.html – The template that displays the questions. Questions are stored in the {{questions}} variable and you can use this setting to completely customize the HTML. Have a look at the default template for an example! quiz_questions_in_random_order – boolean – false – If set to true, the questions will be displayed in random order. quiz_close_on_admin_date – boolean – false – If set to true, entries will not be accepted after the selected date in the admin panel. quiz_maximum_rounds – integer – 1 – The number of rounds available for this quiz (set to 0 for unlimited)
Pages
__load
The quiz module automatically loads up the {{questions}} that you can access in any of the pages.
questions
This page displays the quiz questions template and is typically used with {% include 'app/base/quiz/questions/' %}. You can use the quiz_questions_template option to completely customize the HTML markup of the quiz. You can also use parameters to limit the number of questions displayed or to paginate them: {% include 'app/base/quiz/questions/' 6 3 %}. This would display THREE questions starting at question SIX.
respond
Respond page automatically handles quiz responses. Optionally a name, email, and an array of other parameters can be passed to the response. Important note: the OaQuizQuestion->correct parameter is 0-indexed, while the admin site and the HTML version is 1-indexed. This can cause some confusion. Here’s an example implementation of a quiz template:
You can also override respond() to add custom response logic. When calling respond, you can set the optional $return_result_if_successful parameter to true as such:
Photo (OaPhoto)
The OaPhoto model is a media item that can contain several photos, videos, text, and other meta data. The photo module can be combined with the Vote/Rate, Location, and Video modules to enable fully interactive apps.
To enable the various features of Photo, you’ll need to use the built-in photo uploader field:
{% input oaphoto.photos '' 'app/base/photo/upload.field.html' %}
Options
width – int – 400 – Minimum width of photo.
height – int – 400 – Minimum height of photo.
crop – boolean – true – If set to true, crop will be enabled in GUI and during save.
ratio – string – ‘1:1’ – If crop is enabled, the ratio of the cropper tool and the resulting image.
photo_required – boolean – true – If set to true (the default) a photo upload will be required. If false, you can create an OaPhoto without an actual photo attached to it.
photo_required_count – int – 1 – The number of photos required. Only works if photo_required is set to true. You must include several upload fields on the upload interface if you need more than one photo.
photo_webcam – boolean – false – If set to true (defaults to false), Flash-based webcam photo is enabled.
photo_webcam_width – integer – 300 – The width of the webcam Flash widget.
photo_webcam_height – integer – 300 – The height of the webcam Flash widget.
photo_close_on_admin_date – boolean – true – If set to true, photo uploads will be disabled after the admin close date. If no admin close date is set, uploads will never be disabled.
FB auth scope
For rech the users Fb gallery, you need the “user_photos” custom auth scope in app admin.
Pages
upload()
This is the page to call when you want to upload and save a photo. Here’s a code sample:
/** @var OaPhoto $obj */
$obj = $this->baseapp->upload();
$obj->set('name', 'Name of photo');
$obj->set('oaapp', $this->zajlib->variable->oaapp);
$obj->save();
upload_standard()
This is the function to upload when the Plupload widget is not working. This is automatically included in the photo upload widget HTML.
upload_from_gallery()
This is the function to upload photos from your Facebook gallery. This is automatically included in the photo upload widget HTML, but must be styled to be visible.
Video (OaPhoto + Video)
Even though the model is called OaPhoto, it is actually a media entry, which can be one or more media items. As such Video objects can also be associated with an OaPhoto.
This option is available only if the Video plugin is enabled.
[additional development required for full support!]
Location (OaLocation)
The location module allows you to create a list of locations and display them on a map. Also include HTML5 location support.
Options
lat – integer – 47.497912 – The default latitude location for the map.
lng – integer – 19.040235 – The default longitude location for the map.
zoom – integer – 14 – The default zoom for the map (see Google Maps API).
geolocate – integer – true – Should we use HTML5 location to determine device location?
marker_click_url – integer – false – Set this to a url where %1 will become oalocation id: http://www.example.com/?item=%1
marker_click_function – integer – false – Set this to a function: the first passed param will be the oalocation id
marker_image_url – integer – false – Set this to a custom marker image url. Leave false if you want to use the default.
map_height – integer – 465 – The default height of the map if it is generated as an image.
Pages
map()
Display a map with all my own locations.
bool|string $id A single location id. Leave empty if you want all locations.
bool|string $oaapp The Outlast App id you wantto use. By default it uses the current oaapp.
bool $listview Show a list of results instead of map in view, false by default
You can use {% include %} to display the map in your app as follows:
{% include 'app/base/location/map/' %}
You can also pass parameters:
{% include 'app/base/location/map/' oalocation.id %}
Voterate (OaVote)
The vote module allows rating and voting on objects.
Options
vote – boolean – true – Vote enabled?
rate – boolean – false – Rating enabled?
rate_min – integer – 1 – The minimum rating
rate_max – integer – 5 – The maximum rating
voterate_my_own – boolean – true – Vote on my own stuff?
voterate_requires_fbuser – boolean – true – If set to true, you can only vote with a valid fbuser (helps reduce fraud)
voterate_perip_limit – integer – 0 – Per ip limit – 0 is no limit
voterate_again_after – integer – 0 – Allow vote/rate again after x seconds/days. The default is 0, which means no vote allowed again. Values up to 365 are counted as days (meaning you can vote again after midnight). Values above 365 are counted as seconds.
voterate_again_perentry – boolean – false – If set to true, voterate_again_after is calculated per entry. Meaning you can vote for different items immediately, but you can’t vote for the same item until voterate_again_after passes.
voterate_close_on_admin_date – boolean – true – If the close date is specified in admin, stop accepting votes after that date
Markup for voting
data-oavote-send="objid" – will send a vote on click for id
data-oavote-count="objid" – will refresh the vote count automatically if id is voted for with count
data-oavote-average="objid" – will refresh the vote count automatically if id is voted for with average
data-oavote-onvote="script()" – will evaluate this script after voting was successfully completed
Markup for rating
data-oarate-send="id" – will send a vote on click for id
data-oarate-set="id" – instead of sending a vote, it will just get ready to send it (and all others) whenever you call rate_send_all(). also, it will set any inputs with ids of “id” to the value given by data-oarate-value.
data-oarate-value="1" – the value of a given option.
data-oarate-count="id" – will refresh the vote count automatically if id is voted for with count
data-oarate-average="id" – will refresh the vote count automatically if id is voted for with average
data-oarate-current="value" – set the stars/rating value to this
data-oarate-model="oaphoto" – an optional lowercase parameter with which you can set the rating parent model. Only needed if different from app’s default model.
data-oarate-category="category_name" – an optional parameter where you can set the category for this rating. this will influence count, average, and send.
data-oarate-onrate="script" – this will be evaluated when the rating is sent and successful. if set is used, it will be called immediately on set.
data-oarate-sendurl="/a/url/" – this is used internally to store the submission urls when oarate-set is used. call rate_send_all() to send them all!
Click here to see an example code snippet using the rating data-attributes.
Pages
vote()
Vote for the current item. Used internally with the data attributes.
rate()
Rate the current item. Like vote() this is used internally with the data attributes.
Invite (OaInvite)
The invite app allows you to count and track how many people have invited users and how many of those users have actually signed up.
The invite app works by intercepting the standard oa.request() method and making sure that all such requests are calculated and tracked in the database. Since the invite app uses the FacebookUser object to identify users you should wrap the request in an oa.accept() to ensure that a FacebookUser is present when the user executes the request. Here’s a sample code segment:
function invite_my_friends(){
oa.accept(function(){
oa.request('Great app invite', 'Invite your friends now and win!');
});
}
Instagram (OaPhoto)
The instagram app allows you to create an Instagram and/or Facebook page feed where all #hashtagged content is imported and displayed. The admin panel allows admins to moderate the content.
All imported photos are stored as OaPhoto objects.
Options
instagram_hashtags – array – empty, required – An array of hash tag(s) you wish to look for in posts. Add it without #, so #example is ‘example’.
instagram_facebook_pages – array – array() – An array of Facebook pages you wish to also include for checking public posts with #hashtag. Leave empty if you do not want to include content from page posts.
instagram_client_id – string – outlast app default – Client id of the instagram app. You can leave the default here or you can create your own.
instagram_client_secret – string – outlast app default – Client secret of the instgram app. You can leave the default here or you can create your own.
Pages
update_feed()
Update all app feeds. Typically you should include this in a cron job to run every few minutes. You can optionally specify a ?count=100 query string to specify how many items each feed check should fetch.
Feed items are created as OaPhoto objects with the following properties:
name– the message text (truncated)externalid– the message idsource– this is ‘facebook’ or ‘instagram’category– this is the type: ‘image’ or ‘video’photos– this field is a standard photos field with the imported photo as the first itemother.caption– the full message textother.link– a link to the messageother.user– user id of the authorother.images– an object with the source image data. contains different info for insta and fb
update_feed_instagram()
Update the Instagram feed only. You can optionally specify a ?count=100 query string to specify how many items each feed check should fetch.
update_feed_facebook()
Update the Facebook feeds only.
Event (OaEvent)
The event app allows you to add events via the admin interface, display them, and perform various functions related to Facebook event integration.
Options
No options.
Pages
attend()
You can use this page to attend OaEvents if they are connected to Facebook events. To enable attending, you must:
- Enable the
rsvp_eventpermission for your app - Fill in the Facebook event url in the OaEvent’s
urlfield
You can call attend($oaeventid) from your code or you can perform a request with page=attend&oaevent=[oaeventid]. Both will attempt to perform an event attend API request on Facebook and then display the result via ajax().
You can also get the Facebook return value by passing the second parameter as attend($oaeventid, true).