API: System: Configuring the Framework

Trott edited this page Oct 30, 2011 · 6 revisions
Clone this wiki locally

The UCLA Mobile Web Framework has a series of configuration files for enabling and customizing the behavior of your instance. All of these files can be found in /config. The following sections outline the configuration options available in each file respectively.

General System Configuration (global.php)

The file global.php is the only configuration file that must be populated for a new installation of the framework to function. The first set of entities specify site specific paths:

  • site_url (required) - The url of the MWF installation. This should be the web-accessible address for the root directory, including protocol(http/https).
  • site_assets_url (required) - The URL of assets directory of the MWF installation. This should be the web-accessible address for the assets directory, including protocol(http/https).
  • site_nonmobile_url - This parameter specifies a URL that non-mobile users will be redirected to when they visit the mobile site. If set to false, desktop users will not be redirected when they visit the mobile site.
  • full_site_url - This parameter specifies a URL for the "View Full Site" link at the bottom of all mobile pages. If set to false, the link will not be displayed.
  • help_site_url - This parameter specifies a URL for the "Help" link at the bottom of all mobile pages. If set to false, the link will not be displayed.

Note: All paths specified in the above parameters should NOT include a trailing slash

In addition to the global pathing configuration options, global.php has a set of options for the way the site is presented. This includes cookie_prefix which can be set to add a prefix to all cookies set by the framework. The front-end presentational configuration options include the following:

  • appicon_img - The URL of an image that will represent your app on the homescreen of iOS devices. This icon is used when iOS users choose the "Add to Homescreen" option while browsing your mobile site. An image in this tag will have default effects applied to it, including rounded corners and a gloss overlay.
  • appicon_img_precomposed - The URL of an image that will represent your app on the homescreen of iOS devices. This option is identical to the previous, but an image specified here will not have the gloss overlay applied to it. This is useful for icons that are designed to be displayed exactly as-is on the homescreen.
  • appicon_allow_disable_flag - If set to false, this option will make it so that the framework appicon will always be present. If true, a content provider will be able to pass the no_appicon or no_icon flags when including js.php to disable the framework appicon.
  • back_to_home_text - Text to be displayed at the bottom of framework apps or sub-navigation menus to get back to the mobile homepage.
  • copyright_text - The copyright text to be displayed in the footer of every mobile page.
  • header_home_button - The URL of an image to be displayed in the header of all framework mobile pages on the left hand side.
  • header_home_button_alt - Alternate text for the header home button image.
  • title_text - Text to be used for the title of mobile framework webpages.

Mobile Front Page Configuration (frontpage.php)

An institution can customize their mobile site's front page menu by modifying the menu configuration setting in the frontpage.php config file. The value for this setting is a three-tiered array. The top level items in the array correspond to submenus on the homepage. The default element in this top level array corresponds to the menu displayed on the homepage of the framework. The value for each top-level element should be an array of menu items to be displayed in the corresponding (sub)menu with each menu item itself represented by an associative array of attributes for the menu item. The available attributes are as follows:

  • name - The name for the menu item that will be displayed for the item in the menu.
  • id - The HTML "id" attribute that will be applied to the <li> entity representing the menu item. This makes it easy to specify icons for each menu item.
  • url - The URL that should be launched upon selection of the menu item. If you want a menu item to go to a submenu, set this attribute to index.php?s={SUBMENU_NAME} where you replace {SUBMENU_NAME} with the name specified as the array key for the desired submenu.
  • restriction - A string that corresponds to a function in the User_Agent class that will be called to determine whether or not to display the link. This can be used to make menu items that will only be displayed on certain devices. For example, a value of is_iphone_os will restrict the menu item to be displayed on iOS devices only.

System Stylesheet Configuration (css.php)

The css.php configuration file provides a mechanism by which an institution can define a directory of custom stylesheets that will overwrite the default MWF styles. By setting the custom option to a string, the framework will look for a directory with this name inside the /root/assets/css directory, and if found, will apply the contained stylesheets after the default framework stylesheets, effectively overwriting any specified styles. If an array is provided, the framework will look for multiple directories, and load them in the same order in which they appear in the array. (CSS definitions from files listed later in the array will take precedence)

Analytics Configuration (analytics.php)

The analytics.php configuration file provides an option for institutions to set a Google Analytics identifier that the framework will use to embed Google Analytics code in each page that leverages the framework. If no Google Analytics identifier is specified, Google Analytics code will not be produced by the framework.

Accessing Configuration Settings

The Config class offers a static accessor method to retrieve the values of configuration options. This class is available in any page that includes /root/assets/config.php and configuration options can be acquired with the following call: Config::get('{NAME_OF_CONFIG_FILE', '{NAME_OF_OPTION}');. Simply specify the config file where the desired option resides, and the name of the option, and the value will be returned.