Extending Mobile App Functionality

Since Dolphin v.7.0.7 and Mobile Apps v.1.4 it is possible to add HTML based pages to the mobile app. Account home and profile pages are now customizable and modules can add new items to these pages. This is small tutorial for modules' developers on how to do this.

1. Adding items to home and profile pages

2. Creating web page for mobile

3. Custom URLs schemes

4. Mobile app alerts

1. Adding items to home and profile pages

To add new item to the specified page you need to add record to sys_menu_mobile table:

• id: auto-generated record ID
• type: module identifier (for example bx_news for BoonEx news module) or system for Dolphin core functionality.
• menu: page to add item too, now only system and homepage pages/menus are supported
• title: title of the button item, also it is used as the title of the page this button opens (in the case of HTML page)
• icon: button icon name or URL, for "homepage" menu/page only. If nothing is specified default icon is used. You can specify URL to the image, or use one of the predefined system icons:
  • home_status.png
  • home_location.png
  • home_messages.png
  • home_friends.png
  • home_info.png
  • home_search.png
  • home_images.png
  • home_sounds.png
  • home_videos.png
• action: action identifier, the following actions are supported:
  • homepage
    • 1: update status message
    • 2: view/update location
    • 3: messages
    • 4: friends
    • 5: profile info
    • 6: profiles search
    • 7: images
    • 8: videos
    • 9: sounds
    • 100: open custom URL (provided in action_data field)
    • 101: open custom URL (provided in action_data field) in external browser (available since v.1.6)
  • profile
    • 2: view user's location
    • 3: send a message to the user
    • 4: view user's friends
    • 5: view user's profile info
    • 7: view user's images
    • 8: view user's videos
    • 9: view user's sounds
    • 10: send report about current profile (email to send report to must be in action_data field) (available since v.1.8)
    • 100: open custom URL (provided in action_data field)
    • 101: open custom URL (provided in action_data field) in external browser (available since v.1.6)
  • search (available since v.1.6)
    • 30: search by keyword
    • 31: search by location
    • 32: search nearest members
    • 100: open custom URL (provided in action_data field)
    • 101: open custom URL (provided in action_data field) in external browser
• action_data: custom data for action, now only action with identifier equals to 100 or 101 supports custom data
• eval_bubble: some bubble for the button, if this field is empty bubble is not shown (evaluated as PHP code)
• eval_hidden: is this item is hidden, if this field is empty item is visible (evaluated as PHP code)
• order: item order
• active: is item active, 0 or 1

Some fields support custom markers, the following markers are provided by default:

• homeage
  • {site_url}: site URL
  • {member_id}: logged in member's ID
  • {member_username}: logged in member's username
  • {member_password}: logged in member's password (md5 of clear password)
• profile
  • {site_url}: site URL
  • {member_id}: logged in member's ID
  • {member_username}: logged in member's username
  • {member_password}: logged in member's password (md5 of clear password)
  • {profile_id}: viewed profile's ID
  • {profile_username}: viewed profile's username
• search (available since v.1.6)
  • {site_url}: site URL
  • {member_id}: logged in member's ID
  • {member_username}: logged in member's username
  • {member_password}: logged in member's password (md5 of clear password)

The following fields support markers substitution:

• eval_hidden
• eval_bubble
• action_data
• icon

{member_password} marker can be used to perform users authentication, to check if member's password is correct call this code:

if (!($iId = BxDolXMLRPCUtil::checkLogin ($sUser, $sPwd)))
        echo 'Username or password is incorrect, access denied';
else
        echo 'Username and password are correct, access granted';

2. Creating web page for mobile

Pages for mobile apps are created using HTML.

To match mobile app design you need to use predefined styles, please refer to templates/base/css/mobile.css file for all default CSS classes, use them as much as possible.

Also there are some useful mobile templates:

• mobile_box.html: box to wrap some content
• mobile_page_padding.html: adds default padding to some content
• mobile_row.html: click-able row to wrap some content

To create mobile page, you need to use BxDolMobileTemplate class, so creation of simple "Hello Word!" page looks like this:

    function actionMyFirstMobilePage() {
        
        bx_import('BxDolMobileTemplate');
        $oMobileTemplate = new BxDolMobileTemplate($this->_oConfig, $this->_oDb);
        $oMobileTemplate->pageStart();

        echo 'Hello World!';

        $oMobileTemplate->pageCode('Hello World Page');
    }

Above page will be accessible using the URL like this:

http://my-site.com/path-to-dolphin/m/my-module-uri/my_first_mobile_page/

You can refer to actionMobileEntry and actionMobileLatestNews functions in default BoonEx News module for some basic examples.

3. Custom URLs schemes

You need to use specific URL schemes to refer to some content inside the app. All parameters must be url encoded, in PHP use rawurlencode function.

The following URL schemes are supported:

• bxprofile:[some-username-here]: link to some profile inside the app, for example:

<a href="bxprofile:AlexT">View AlexT profile</a>

• bxcontact:[some-username-here]: open send message page with some profile set as recipient, for example:

<a href="bxcontact:AlexT">Contact AlexT</a>
Old syntax, use syntax described below for mobile apps since v.1.6

• bxcontact://[some-username-here]@[some-user-title-here]: open send message page with some profile set as recipient, for example:

<a href="bxcontact://AlexT@Alexander Ivanov">Contact Alexander Ivanov</a>
Available since v.1.6

• bxgoto:[section-name-here]: open some system page inside the app, the following system pages are supported:
  • home
  • friends
  • messages
  • images (unavailable since v.1.6)
  • search

Example of usage: <a href="bxgoto:friends">View my friends</a>

• bxphoto://[username]@[album-id]/[image-id]: link to some image inside the app, for example:

<a href="bxphoto://AlexT@14/21">View image</a>
Available since v.1.5

• bxvideo://[username]@[album-id]/[video-id]: link to some video inside the app, for example:

<a href="bxvideo://AlexT@14/21">Watch video</a>
Available since v.1.5

• bxaudio://[username]@[album-id]/[sound-id]: link to some sound inside the app, for example:

<a href="bxaudio://AlexT@14/21">Listen sound</a>
Available since v.1.5

• bxphotoupload:[album-name]: show upload photo dialog into specified album, if the album doesn't exist it is automatically created, for example:

<a href="bxphotoupload:my vocation">Upload photo</a>
Available since v.1.5

• bxlocation:[username]: show user's location screen, for example:

<a href="bxlocation:AlexT">AlexT's location</a>
Available since v.1.5

• bxprofileinfo:[username]: show user's information screen, for example:

<a href="bxprofileinfo:AlexT">AlexT's information</a>
Available since v.1.5
Unavailable since v.1.6

• bxprofilefriends:[username]: show user's friends list screen, for example:

<a href="bxprofilefriends:AlexT">AlexT's friends</a>
Available since v.1.5

• bxphotoalbums:[username]: show user's photo albums, for example:

<a href="bxphotoalbums:AlexT">AlexT's photos</a>
Available since v.1.5

• bxvideoalbums:[username]: show user's video albums, for example:

<a href="bxvideoalbums:AlexT">AlexT's videos</a>
Available since v.1.5

• bxaudioalbums:[username]: show user's audio albums, for example:

<a href="bxaudioalbums:AlexT">AlexT's sounds</a>
Available since v.1.5

• [url]#blank: open [url] in external browser, for example:

<a href="http://www.boonex.com/#blank">BoonEx</a>
Available since v.1.6

• bxpagetitle:[title]: set page title to [title], for example, include this in you page and title will be changed upon loading this iframe:

'<iframe style="width:0px;height:0px;border:0px;" src="bxpagetitle:' . rawurlencode('Custom Title') . '" ></iframe>'
Available since v.1.6

4. Mobile app alerts

It is possible to handle some alerts to customize mobile app even more.

The following alerts are supported:

• BxDolAlerts('mobile', 'view_profile', $iIdProfile, $iId, array('access_denied' => &$mixedAccessDenied)): mobile profile is going to be viewed.
  • access_denied: already defined variable, you can override this to make some custom behavior, possible values:
    • some message: if access to the profile is denied for some reason, usually according to membership settings
    • -1: if access to the profile is denied because of privacy settings
    • false: if profile is accessible for the given viewer
• BxDolAlerts('mobile', 'contacts', $iId, 0, array('contacts_data' => $aAll)): member's contacts is going to be viewed.
  • contacts_data: already defined array with member's contact, you can override this to add/remove some contacts, by default contacts are all members in fave/hot list, friends and message senders or recipients.
• BxDolAlerts('mobile', 'user_info', $iId, $iIdViewer, array('profile' => &$aSexSql, 'return_data' => &$aRet)): profile's info.
  • profile: profile info array
  • return_data: override-able return data, be careful, since it is already in XMLRPC format
• BxDolAlerts('mobile', 'user_info2', $a['ID'], $iIdViewer, array('profile' => &$a, 'return_data' => &$aRet)): similar alert as above, but the return data is formatted a bit different way
  • profile: profile info array
  • return_data: override-able return data, be careful, since it is already in XMLRPC format
• BxDolAlerts('mobile', 'menu', 0, 0, array('menu' => $sMenu, 'data' => &$aRecords, 'markers_replace' => &$aMarkersReplace)): menu for mobile pages
  • menu: menu/page, for now it is homepage or profile only
  • data: override-able menu data, before processing any markers
  • markers_replace: markers to replace in some fields, you can override this array, by adding custom markers
• BxDolAlerts('mobile', 'check_login', $iId, 0, array('password' => $sPwd, 'return_data' => &$iRet)): user is going to be authenticated
  • password: clear password
  • return_data: return data, true - authentication is successful, false - authentication failed, you can override this to restrict some users logging in to your site using mobile app.