Control Screen layout via Setting APIs
The native mobile apps allow us to control screen layout setting via 2 Core APIs
- Core App Setting API: This API collects all settings of each app to build the screen layout
- Core Site Setting API: This API allows the app to define settings for each mobile screen. Support blocks and can 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 the getAppSetting method in PostApi class and the getMobileSettings method in PostResource & PostCategoryResource classes
PostApi.php
<?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; } }
Posts/Api/Resource/PostResource.php
<?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 methods, you can re-check the API above and should see that new `post` object is appended to the Core App Setting API
Detail information of each section
Item | 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 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: GET
Screen Setting Parameters
Define 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 |
|
|
Naming Convention of Screen Name on Mobile app
Each module (such as Blog, Event, etc) will have 3 default screens: Module Home Screen, Module Detail Screen, Module Listing Screen
Screen Name | Naming Convention |
Module Home Screen | "module" + app name Ex: moduleBlog |
Module Detail Screen | "detail" + app name Ex: detailBlog |
Module Listing Screen | "listing" + app name Ex: listingBlog |
Here is the sample API response for Blog
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 implementing 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 a child of the 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 will 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
Key | Description |
component | Component name of the block, this value should be: |
title | 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: |
limit (optional) | Default 4, defined how many items show on the block |
If you don't want to support ads on a screen, you should add property "no_ads" => true to that Page Setting
$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 pre-defined components used to render layout on mobile and controlled by Core Site Setting API
Components for module home page, module search page
List of components are defined to render layout on module Home page and module Search/listing page
Component Name | Description / Render | Recommend section | Supported parameter | Note |
---|---|---|---|---|
module_header | The Header section for module home page | header |
| Search bar, right buttons controlled by Core App Setting API |
simple_header | The Header section for listing page | header |
| 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 |
| Items type controlled by Core App Setting API |
smart_tabs | List of items related to current module (separated by tab component) | content |
| 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 page
Component Name | Description / Render | Recommend section | Supported parameter | Note |
---|---|---|---|---|
item_header | The header section for module detail page | header |
| 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 pages
Component Name | Description / Render | Available section | Supported parameter |
---|---|---|---|
banner_ad | Admob Banner |
|
|
simple_list_block | List of limit items basing on parameters |
|
|
Components for specific pages
List of components are defined to render some special blocks that currently only apply for some specific pages
Component 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 |