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

1. Core App Setting API: This API collect all settings of each app then build the display layout
2. 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 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 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: GET

  Screen 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:

  Page Name	Screen ID
  Module Home Page	module
  Module Detail Page	detail
  Module Search Page	listing

  If a screen is defined, Admin can config to show Ads via AdMob on that screen in the specific section.
  
  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

   

  Key	Description
  component	Component name of the block, this value should be: ScreenSetting::SIMPLE_LISTING_BLOCK
  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: GET url/restful_api/mobile/<resource_name>?access_token=token&<query> to get data
  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 a list of pre-defined components use to render layout on mobile 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	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

• 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:

• 
  
  • 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
    
• 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:

• 
  
  • 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
    
• 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 page

  Component 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

• 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 pages

    Component Name	Description / Render	Available section	Supported parameter
    banner_ad	Admob Banner	top

• 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

• 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 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