xbMaps component Documentation. This primarily deals with the admin side of managing the data. Presentation on the front-end site is straightforward with user interaction for searching filtering and sorting the data using standard Joomla facilities.
(click on the screengrab images to enlarge)
Contents:
- Introduction
- Installation
- Options
- Data Structures
- Categories and Tags
- Admin views
- Site Views
- Maps and Map Views
- Markers
- Tracks and Track Views
- Searching and Filtering
Introduction
xbMaps provides views of maps with optional gpx tracks and markers for points of interest. For basic details see the info page.
Installation
Install in the usual way - by downloading the zip file from here and uploading it to Extensions-|-Manage on your site admin, or from the direct link.
Immediately after installing it is recommended you review the Options (button on top right of toolbar for xbMaps Control Panel) and set defaults values as required.
Uninstalling
Uninstall will remove all xbMaps data tables from the database.
Any images (eg markers) will not be removed by uninstall. By default a folder /images/xbmaps/markers is created and this will remain until you delete it manually. Track gpx files are also not removed on uninstall. They normally reside in /xbmaps-tracks although this can be changed in configuration options.
Setting Options
There are a large number of global parameters - you should check that the default settings match your requirements or you may get unexpected results.
The xbMaps global options page has seven tabs
General options
Map Options
Marker Options
Codes Options - currently there are only two options here
Firstly a 'beer' code to remove the CrOsborne footer at the bottom of every xbMaps page for the price of a bottle of beer in Cornwall (which will probably be less than your time spent working out how to hack the code to remove it without thanking me for producing the component by joining me for a bottle of beer (or a nice cup of tea and a bikki if you don't drink alcohol). Click the link at the bottom of any admin page to use PayPal to donate at least £4.
Secondly your What Three Words API key if you wish to enable use of what3words for marker locations. Visit https://what3words.com/select-plan to get your free API key.
Further API keys may be added on this page as required for facilities in future versions of xbMaps (eg to use some paid-for tile sets)
Metadata Options - similar to the Joomla article metadata permissions, these allow you to modify the default metadata (<meta> tags),
Permissions - these are the standard Joomla permission options for a component
Data Structures
xbMaps adds five new tables to the database to store the information
- #__xbmaps_maps maps data and configuration
- #__xbmaps_markers marker data and configuration.
- #__xbmaps_mapmarkers link table for many-to-many map-marker relationship
- #__xbmaps_tracks track data and configuration
- #__xbmaps_maptracks link table for map-track many-to-many relationship. The track colour can also be set in this table and will override the default colour set in the track parameters.
Standard Joomla fields for publishing info are in all item tables.
A lot of configuration data for items is held in the params json field.
Minimal required fields are:
- #__xbMaps: Title, Type,
- #__xbpersons: Lastname (some people only have one name)
- #__xbreviews: Title, Rating, Book link.
Optional fields are:
- #__xbfilms: Subtitle, Summary (brief, plain text), Synopsis (rich text), Poster Image (filename),
Setting, Release_year, Studio, Country, Original_lang, runtime, Colour, aspect_ratio, Format, filmsound, External links, Category (defaults to Uncategorised), Admin note - #__xbpersons: Firstname, Portrait (filename), Nationality, Year born, Year died, External links, Category (defaults to Uncategorised), Admin note
- #__xbreviews: Summary (brief plain text), Review (rich text), Reviewer (defaults to username), Date read, Format read, Edition read, Category (defaults to Uncategorised), Admin note
Standard Joomla fields for all items are:
- id, category_id, asset_id, alias, state, access, created, created_by, created_by_alias, checked_out, checked_out_time, modified, modified_by, metadata, ordering, params
xbMaps does not currently implement the Joomla version control system. It seems unnecessary as items are fairly unlikely to need revision apart from living authors' biographies
Categories and Tags
xbMaps uses the built-in Joomla support for Categories and Tags. These can be applied to all items. Categories are specific to the xbMaps component, Tags may be shared with articles and any other components using the Joomla tagging system.
Four default categories are provided - "Uncategorised", "Maps", "Markers", and "Tracks" others can be added ad-lib. A default category can be set for each type of item (the default default for all items is "Uncategorised")
Categories and Tags can be enabled or disabled globally for each type of item.
Tags can be freely created when creating or editing items on the admin side. Joomla does also allow for tags to be arranged in a hierarchy using the built in Tags component,
Admin views
Screenshots of the Admin pages can be found on the demo page (links below).
Additional notes are provided here on the parameters available for each type of item.
there are 5 types of site views.
for each type there are two views a list view and a detail view. The links above demonstrate each type of list view. Click on an item title in the list to see the corresponding item view.
Front-end views only show published items. Many elements can be shown/hidden or have content type set either globally, or in the item or menu parameters.
The list scan be sorted by some columns by clicking on the column heads
Optional search and filtering tools are available on front-end list views.
Maps have various optional controls such as search, zoom, download as image. Clicking on a marker or track ion a map will bring a popover with additional information.
