PX Atlas draws interactive maps in the Joomla administrator: layers of points, lines and shapes on OpenStreetMap, Google Maps or your own picture, shown on the site with a module. Set it up in Components → PX Atlas.

PX Atlas draws interactive maps in the Joomla administrator and shows them on your site. A map has layers, and layers hold points, lines, polygons, circles and rectangles, each with its own style and content. The map can sit on OpenStreetMap, on Google Maps, or on your own picture such as a floor plan or a park map. Use it for store locators, city guides, delivery zones, hiking trails, venue and campus maps. PX Atlas is free.

  • Visual editor: layers and objects on the left, the map on the right; draw, drag, reshape or type exact positions.
  • Five object types: points, polylines, polygons, circles and rectangles; up to 200 layers and 5,000 objects per map.
  • Markers: pin, point, square, letter badge, Font Awesome icon or your own picture, in any colour and size.
  • Content: a heading, formatted text, an image and a button, shown as a tooltip, popup or side panel, on click or hover.
  • Layers for visitors: a layer control, layers hidden at load, and zoom ranges that show detail only when zoomed in.
  • Image maps: your own JPG, PNG or WebP picture from the Media Manager, with positions in pixels.
  • The Joomla way: a module for any position, {loadmoduleid} in articles, Joomla permissions, languages, keyboard access.
Try it first: the PX Atlas demo has six maps (a city guide, a store locator, delivery zones, a hiking trail, a floor plan and a festival map) on a plain Joomla 6 site.

System requirement

  • Joomla 5.4 or Joomla 6
  • PHP 8.1 or later
  • A MySQL or MariaDB database

Install the package

  1. Download pkg_pxatlas-1.0.0.zip from the PX Atlas page (a free thepixel.dev account is enough).
  2. In your Joomla administrator go to System → Install → Extensions and upload the file.
  3. Open Components → PX Atlas.

The package installs the component (the editor), the PX Atlas module (the map on the site) and the plugin Console - PX Atlas (command line). New versions show up in System → Update → Extensions; installing a newer package over the old one keeps your maps.

Uninstalling the package deletes all maps, layers and objects. The pictures you chose in the Media Manager stay. Back up your database first.

Components → PX Atlas lists your maps with their 1title and a Preview link, and their 2type and provider. Search, filter by status or type, publish, unpublish and trash maps the usual Joomla way. Deleting a map from the trash also deletes its layers and objects.

PX Atlas list of maps
Components → PX Atlas.

New asks what kind of map you want: 1Geographic map (OpenStreetMap or Google Maps) or 2Image map (your own picture). The type cannot change once the map has objects.

New map window: geographic map or image map
The New map window.

Details

Give the map a Title, then open the Details tab:

  • 1Provider: OpenStreetMap or Google Maps (see Map providers).
  • Center Latitude / Longitude and 2Initial Zoom (0 = the whole world, 22 = a building). You can also set the start view in the editor.
  • Minimum / Maximum Zoom: how far visitors can zoom out and in; empty uses the provider's limits.
  • Width (1%–100% or 100px–10000px) and Height (100px–5000px or 10vh–100vh).
  • Layer control and its position: a button with the list of layers for visitors (shown when the map has two or more published layers).
  • Status, Language and a Description for your own notes.
Details tab of a geographic map
The Details tab of a geographic map.

The Map Editor tab is where you draw. 1Layers and their objects are on the left, the map on the right. Above the map are 2the tools Select, Point, Rectangle, Circle, Polygon and Polyline, and on the right Preview content, Full screen and 3Set start view: pan and zoom, click it, and that is the view visitors get when the map loads.

The PX Atlas map editor
The Map Editor tab.

Hold Ctrl (⌘ on a Mac) and scroll to zoom the map; a plain scroll moves the page. A dark bar on the map explains the active tool, and a status line under it shows the cursor position, the zoom and how many layers and objects are visible. Changes are stored with Save or Save & Close; Close with unsaved changes asks "Leave without saving?".

Layers

Layers group objects, for example Sights, Food & coffee or a walking route. A map needs a layer before you can draw.

  • + Layer adds one. Each layer row has buttons to hide it in the editor (the eye, only for you), Order layers, Go to … (fits the map to its objects) and Settings of ….
  • In the layer settings: Layer name, Published, Colour (objects use it unless they have their own), Visible when the map loads and a zoom range.
  • Order layers by dragging, or with the move buttons and Alt + arrow keys.
  • Delete layer asks whether to delete its objects or move them to another layer.
  • The Filter… box and the All types list narrow the list.

Drawing objects

ToolHow to draw
PointClick the map.
PolylineClick to add points; double-click, press Enter or click Finish to end. Undo point removes the last one.
PolygonClick to add corners; click the first corner, double-click or press Enter to close it.
RectangleDrag, or click two opposite corners. Hold Shift for a square.
CircleDrag from the centre, or click the centre and then the edge.

After drawing you pick the layer, and 1the object's settings open on the left while 2the object is selected on the map. With Select you drag an object to move it and its white handles to reshape it, or type exact values in Position (paste "38.7139, -9.1335" into Latitude to fill both boxes). You can also duplicate, delete (Delete key), reorder objects inside a layer and move them to another layer.

Settings of a selected point in the editor
A selected point and its settings.

Style

A point is a Pin, Point, Square, Badge (1 or 2 letters or digits), Icon (search the Font Awesome icons of your site, for example coffee, bus or parking) or Image (a picture from the Media Manager). Set its Colour ("Layer colour" follows the layer) and Size (S, M, L or a custom size). Lines have width, opacity and a solid, dashed or dotted line style; polygons, circles and rectangles also have a fill colour and fill opacity.

Marker style: kind, colour, size and icon
Style of a point.
Shape style: border and fill
Style of a polygon.

Content

What visitors see when they open an object: a Heading (empty uses the object's name), Text written in Joomla's editor (Edit text), an Image from the Media Manager and a Button with its link (a page of your site, or https://, mailto: or tel:). An object without content is shown but cannot be opened.

Interaction

Display as chooses a Tooltip (a small label), a Popup (a card next to the object) or a Side panel (a card at the side of the map). Show on is Click or Hover (a tap on touch screens). Switch the title and the image on or off, and choose whether a click on the map closes the box. On small maps, popups and side panels open as a sheet at the bottom. Preview content in the toolbar shows the selected object's box as visitors see it.

Content of an object: heading, text, image and button
Content.
Interaction: tooltip, popup or side panel, on click or hover
Interaction.

A layer or an object can show only between two zoom levels, so details such as water taps or bus stops appear once the visitor has zoomed in. Fill From zoom and To zoom in the Zoom range section of the layer or object settings. In the editor the layer gets 1a badge such as Zoom 14–17, and the layer control on the site lists it dimmed with "Visible at zoom 14–17" until the visitor zooms in.

A layer with a zoom range badge in the editor
The "Water, trains and views" layer shows from zoom 14.

An image map shows your own picture instead of a street map: a floor plan, a drawing, a campus or festival map. Choose Image map in the New map window, type a title and pick the Base image on the Details tab (a JPG, PNG or WebP file in the images folder). After saving, the form shows its size, for example "1600 × 1000 px · PNG · 100 % at zoom 3". A new image map can only be published once it has a base image.

Details tab of an image map with the base image
The Details tab of an image map.

You draw exactly as on a geographic map, but positions are pixels counted from the top-left corner of the picture (X, Y, Radius (px)…), and objects stay inside the picture. The image map has its own zoom scale; set the Initial view, start, minimum and maximum zoom on the Details tab or with Set start view. Background colour fills the space around the picture and Attribution adds a credit in the corner.

Drawing rooms on a floor plan in the editor
A polygon room on a floor plan.

To change the picture, select another one and save. A picture of the same size keeps everything in place; one of the same shape but another size can rescale the objects (tick Rescale objects to the new size); a picture of another shape needs a new map. Keep pictures reasonably small: very large images are loaded whole by the visitor's browser, and their hidden photo data (such as GPS) stays in the public file.


The provider settings are in Components → PX Atlas → Options.

OpenStreetMap

Works without any setup. The public OpenStreetMap tile service is meant for light use (see its tile usage policy); for a busy site, enter the Tile URL, Attribution, Attribution link and Maximum tile zoom of a commercial tile provider or your own tile server on the OpenStreetMap tab. A value that is not valid falls back to the OpenStreetMap default, and the attribution is always shown.

PX Atlas Options, OpenStreetMap tab
Options → OpenStreetMap.

Google Maps

  1. In the Google Cloud console, create or choose a project and enable the Maps JavaScript API.
  2. Create an API key and restrict it to HTTP referrers (your site's address) and to the Maps JavaScript API. The key is public, so these restrictions protect it.
  3. Paste it into Browser API Key on the Google Maps tab of the Options and save.

Without a key, Google shows its maps in development mode. If Google refuses the key or does not answer, the map says "The map could not be loaded." and the editor points to the key. Google bills your own account; PX Atlas only passes the key on.


  1. Go to Content → Site Modules → New and choose PX Atlas.
  2. Pick the 1Map. 2Width, Height and Layer control can override the map's own settings for this module.
  3. Choose a Position, the Access level (it decides who sees the map) and the pages in Menu Assignment, then save.
The PX Atlas module settings
The PX Atlas module.

To put a map inside an article, create the module without a position and type {loadmoduleid N} in the article, where N is the module ID. Several maps can share one page, and one map can be used by several modules. A map that is missing, unpublished or trashed shows nothing at all.

What visitors can do

  • Zoom with the buttons, a double-click, or Ctrl + scroll; on touch screens, move and zoom the map with two fingers (one finger scrolls the page).
  • Click, tap or hover on objects to open their tooltip, popup or side panel, or reach them with Tab and open them with Enter.
  • Switch layers on and off with the layer control.
A popup with a photo on an OpenStreetMap map
A popup with a photo and a button.
A store locator with a side panel
A side panel on a store locator.
The layer control open on the site
The layer control: "Tram 28" starts hidden.
A floor plan image map with a side panel
An image map.
A map on a phone with the content as a bottom sheet
On a phone.

PX Atlas uses Joomla's permissions (Options → Permissions) for the whole component: Access Administration Interface, Create, Edit, Edit Own (maps you created), Edit State, Delete and Configure Options. The editor needs Edit, or Edit Own on your own map. Every save is checked on the server with Joomla's form token. Maps have no access level of their own: the module's Access decides who sees them.


The plugin Console - PX Atlas adds three commands to Joomla's command line:

  • php cli/joomla.php pxatlas:map:export <id> [--output=map.json] writes a map as one JSON file.
  • php cli/joomla.php pxatlas:map:import map.json --user=<username> [--map=<id>] [--dry-run] creates a map from such a file, or replaces the layers and objects of an existing map.
  • php cli/joomla.php pxatlas:module:create --map=<id> --user=<username> makes a module for a map and prints the {loadmoduleid N} text.

Add --json for one JSON answer. The commands run with the rights of --user and the same checks as the editor. The file format, every value and complete examples are in administrator/components/com_pxatlas/AI.md, written for AI agents and scripts. The PX Atlas demo is built this way.


  • Limits: 200 layers and 5,000 objects per map, 2,000 points per line or polygon, 4 MB per save.
  • Not a GIS: no address search, routing or live tracking. The editor has no undo.
  • The map type is fixed once a map has objects; make a new map for the other type.
  • Nothing shows? Check that the map, its layers and objects and the module are published, the module is assigned to the page and its Access includes the visitor, and Content - Load Modules is enabled when you use {loadmoduleid}.
  • A Google map in development mode needs an API key (see Google Maps).