Photo Gallery plugin - ECO Design Studio

Getting started

Mbica adds two things to the WordPress admin menu: Galleries, which are sets of images, and Albums, which are sets of galleries. Both can be placed anywhere on the site with a block or a shortcode, and both get a page of their own.

The lightbox is written in plain JavaScript — no jQuery, no third-party libraries — and the stylesheet and script only load on pages that actually contain a gallery, so pages without one are untouched.

Install and activate

In the admin, go to Plugins › Add New › Upload Plugin and choose mbica.zip. Or copy the mbica folder into wp-content/plugins/ over FTP.
Click Activate. A Mbica item appears in the admin menu.
Open Mbica › Settings and set the defaults every new gallery will inherit. You can change them later, and any single gallery can override them.

How Mbica is organised

Album — “Nairobi launch”

Gallery — “Arrivals”

Gallery — “The talks”

An album holds galleries. A gallery holds images from the media library. Nothing is copied — an image can appear in as many galleries as you like.

Galleries are the working unit. One gallery is one set of images, in the order you drag them into, with its own layout and spacing.

Albums group galleries. An album shows one cover per gallery, and a visitor either opens that gallery in the lightbox or goes through to its page — your choice.

Gallery categories are a shared taxonomy for both. Use them to keep a long list manageable in the admin; they also give you category pages such as /gallery-category/events/ if your theme lists them.

Build your first gallery

Go to Mbica › Add gallery and give it a title. The title is what visitors see on the gallery page and on album covers, so name it for them, not for you.
In the Images box, click Add images and pick from the media library. Upload new files there in the same step if you need to.
Drag the thumbnails to set the order. That order is what the front end and the lightbox follow. The × on a thumbnail removes it from the gallery; the file stays in the media library.
Set the options in the Display box on the right — layout, columns, spacing, thumbnail size, captions, lightbox. Anything you leave alone follows the site-wide defaults.
Set a Featured image if this gallery will sit in an album; it becomes the album cover. Without one, the first image is used.
Click Publish. The Embed box now shows the shortcode for this gallery — copy it into any post, page or widget.

A gallery does not have to be published to be edited, but a draft gallery will not show on the front end and will be skipped inside an album.

Display options

Every gallery and album has a Display box. These are the same choices as the site-wide defaults, applied to this one gallery.

Option	What it does
Layout	Grid crops every image to equal tiles — the tidiest option for mixed material. Masonry keeps each image’s true proportions and staggers them into columns. Carousel puts everything in one row that scrolls sideways, with arrows on either end.
Columns	1 to 8, on wide screens. Columns drop to a comfortable two on tablets and one on phones automatically, so pick the number that suits a desktop.
Space between images	0 to 80 pixels. Zero gives a seamless mosaic.
Thumbnail size	Which registered image size the tiles use — not the size they display at. Larger sizes look sharper on big screens and cost more to load. `medium_large` suits most three-column grids.
Captions	Hidden, Below each image, or On hover. The text comes from the media library caption field.
Open images in the lightbox	On by default. Turn it off and a click opens the full-size file in a new tab instead.
Clicking a gallery cover	Albums only. Either open that gallery in the lightbox without leaving the page, or go through to the gallery’s own page.

Albums

Go to Mbica › Albums › Add album and title it.
In Galleries in this album, choose a gallery and click Add to album. Repeat, then drag the rows into the order you want.
Set the Display options — including what a click on a cover should do — and publish.

Each cover shows the gallery’s title and its image count. A gallery can sit in more than one album, though the breadcrumb on a gallery page will name only the first.

Putting a gallery on a page

The block

In the editor, add the Mbica gallery block. In the sidebar choose whether to show a gallery or an album, pick it from the list, and optionally override the layout, columns, spacing and captions for this one placement. The block previews the real gallery as you edit.

Shortcodes

Use these anywhere shortcodes run — classic editor, text widgets, Elementor’s shortcode widget, or a template with do_shortcode().





[mbica_breadcrumb]

Attribute	Accepts
id	The gallery or album ID, shown in the Embed box on its edit screen.
ids	Attachment IDs, comma separated — renders images directly, with no gallery post needed. Gallery shortcode only.
layout	`grid`, `masonry`, `carousel`
columns	1–8
gap	0–80, in pixels
size	Any registered image size, or `full`
captions	`none`, `below`, `hover`
lightbox	`yes` or `no`. Gallery shortcode only.
limit	Show only the first n images — useful for a teaser row. Gallery shortcode only.
on_click	`lightbox` or `link`. Album shortcode only.

Anything you leave out follows the gallery’s own Display settings, which in turn follow the site-wide defaults.

Gallery and album pages

Every gallery and album also has a page of its own, at /gallery/its-slug/ and /album/its-slug/. Three things happen there automatically, and all three can be switched off in Mbica › Settings.

The images appear below whatever you typed in the editor, so the editor is free for an introduction.
A breadcrumb appears above the title — Main Album » Gallery one — linking back to the album that holds this gallery. A gallery that belongs to no album shows no breadcrumb.
The featured image is hidden, since most themes print it above the content and it would only repeat the first thing in the gallery. It is still used as the album cover and is still there in the admin.

If you would rather place the breadcrumb yourself — inside an Elementor template, say — turn the setting off and use [mbica_breadcrumb] where you want it.

Captions and alt text

Both come from the media library, not from Mbica, so they follow the image everywhere it is used.

Caption is what a visitor reads under the tile and in the lightbox. Write it for someone looking at the picture: who, where, when.
Alternative text is what a screen reader announces and what search engines read. Describe what is in the frame. If it is empty, Mbica falls back to the attachment title, which is usually the filename — worth fixing.

To edit either, open Media › Library, click the image, and fill in the fields on the right. Changes show on the front end straight away.

The lightbox

This is what your visitors get when they click an image.

Action	Result
Click a tile	Opens that image full screen, with a counter and the caption beneath it.
`←` `→`	Previous and next image. Swiping does the same on a phone.
`Esc`	Closes and returns focus to the tile that was clicked.
Click the image	Zooms in, then out again.
Thumbnail strip	Jump straight to any image in the set. Can be switched off in Settings.

Neighbouring images are loaded quietly in the background, so moving through a set feels immediate. The backdrop can be dark or light — that is a site-wide choice in Settings.

Settings

Mbica › Settings holds the defaults every gallery and album inherits, plus a few site-wide choices. Changing a default does not overwrite a gallery that has already been given its own value.

Setting	Notes
Default layout, columns, spacing, thumbnail size, captions	The starting point for every new gallery and album.
Lightbox backdrop	Dark or light, site-wide.
Show the thumbnail strip	The row of small images along the bottom of the lightbox.
Loop from the last image back to the first	Off means the arrows stop at either end.
Show the images automatically on a gallery or album page	Turn off if you place galleries by hand in a page builder template.
Hide the featured image at the top of the page	Applies to gallery and album pages only. Album covers are unaffected.
Show a breadcrumb above the title	Album » gallery, on gallery pages.

Troubleshooting

The gallery is not showing

Check the gallery is published, that it has images in it, and that the ID in the shortcode matches the one in the Embed box. A shortcode typed into a block that is not a shortcode or paragraph block will print as text rather than run.

Images look soft or blurry

The thumbnail size is smaller than the space it is being shown in. Raise Thumbnail size in the Display box — or reduce the number of columns so each tile is smaller.

I changed something and the page looks the same

Clear your caching plugin and your CDN, then reload with a hard refresh. Hosting-level caching is the usual culprit.

A gallery page returns 404

Go to Settings › Permalinks and click Save without changing anything. That rebuilds the URL rules.

The featured image is still at the top of the page

Some themes paint it as a background image on a page header rather than printing it as an image, and no setting can reach that. Your theme’s own options usually have a switch for the page header; if not, ask your developer for a CSS rule scoped to the gallery page.

No breadcrumb on a gallery page

The gallery is not in any album yet. Add it to one, or place the trail by hand with [mbica_breadcrumb].

The colours do not match the site

See below — the whole plugin re-skins from five values.

For developers

Re-skinning

Every colour in the front-end stylesheet resolves from five custom properties declared at the top of assets/css/mbica.css. Override them in the theme rather than editing the plugin, so updates do not undo the work.

:root {
	--mbica-evergreen: #12352c; /* veils, carousel controls */
	--mbica-ink:       #14161a; /* text */
	--mbica-paper:     #f5f2ea; /* light lightbox backdrop */
	--mbica-brass:     #b4894a; /* links, focus rings */
	--mbica-sage:      #c9d6cb; /* quiet surfaces */
}

Filters

Filter	Use
`mbica_hide_featured_image`	Whether to suppress the theme’s featured image on a gallery or album page. Passed the setting and the post ID.
`mbica_show_breadcrumb`	Whether the breadcrumb is inserted above the title.
`mbica_breadcrumb_trail`	The ancestor steps, each an array of `title` and `url`, before the current page is appended.
`mbica_parent_album`	Which album a gallery is treated as belonging to, when it sits in several.

Markup

Galleries render as .mb-gallery containing figure.mb-item elements; albums add .mb-album, breadcrumbs are nav.mb-crumbs. Column count and spacing arrive as the inline custom properties --mb-cols and --mb-gap, so a media query can override them per breakpoint.

Uninstalling

Deleting the plugin removes its settings only. Galleries, albums, categories and every image stay in the database, so reinstalling picks up where you left off.