Getting started
Sections
Help

Application:hello

From Snowfire Wiki

Jump to: navigation, search

The following guide will demonstrate how to create a basic application in Snowfire. The application will generate data with PHP and send it to a layout/page in Snowfire. This application and other examples can be found at http://apps.snowfireapp.com

Let's get started

First I'll make sure to have a web server where I will create my PHP script (called application from now on). The web server needs to be connected to the internet since Snowfire needs to fetch data from it. If you're developing locally, please make sure to turn off your firewall and use your external IP. For the purpose of this tutorial I will use 127.0.0.1 in my example code.

Create app.xml and place it in your web root (I will place it in http://127.0.0.1/helloworld/app.xml). This file will tell Snowfire what your app is called and what it does.

<?xml version="1.0" encoding="utf-8"?>
<application>
	<app>
		<id>helloworld</id>
		<name>Hello World</name>
	</app>
 
	<acceptUrl>http://127.0.0.1/helloworld/install.php</acceptUrl>
	<uninstallUrl>http://127.0.0.1/helloworld/uninstall.php</uninstallUrl>
 
	<integration>
		<point type="MODULE_TAB">
			<url>http://127.0.0.1/helloworld/tab.php</url>
		</point>
	</integration>
 
	<actions>
		<action>
			<name>date</name>
			<url>http://127.0.0.1/helloworld/view.php</url>
		</action>
	</actions>
 
</application>

The app id and action name is string identifiers and no other characters than a-z and 0-9 are allowed. <integration> and <actions> are optional but you need one of them to make your app useful. I'll show you how they work later in this guide.

Install/Uninstall

To connect a Snowfire account to an application a user needs to install it. I'm going to create "install.php" in my web root.

install.php

<?php
if (!stristr($_SERVER['HTTP_USER_AGENT'], 'snowfire')) {
	die('Please use this URL to install the application Hello World to your Snowfire powered website');
}
 
// Speak XML when you talk to Snowfire
header('Content-Type: text/xml');
 
// Snowfire will actually make two separate calls to install.php
// First time - return the app.xml  (the user will be asked to give permissions to your app)
// Second time - Snowfire will send a HTTP POST with the application key and the accounts domain (the user accepted your app)
if (isset($_POST['appKey'], $_POST['domain'], $_POST['userKey'])) {
	// Do something useful with $_POST['domain'] and $_POST['key']
	file_put_contents('auth', $_POST['appKey'] . "\n" . $_POST['userKey'] . "\n" . $_POST['domain']);
	echo '<?xml version="1.0" encoding="utf-8"?><response><success>true</success></response>';
} else {
	readfile('app.xml');
}

When the user accepts the application I'll save its information in a file. The uninstall script will remove this file.

uninstall.php

<?php
 
if (!stristr($_SERVER['HTTP_USER_AGENT'], 'snowfire')) {
	die('Please use this URL to uninstall the application Hello World to your website');
}
 
header('Content-Type: text/xml');
unlink('auth');
echo '<?xml version="1.0" encoding="utf-8"?><response><success>true</success></response>';

Snowfire sends the app key to the uninstall action if you need it. Retrieve it with $_POST['key']

Now let's login to Snowfire and hit the "Applications" tab. Install a new application with your development url like http://localhost/hello_world/install.php It should return success and add a new tab called "Hello World". Click it.

..yes it will give you a 404 NOT FOUND because it's trying to access "tab.php" in your web root. I don't like 404 pages so I'll create "tab.php".

tab.php

<?php
 
// To make sure your user is really coming from a logged in Snowfire account
// validate $_GET['snowfireUserKey'] and $_GET['snowfireAppKey'] against your "auth" file
 
?>
 
Hi there! 
 
<a href="javascript:history.back(1)">Return to Snowfire</a>

Call your PHP application from a page layout

I'm going to create a new page layout (via Snowfires FTP) in /layout/layouts/hello.tpl as an empty file and jump to the "Pages" tab -> "Layouts" -> "Install new layout" then create a new page based on the "Hello" layout. Now add the following code to your layout:

{ com_singlerow ( id:'1', description:'heading', htmlElement:'h1', key:'heading' ) }
{ com_application ( id:'2', app:'helloworld', action:'date', cache:'0', paramUrl:'true', paramKey:'true', paramUrlNoDomain:'true' ) }

Then add "view.php" in your web root:

<p>Hi, today's date is <?= date('Y-m-d') ?></p>

Reload your page layout within Snowfire's Live edit and voila, your applications is outputting today's date from your web root within Snowfire.

Views
Personal tools