Installation

It is recommended that a single instance of the framework be hosted within an institution. This reduces redundant maintenance of the application, as updates to the framework have to occur in only one place, and because it best enables a unified mobile presence among modules that use it, regardless of where the modules are hosted.

This article is thus intended to give a start for service providers (those looking to host a copy of the framework).

Before getting started with this guide, please refer to the System Requirements documentation to make sure that your system is compatible with the Mobile Web Framework. It is the intent of the project to make this as portable as possible, but not all environments are yet fully supported.

Getting the Framework

The framework can be downloaded through two mechanisms, either via a direct download link on Github or via the Git version control system. The latter is recommended, and the rest of this section will intend that this is what you're trying to do. If you are simply going to download a copy of the framework in its entirety, you can bypass this section.

The first thing you will need to do to get a copy via Git is install Git on your server.

Once git is installed, the next step is to "clone" the repository onto your local machine.

If you're looking merely to pull a copy of the repository, this can be achieved as follows:

git clone git://github.com/ucla/mwf.git

If, instead, you're looking to use Git to track both MWF releases and your own changes, you'll want to first initialize your own repository:

mkdir mwf
cd mwf
git init

Once this is initialized, if you have a remote Git repository, you'll want to add a remote as follows:

git remote add origin {YOUR_REMOTE_URL}

Regardless of if you have your own remote repository, or intend to just handle version control locally, the next step is then to configure another remote that points at the MWF central repository:

git remote add upstream git@github.com:ucla/mwf.git

Once this remote is configured, then you can fetch a copy of the MWF itself:

git pull upstream master

If you have your own remote repository, you can then push it up to that remote as follows:

git push origin master

To begin developing your own code, it is recommended at minimum to work in your own branch.

git checkout -b {INSTITUTION_NAME}/master master

At this point in time, you now have your own branch that you're working in and can do your own commits to separate from those of the MWF itself.

Installing the Framework

Once you have a copy of the framework, installation is relatively simple.

It is recommended that you configure your document root to be the root/ directory of the MWF, keeping it isolated from other MWF folders such as install/ and config/.

The first step to installing is to run the following command:

sudo sh install/install.sh

This will create /var/mobile and several directories under it for caching and other framework features that require the file system. These directories are relatively light. If you are not running a system that supports this, or you do not have sudo, you can still use the framework. You'll just need to take a look at the install script and create the directories with proper permissions where you intend to place them.

Once this is done, then you'll want to modify configuration files in config/.

The following two properties in config/global.php must be set:

• site_url The web accessible URL where the front splash page (root/index.php) resides [required]
• site_assets_url The web accessible URL where the MWF assets (root/assets/) reside [required]

Beyond these, config/global.php includes several other properties that may be set. Please refer to inline documentation as to the purpose of each of these properties.

There are several other configuration files you may want to modify to get started:

• config/analytics.php with your Google Analytics key to enable Google Analytics
• config/css.php with a directory name of CSS files that you'll define special for your institution
• config/frontpage.php with the structure of items displayed the front splash page (index.php)
• config/mobile.php if you want to change the maximum screen dimensions for a device to be considered "mobile"
• config/preview.php with the domain under which the preview mode menu should appear

If you did not run install/install.sh, or have configured your directories in a different way, you will also need to set the image cache directory variable cache_dir in config/image.php to be a directory that is writable by the web server user.

Once this is done, you should have a working copy of the framework.

Customizing the Framework

Most institutions seek to apply their own styles to the framework. To do this, you do not need to modify the files under root/assets/css/default. Instead, you should create another directory under root/assets/css and set the variable in config/css.php as this directory name.

Once you have another directory under root/assets/css and have configured config/css.php as such, you can define a basic.css, standard.css and/or full.css within this directory and these definitions will be loaded in addition to the default CSS.

Updating the Framework

The framework is frequently updated with bug fixes, added device support and new features. As such, updating it to the latest stable version is highly recommended. A stable version number is one either with an rc descriptor at the end of the version number, or one with no descriptor at the end.

In the event that you're doing this without Git, you should follow this process:

1. Download the latest copy of the framework into a new directory.
2. Copy your configuration settings to the new directory.
3. Copy your custom CSS folder to the new directory.
4. Copy any modules you have created into the new directory.

However, this is where the power of Git really shines.

Under the Git model described above, you can instead issue the following commands:

git checkout master
git pull upstream master
git checkout {INSTITUTION_NAME}/master
git merge --no-ff master

If there are no conflicts, this process will occur smoothly and without a hitch. If there are conflicts, you can then resolve them as need be. This will not affect any CSS in your custom CSS folder, nor modules you have created or configuration settings you have made. This thus significantly reduces the effort involved in maintaining the latest version of the framework for your institution.

Going a Step Further

If you're interested not only in using the framework, but in developing for it and contributing back to the initiative, this is highly encouraged. The first step to doing this is contacting the MWF core team to get access to the JIRA issue tracking system. Then you can use Git to create a patch file that you can submit to JIRA as a "Merge Request" ticket. If you have a public Git repository, you can also issue a pull request to the develop branch of MWF itself. More information on this is coming soon to the wiki, or available on request in the meantime.