README

Module  : @TITLE@
Version : @VERSION@
Author  : @AUTHOR@

@DESCRIPTION@

The module can also be used to plot all known user locations on a map.
You will have to create a link to this user map yourself. See "Customization"
below for information on how to link to this user map.

For running this mod, you need Phorum @REQUIRED_VERSION@ or later. It will not
work for earlier versions of Phorum.


Contents:
1. Install
2. Upgrade
 2.1 From a version, prior to 2.0.4
 2.2 From a version, prior to 2.0.0
3. Customization
 3.1 Module templates
 3.2 User control center
 3.3 User profile screen
 3.4 Message read pages
 3.5 Width and heights of the maps
 3.6 Linking to the user map


1. Install
----------

- Unpack the archive;

- Move the directory "@MODULE_ID@" to the directory "mods"
  within your Phorum installation;

- Login as administrator in Phorum's administrative interface and
  go to the "Modules" section;

- Enable the module "@TITLE@".

- Configure the module through the module's settings page.


2. Upgrade
----------

 2.1 From a version, prior to 2.0.4
 ----------------------------------

  Please note that some new files have been added to the module template
  directory mods/@MODULE_ID@/templates/emerald/. If you did not create a
  custom template directory next to that emerald directory, then you are fine.
  If you did create a custom template however, you will have to make sure
  that your custom template contains all templates from the emerald directory
  (by simply copying over the missing files).


 2.2 From a version, prior to 2.0.0
 ----------------------------------

  The recommended way for upgrading from versions prior to 2.0.0 is:

  - Login as administrator in Phorum's administrative interface and
    go to the "Modules" section;

  - Disable the module "@TITLE@".

  - Delete the directory "mods/@MODULE_ID@" within your Phorum installation
    (but keep of course customized template files if you have those).

  - Move the new "@MODULE_ID@" directory to the "mods" directory.

  - Go to the Modules administration and enable the module "Google Maps".


3. Customization
----------------

 3.1 Module templates
 --------------------

  This module makes use of module templates. If you want to modify the
  templates to make them work better for your site's template, then do
  not edit the template files that were in the module distribution.
  Instead, copy the full directory "mods/@MODULE_ID@/templates/default" to
  "mods/@MODULE_ID@/templates/yourtemplatename" (asuming that your site's
  template is stored as "templates/yourtemplatename") and edit the files
  in the new directory. Phorum will automatically recognize that you have
  created a specific template set to use for your site's active template.

 3.2 User control center
 -----------------------

  By default, the module will add the Google map editor to the user
  profile screen on the "Edit My Profile" page. In case you want to
  fully customize where and how the map is shown inside the control center,
  you can disable automatic displaying of the map tool through the module
  settings. After that, you can edit your "cc_usersettings.tpl" template
  file and use the special template variable {MOD_GOOGLE_MAPS} for
  displaying the map where you want it to appear.

  Here's an example of what could be added to the cc_usersettings.tpl:

  {IF PROFILE->USERPROFILE}
    <dt>{LANG->mod_google_maps->CCIntroduction}</dt>
    <dd>
      <div style="height:400px">
        {MOD_GOOGLE_MAPS}
      </div>
    </dd>
  {/IF}

 3.3 User profile screen
 -----------------------

  By default, the module will add the Google map for the user to the bottom
  of the profile page. In case you want to fully customize the way in which
  the map is displayed on the profile page, you can disable automatic
  displaying of the map through the module settings. After that, you can edit
  your "profile.tpl" template file and use the special template variable
  {MOD_GOOGLE_MAPS} to display the map where you want it to appear. For users
  that did not configure their location through the control center, the
  {MOD_GOOGLE_MAPS} variable will not be set.

  Here's an example of what could be added to the profile.tpl:

  {IF MOD_GOOGLE_MAPS}
    <tr>
      <td nowrap="nowrap" valign="top" style="padding-top: 10px">
        My location:
      </td>
      <td width="100%" valign="top" style="padding-top: 10px">
        In the map below, you can see where I am.<br/>
        <br/>
        <div style="height:400px">
          {MOD_GOOGLE_MAPS}
        </div>
      </td>
    </tr>
  {/IF}

  When the user has stored his position while the module configuration option
  "Retrieve city and country on saving" was enabled, then the country
  and the city name will be available in the profile data. Code for adding
  this info to the profile page could look like this:

  {IF PROFILE->mod_google_maps->city}
    {PROFILE->mod_google_maps->country},
    {PROFILE->mod_google_maps->city}
  {/IF}

  Here's an example that works well with the Emerald template:

  {IF PROFILE->mod_google_maps->city}
    <dt>{LANG->mod_google_maps->Location}:</dt>
    <dd>
      {PROFILE->mod_google_maps->city},
      {PROFILE->mod_google_maps->country}
    </dd>
  {/IF}

 3.4 Message read pages
 ----------------------

  When the user has stored his position while the module configuration option
  "Retrieve city and country on saving" was enabled, then the country
  and the city name will be available in the message data. Code for adding
  this info to the read pages could look like this:

  {IF MESSAGES->user->city}
    {MESSAGES->user->country},
    {MESSAGES->user->city}
  {/IF}

  (note that for read.tpl and read_hybrid.tpl you must use {MESSAGES->...},
  while for read_threads.tpl you must use {MESSAGE->...} instead.

 3.5 Width and heights of the maps
 ---------------------------------

  If you want to influence the width and height of a displayed map, then
  wrap it in a <div> that limits the size. For example:

  <div style="width: 300px; height: 200px">
    {MOD_GOOGLE_MAPS}
  </div>

 3.6 Linking to the user map
 ---------------------------

  For linking to the user map, the template variable
  {URL->MOD_GOOGLE_MAPS_USERMAP} can be used. So a basic link could
  be put in your templates like this:

  <a href="{URL->MOD_GOOGLE_MAPS_USERMAP}">View user locations</a>

  For modifying the user map page itself, you can change the module
  template usermap.tpl (mods/@MODULE_ID@/templates/yourtemplate/usermap.tpl).