Control Screen layout via Setting APIs
Controlling Screen layout via Setting APIs
The native mobile app allows us to control screen layout setting via 2 Core API
- Core App Setting API: This API collect all settings of each app then build the display layout
- Core Site Setting API: This API allows the app to define the setting for each screen display on Mobile. Support blocks and able to combine layout
Extend Core App Settings API
API Route: /core/app-settings?access_token=token
This API register all apps to the Native Mobile App. Implement getAppSetting in PostApi and getMobileSettings method in PostResource & PostCategoryResource classes
PostApi.php Expand source
<?php
class PostApi extends AbstractResourceApi implements ActivityFeedInterface, MobileAppSettingInterface
{
/.../
/**
- Define Native Mobile App setting
- @param $param
- @return MobileApp
*/
public function getAppSetting($param)
{
$l = $this->getLocalization();
$app = new MobileApp('post' ,[
'title'=> $l->translate('Posts'),
'home_view'=>'menu',
'main_resource'=> new PostResource([]),
'category_resource'=> new PostCategoryResource([]),
//'other_resources' => [
//new PostListResource([]),
//]
]);
$headerButtons = [
[
'icon' => 'list-bullet-o',
'action' => Screen::ACTION_FILTER_BY_CATEGORY,
],
];
if ($this->getAccessControl()->isGranted(PostAccessControl::ADD)) {
$headerButtons[] = [
'icon' => 'plus',
'action' => Screen::ACTION_ADD,
'params' => ['resource_name'=> 'post', 'module_name' => 'post']
];
}
$app->addSetting('home.header_buttons', $headerButtons);
return $app;
}
}
PostResource implementation:
Posts/Api/Resource/PostResource.php Expand source
<?php
class PostResource extends ResourceBase
{
/* ... */
public function getMobileSettings($params = [])
{
$permission = NameResource::instance()>getApiServiceByResourceName($this>resource_name)>getAccessControl()>getPermissions();
$l = $this->getLocalization();
return self::createSettingForResource([
'acl'=> $permission,
'resource_name' => $this->resource_name,
'search_input' => [
'placeholder'=>$l->translate('search_posts_dot'),
],
'schema' => [
'definition' => [
'categories' => 'post_category[]'
]
]
'forms'=> [
'addItem'=>[
'apiUrl'=>UrlUtility::makeApiUrl('post/form'),
'headerTitle'=>$l->translate('Add a New Post'),
],
'editItem'=>[
'apiUrl'=>UrlUtility::makeApiUrl('post/form/:id'),
'headerTitle'=>$l->translate('Editing Post'),
]
],
'list_view'=>[
'noItemMessage' => $l->translate('no_posts_found'),
'alignment' => 'right'
],
'detail_view'=>[
'component_name'=> 'blog_detail'
],
'app_menu'=> [
['label' => $l->translate('all_posts'), 'params'=>['initialQuery' => ['view' => '']]],
['label' => $l->translate('my_posts'), 'params'=>['initialQuery' => ['view' => 'my']]],
['label' => $l->translate('my_draft_post'), 'params'=>['initialQuery' => ['view' => 'draft']]],
['label' => $l->translate('friends_posts'), 'params'=>['initialQuery' => ['view' => 'friend']]],
['label' => $l->translate('pending_posts'), 'params'=>['initialQuery' => ['view' => 'pending']], 'acl' => 'can_approve'],
],
]);
}
}
PostCategoryResource no need to implement getMobileSettings because don't have a specific screen on Mobile App
After implementing the above method, re-check the API above and make sure new `post` object appended to the Core App Setting API
Detail information of each sectionItem
Type
Description
setting.resources
Object
The setting of each resource supported by the new Post app
setting.screens
Object
Screen Setting for the new app
setting.parameters
Object
Other parameters
Define Resource Settings
Resource setting
Type
Description
post.acl
Object
Control permission of the current user for the app
post.add.icon
string
Create a post button Icon
post.add.label
string
Create a post button label
post.search_input
object
Setting for search form in Post App
post.search_input.placeHolder
string
Place Holder display on the app
post.resource_name
string
Name of resource
post.forms
object
Define API to get the form to create & edit
post.forms.addItem
object
Define apiUrl & headerTitle for the Add form
post.forms.editItem
object
Define apiUrl & headerTitle for the Edit form
post.list_view
object
Define layout component & information used to render layout on mobile app
post.detail_view
object
Define layout component used to render layout on detail resource listing
post.feed_view
object
Define feed attachment layout on App, with 2 property:
- item_view: View name of attachment layout, support some default value: embed_blog, embed_video, embed_music_song, embed_event...
- alignment: If item_view is empty, using embed_default view was defined on App with the alignment of image on feed (top, right, left)|
Extend Screen Settings via Core Site Setting API
API Route: /core/site-settings?access_token=token
Method: GETScreen Setting Parameters
Defile all screen properties that supported by your app.
Parameter
Type
Description
screen.home
object
Define Home screen of the app
screen.home.headerTitle
string
screen.home.header_buttons
object
List of button display on the Home Screen
screen.home.header_menu
object
screen.home.header_menu.config_name
screen.home.header_menu.action
screen.home.default
screen.home.default.parent
screen.home.default.category_layout
screen.app.header_menu
Defined screen component, view, blocks on Mobile App, API will define some pages on Mobile:If a screen is defined, Admin can config to show Ads via AdMob on that screen in the specific section.Page Name
Screen ID
Module Home Page
module
Module Detail Page
detail
Module Search Page
listing
Each screen has some sections to show content, support some locations:Section Name
Description
Section ID
Location Top
Section on top
top
Location Bottom
Section on bottom
bottom
Location Main
The main content of the page
content
Location Header
Header of page
header
Location Right
Right block and show on a tablet only
right
Generate Screen Setting for an App
To implement views component for screen setting, make sure your App was added API service and implement MobileAppSettingInterface, then add the new function
getScreenSetting in that API.
Example:
use Apps\Core_MobileApi\Adapter\MobileApp\ScreenSetting;
use Apps\Core_MobileApi\Adapter\MobileApp\MobileAppSettingInterface;
//.....
class BlogApi extends AbstractResourceApi implements ActivityFeedInterface, MobileAppSettingInterface
{
//.....
public function getScreenSetting($param)
{
$screenSetting = new ScreenSetting('blog',[
'name' => 'blogs'
]);
$resourceName = BlogResource::populate([])->getResourceName();
$screenSetting->addSetting($resourceName, ScreenSetting::MODULE_HOME);
$screenSetting->addSetting($resourceName, ScreenSetting::MODULE_LISTING);
$screenSetting->addSetting($resourceName, ScreenSetting::MODULE_DETAIL);
$screenSetting->addBlock($resourceName, ScreenSetting::MODULE_HOME, ScreenSetting::LOCATION_RIGHT, [
'component' => ScreenSetting::SIMPLE_LISTING_BLOCK,
'title' => 'most_viewed',
'resource_name' => $resourceName,
'module_name' => 'blog',
'query' => ['sort' => 'most_viewed']
]);
return $screenSetting;
}
}
According to the above codes, we defined 3 screens for resource Blog (Home, Listing, Detail) and add a block on Right location in Home
Function $screenSetting->addSetting, will auto create a screen setting base on Page Name we mentioned above like that:
But if you add custom params, it will be used as screen config for that page.
If you add a custom Page Name, you have to define params for it. Example:
If you want to add a new block on a screen, have 2 ways:
Add a new location to your Page params.
Note: if you add a block into main content, it must be children of embedComponents array:
If you don't add params for your page, and use default config, you have to use function $screenSetting->addBlock. Below example, we add block Most Viewed for Blog Home Page at Right section:
$screenSetting->addBlock($resourceName, ScreenSetting::MODULE_HOME, ScreenSetting::LOCATION_RIGHT, [
'component' => ScreenSetting::SIMPLE_LISTING_BLOCK,
'title' => 'most_viewed',
'resource_name' => $resourceName,
'module_name' => 'blog',
'query' => ['sort' => 'most_viewed']
]);
Support parameters of each block
If you don't want to support ads on a screen, you should add property "no_ads" => true to that Page SettingKey
Description
component
Component name of the block, this value should be:
ScreenSetting::SIMPLE_LISTING_BLOCKtitle
Block title
resource_name
Resource name will be used to fetch item and define which view will be used to show item
module_name
Module name
query (optional)
Extra query for API of this block, the block will call API:
GETurl
/restful_api/mobile/<resource_name>?access_token=token
&<query>
to get datalimit (optional)
Default 4, defined how many items show on the block
$screenSetting->addSetting($resourceName, 'mainFriendRequest', [
ScreenSetting::LOCATION_HEADER => [
'component' => ScreenSetting::SIMPLE_HEADER,
'title' => 'friend_requests',
'back' => false
],
ScreenSetting::LOCATION_MAIN => [
'component' => ScreenSetting::SMART_RESOURCE_LIST,
'module_name' => 'friend',
'resource_name' => FriendRequestResource::populate([])->getResourceName()
],
'no_ads' => true
]);
Layout components
Layout components are a list of pre-defined components use to render layout on mobile controlled by Core Site Setting APIComponents for module home page, module search page
List of components are defined to render layout on module home page and module search/listing pageComponent Name
Description / Render
Recommend section
Supported parameter
Note
module_header
The Header section for module home page
header
- title: Title for this screen, default by module_name
- title: Title for this screen, default by module_name
- enableTitleMenu: (true, false) show or hide title for this screen, the default value is true|Search bar, right buttons controlled by Core App Setting API|
simple_header
The Header section for listing page
header
- title: Title for this screen, default by current category listing name
- title: Title for this screen, default by current category listing name
- transition: Behavior animation for this header
- 'simple'
- 'float'|Does not support search bar, right buttons like module_header|
stream_profile_feeds
List of feed items related to the current module
content
embedComponent contains other child components
None
smart_resource_list
List of items related to current module (no separation)
content
embedComponent contains other child components
Items type controlled by Core App Setting API
smart_resource_section
List of items related to current module (separated by section)
content
- Required an array parameter called sections. Each element in the array contain some parameters in order to control the layout of that section block:
- Required an array parameter called sections. Each element in the array contain some parameters in order to control the layout of that section block:
- 'simple'
- module_name: Module name
- module_name: Module name
- resource_name: Resource name will be used to fetch item and define which view will be used to show the item in this section
- header: { title: "your_title" }: Title of this section
- use_query: Extra query for API of this section
- limit: default is 10, defined how many items show on this section
- resource_name: Resource name will be used to fetch item and define which view will be used to show the item in this section
- embedComponent contains other child components
|Items type controlled by Core App Setting API|smart_tabs
List of items related to current module (separated by tab component)
content
- Required an array parameter called tabs. Each element in the array contain some parameters in order to control the layout of that tab block:
- Required an array parameter called tabs. Each element in the array contain some parameters in order to control the layout of that tab block:
- label: Title of this tab
- label: Title of this tab
- component: Component name for this tab
- resource_name: Resource name will be used to fetch item and define which view will be used to show in this tab
- query: Extra query for API of this tab
- component: Component name for this tab
- embedComponent contains other child components
|Items type controlled by Core App Setting API|sort_filter_fab
A floating block contains sort & filter button
mainBottom
None
None
Components for module detail page
List of components are defined to render layout on the module detail pageComponent Name
Description / Render
Recommend section
Supported parameter
Note
item_header
The header section for module detail page
header
- title: Title for this screen, the default is none
- title: Title for this screen, the default is none
- transition: Behavior animation for this header
- 'simple'
- 'float'
- 'transparent'|None|
feed_header
Header for feed detail page
header
None
This is a special type of header, only use for feed detail
item_simple_detail
Wrapper block for other item's component
content
embedComponent contains other child components
None
feed_detail
Detail of current feed item
content
embedComponent contains other child components
None
stream_profile_description
Information block of the current item ( short description location, category)
embedComponent
None
None
stream_profile_menus
Menu bar for the current item
embedComponent
None
Only use for profile item Ex. (User, Pages, Groups, ....)
stream_profile_photos
Photo block for the current item
embedComponent
None
None
stream_composer
Post Status, Composer block
embedComponent
None
None
item_image
Image field of this item
embedComponent
None
None
item_title
Title field of this item
embedComponent
None
None
item_pricing
Price field of this item
embedComponent
None
None
item_author
Author (created user) field of this item
embedComponent
None
None
item_stats
Statistic field of this item
embedComponent
stats: Object
Ex:
stats: {
view: 'total_view',
like: 'total_like',
comment: 'total_comment',
vote: 'total_vote',
play: 'total_play'
}
item_pending
Message block if this item is pending
embedComponent
message: the message will show in the center of the block
None
item_description
Short description (non-HTML) field of this item
embedComponent
None
None
item_html_content
Full description (both HTML or non-HTML) field of this item
embedComponent
None
None
item_separator
Separate current item_simple_detail
embedComponent
None
None
item_category
Category field of this item
embedComponent
None
None
item_genre
Genre field of this item
embedComponent
None
None
item_tags
Tags field of this item
embedComponent
None
None
item_user_tags
User tags field of this item
embedComponent
None
None
item_location
Location field of this item
embedComponent
None
None
item_video
Video field of this item
embedComponent
None
None
item_like_bar
Like, Comment, Share bar for this item
bottom
None
None
....
Components for all pages
List of components are defined to render some special blocks that can apply on all pagesComponent Name
Description / Render
Available section
Supported parameter
banner_ad
Admob Banner
- top
- top
- 'simple'
- bottom
- embedComponent
- right|* androidUnitId: Banner Unit Id provided by Google Admob to show a banner on the Android App
- iosUnitId: Banner Unit Id provided by Google Admob to show a banner on the iOS App
- capping: Frequency capping type of this banner ('no_frequency', 'time', 'views')
- limit: Number of occurrences of this banner (apply when capping = 'time' or capping = 'views' )
- time: the time limit (second) that app will refresh this banner (apply when capping='time')|
simple_list_block
List of limit items basing on parameters
- bottom
- bottom
- embedComponent
- right|* title: Block title
- module_name: Module name
- resource_name: Resource name will be used to fetch item and define which view will be used to show item
- query: Extra query for API of this block
- limit: Default 4, defined how many items shows on the block|
Components for specific pages
List of components are defined to render some special blocks that currently only apply for some specific pagesComponent Name
Apply For Page
Description / Render
Available section
Supported parameter
stream_user_header_info
User detail
Top section of User page (Cover, Avatar, some specific information)
embedComponent
None
stream_event_header_info
Event detail
Top section of Event page (Cover, Title, author)
embedComponent
None
stream_pages_header_info
Pages detail
Top section of Pages page (Cover, Avatar, some specific information)
embedComponent
None
stream_groups_header_info
Groups detail
Top section of Groups page (Cover, Avatar, some specific information)
embedComponent
None