On this page

The Settings tab

The Settings tab is used to configure general settings for app (app type, permissions and listing style), it is also used to create custom fields to store app settings for each site.

General Settings

App Type: determine whether the app is a

  • Instant App: app built by App Builder with no direct access to PHP/SQL, can be deployed instantly
  • Remote App: uses remote API to process app records.
  • Standard App: uses PHP to process app records, app needs to be reviewed and approved before it can be activated.  
  • (Remote) Widget app: produces widget that can be attached to a specified position on other app's record(s). Widget can be generated by a remote API or PHP.

App Handler: in the case of Remote App/Widget, an API endpoint can be specified to handle data.

Screenshot: specify a screenshot or an icon for the app which will be shown with the app when it is listed on SiteGUI Appstore or each Site's activated Apps.

Listing Style: choose how to display multiple records when accessing the app's main page.

  • Table: display each record as a row in a table
  • Grid: display each record as a card in a grid
  • Kanban: group records by a property (e.g: status) and display them in kanban columns

Tick Button's Action: enter URL encoded params to update an app's record when it is ticked. Leave blank to disable Tick button. One example for Tick button is a Todo app where you can tick a Todo entry to mark it as Done. Tips: when a record is ticked, the frontend will send the params to the server, if it is successful, the frontend will attempt to move the record to a Kanban board associated with the value of the first param (Kanban view only).

Menu Category: which category the app should belongs to.

App Permissions

Every app has three stakeholder groups: Client, Staff and Guest (public, non-registered user). Clients are the main users of the app who can create a new record and view their own records (created by or on behalf of them), Staff are those who can manage records and Guest can view all published records if the app allows it. SiteGUI app can be built to serve different stakeholder groups, including guests/non-registered users (Documentation app), Clients (Support Ticket Tracker app), both registered and non-registered users (Feature Request app) and Staff only (Task Management app). Choosing suitable App Users for each app makes this possible.

App Users: if the app is built for Customers to use, besides enabling Client Permissions (Read/Write/Delete), developers should also include Client as App Users in order to make the app accessible at the Customer Portal at https://my.company.domain/account, this is where Customers can access all the apps made available for them. If App Users does not include *Client*, Customer access will be denied. Similarly, if the app is built for Guests to view published records, developers should include Guest as App Users in order to make the app viewable at https://company.domain/app_name, this is where Guest can access all the app's published records. If the Client Read permission is not enabled, Guest access will be denied. Please note that for App Users, Client strictly refers to Customers, only include Client as App Users if you do want Customers to access the app at the Customer Portal.

Publish Client's Post Automatically: app records need to be published (App Users should include Guest and Client Read permission must be enabled) before unregistered users can view them on the website (e.g: https://company.domain/app/app_name/record_slug). Normally, Clients do not have permission to publish records but for some apps, it is not necessary to moderate records created by Clients. By enabling this feature, new records created by Clients are published automatically without having to wait for Staff to do that. 

Record Versioning: this enables versioning for published records. When a staff with no publish or management privilege tries to save an already-published-record (public access can be blocked by not including Guest in App Users), a new version of the record is cloned instead, allowing the staff to make changes to the cloned version without changing the original one. Later, the staff may choose Request Merge to request privileged staff to update the original version with their modified version. For privileged staff, they can replace the original version with any version by choosing Replace The Original Version With This Version when viewing the choose version. Please note that versioning just clones the record content only, it doesn't clone the record's subapp entries or the original record's relationship (menu, widget etc). When updating, versioning will preserve the original record's ID, slug, view, public data and subapp entries/relationships. The Request Merge action should be handled by Automated Actions to notify privileged staff or request their approval when the event occurs (when the poster is not a supervisor but requesting to publish the record)

Staff Permissions: if you don't want all Staff to access or manage app records, you can always use Staff Permissions to limit access to certain staff group. By specifying Create permission, you'll limit creating and listing records to those staff having that permission. Only those having specified Manage permission are allowed to manage app records, other staff will not be able to manage them. This is app level permission, meaning that it applies to all app records.

Client Permissions: if your app allows only certain customer group to access or manage app records, you can use Client Permissions to limit access to certain customer group. By setting Read or Write permission to a Group::Group_Name, you'll limit listing/reading or creating/updating records to those customers in the Group_Name group. For apps without this Read permission set, customers can list/read only app records they created or are assigned to them. However for apps having this Read permission set, customers in the associated group will be able to list/read any unprotected app records including records created by staff or other customers.

Page Level Permission: page/record level permission applies to each individual record staticly or dynamically. If a static permission (e.g: Product::create) is specified then only staff having that permission (besides app level permission) can read the record. In some situations, the permission must be set dynamically depending on another value chosen when creating the record. In that case, dynamic mapping the value to the permission is needed. The mapping table cannot be specified when the app is built but when the app is configured for each site. The Per Site Settings section below will help setting up the mapping table by creating a config fieldset to let Site Managers to enter 1 to 1 mapping of values to permissions when configuring the app.

Here is an example to illustrate how dynamic permission mapping works: a Ticket Tracker app has a custom config fieldset that includes department and permission as the properties and dynamic mapping is set to depend on the department's value. A company using this app has three departments: Sales, Billing and Tech. Sales staff has permission Product::create, Billing staff has permission Invoice::create and Tech staff has permission Role::Tech exclusively. When configuring Ticket Tracker app for this company, we can enter department Sales and permission Product::create to create a mapping, do the same for Billing and Tech. When the app is used and the Customer chooses Sales department, the dynamic mapping will kick in and select the associated
 permission which is Product::create  for that record. As the permission is set, besides the Customer creating that ticket, only Sales staff can read the ticket because they have that permission.

Per Site Settings

As app is built to use on multiple Sites, some Settings need to be specified by Site Managers rather than the app developer. App developers may create custom Settings fields for storing app settings for each site. SiteGUI App Builder has many predefined fields such as 

  • Text/Textarea: text input field
  • Lookup: a lookup field that returns the IDs of matching object name (e.g: a Page name, a Product name, a User name). Supported objects are: creator (user), staff, group (role), page, collection, menu_id, product, variant, sku, app name (e.g: feature_request).
  • Select/Radio: a field that consists several options to choose. Options can be pre-defined or can be looked up by specifying From::lookup as the first option, object (creator, page, permission) as the second option and optionally the value to lookup as the third option.  
  • File/Image: a file/image field that allows uploading of file/image or selecting a file/image from File Manager
  • Checkbox: a checkbox field
  • Radio Hover: a radio field that shows the selected or default option and upon mouse hovering, shows other available options to choose (e.g: an emoji selection)
  • Rating: a clickable/slidable field that consists 5 stars to allow choosing a rate out of 5. Half-star or a rate of 4.5 is also supported.
  • Password: a password field that can be used to store sensitive credentials, the value will be encrypted
  • URL/Email/Tel/Color: standard input fields
  • Country: a dropdown field for selecting a country 

To create a custom field, just choose a field type, name (id), label (display name) and description (optional) for it. You can also set field visibility, a default value, whether the field is required or optional or accepting multiple values (select and lookup field only), and specify options if field supports them.

For field that accepts multiple text-input values (not selectable values), it should be added as a fieldset field. For example: an app allowing Site Managers to specify their own statuses can create a custom field named status and make it a fieldset field. When configuring the app, Site Managers can add multiple statuses as they like. Multiple fields can be added to a fieldset if they all need multiple values, the values for each field will be consolidated to remove duplicated entries from the list of values. 

If a field named permission is added to a fieldset, its value can be used for Page Level Permission's dynamic mapping if Page Level Permission is set to map to another field in the fieldset. For example a field named department is in the fieldset and dynamic mapping is set to department, then when a new records is created, depending on the value of department (department should be an input field as well), the associated permission will be chosen for that record.

Oauth Settings

If your app connects to an external API resource, you may want to specify some fields to store access tokens for each site. Those fields may be filled manually by Site Managers or you may create an Oauth field to let Site Manager click to authorize and have those fields filled automatically. To configure Oauth, choose Oauth as the field type, set Name to 'oauth', set Label to the name of the API resource e.g: Connect with Google and set the options as follows:

  1. Option 1 should be set to the Authorization URL of the given Oauth provider e.g: https://accounts.google.com/o/oauth2/auth?client_id=hardcoded_id&response_type=code&access_type=offline&include_granted_scopes=true&state={state}&redirect_uri={redirect_uri}&scope= https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send. You may hard code the client_id and use placeholders (e.g: {state}) for other parameters, SiteGUI will replace those placeholders by actual values. Please note that {state} is required and must be set by SiteGUI in order for the process to work properly. If the Oauth provider does not return state to our redirect_uri, you may include it in the redirect_uri like this: ...&state={state}&redirect_uri={redirect_uri}%26state={state}&scope=...

  2. Option 2 should be set to the Access Token endpoint of the Oauth provider, this endpoint is where access token is provided after Authorization is given e.g: https://oauth2.googleapis.com/token

  3. Option 3 can be used to set the parameters for querying the Access Token endpoint above e.g: client_id=hardcoded_id&client_secret={client_secret}&code={code}&grant_type=authorization_code&access_type=offline&redirect_uri={redirect_uri}&extra_param={extra_param}. Which parameters are required should be instructed by the Oauth provider, normally you will need the client_secret and the authorization code which can be filled automatically using placeholders. If {extra_param} is specified, it will be replaced with the value of extra_param returned by the Authorization URL. Please note that parameters and their values (except placeholders) should be URL-encoded if they contain special characters. If no parameter is required, please do set this option to an empty JSON object i.e: {}

  4. Option 4 can be used to set special headers for querying the Access Token endpoint. By default 'Content-Type: application/x-www-form-urlencoded' header is used to perform request to the Access Token endpoint, if the given Oauth provider requires different headers, you may specify them here, different headers should be separated by "&" e.g: "Content-Type: application/json&secret_key:{client_secret}&another:key". Please change option 3 to a json encoded value if the header is set to "Content-Type: application/json"

  5. Option 5 is optional, should be specified when you need to retrieve additional information automatically from the Oauth provider after successfully authorized and connected (e.g: https://www.googleapis.com/oauth2/v3/userinfo). Please note that you do not need this to retrieve and save the access_token and refresh_token. The information could be the name, ID of the authorized user, to save them automatically you should set other settings fields' default value to {oauth::flatten_oauth_response_property}, for example: create a text field named 'email' and set its default value to {oauth::level1__level2__level3}, this value will be replaced by the value of $response_object->level1->level2->level3 in the retrieved information object (which is flatten i.e: https://sitegui.com/docs/the-actions-tab#flatten-array).

  6. When option 5 is specified, you may use option 6 to set the parameters for querying the information endpoint, this is similar to Option 3 but you have a new placeholder {access_token} to specify the access token.

  7. When option 5 is specified, you may use option 7 to set the headers for querying the information endpoint, this is similar to Option 4 and you also can use {access_token} to specify the access token.

  8. SiteGUI normally uses POST to send API requests, if the connection requires a different method such as GET, you can use option 8 to specify that method

Finally, if you want to store the secret (client_secret) for your app securely (instead of hard coding), you may enter the secret as the default value for the Oauth field, this value will be stored and retrieved automatically when your application needs it. This needs to be done one time only and is effective immediately for Instant Apps, for normal Apps, the value will be saved when the App is configured for the first time.