Documentation | SE Paginated News Display

SE News Display Paginated — User Guide

Version 1.1.0 • Joomla 4.0+ Module • GNU GPL v2+

Overview
Requirements
Installation
Configuration
Usage Tips & Best Practices
Troubleshooting
Upgrading from v1.0
Rollback / Uninstall
FAQ

1. Overview

SE News Display Paginated is a responsive Joomla site module that shows articles from one or more categories in a configurable grid layout. It features client-side pagination (no page reloads), image overlays, an article offset option, full typography controls, and animation effects. All settings are managed through the standard Joomla module configuration panel — no code editing required.

Key Features

Responsive grid with separate column settings for desktop, tablet, and mobile
Client-side pagination (page numbers or previous/next)
Image overlay mode with configurable position, colour, and opacity
Article offset — skip the first N articles so multiple module instances can share a category without duplicating content
Full typography controls for titles, intro text, meta info, category badges, and buttons (font size, weight, colour, line height, letter spacing)
Custom call-to-action button at the bottom of the module
Entry animations (fade, slide up, slide left, scale)
Multiple image aspect ratios (16:9, 4:3, 3:2, 1:1, 9:16, auto)
Caching support

2. Requirements

Joomla 4.0 or higher
PHP 7.4 or higher
FTP or Joomla admin panel access for installation

3. Installation

Option A — Joomla Extension Manager (recommended)

Log in to your Joomla administrator panel.
Navigate to System → Install → Extensions.
Click Upload Package File.
Select mod_se_news_display_paginated_jed_gpl.zip and click Upload & Install.
Go to System → Clear Cache and delete all cached items.
Navigate to Content → Site Modules, find "SE News Display Paginated", and configure it.

Option B — Manual Upload via FTP

Extract the zip file on your local machine.
Connect to your server via FTP.
Upload the mod_se_news_display_paginated folder to /modules/.
Upload the media folder contents to /media/mod_se_news_display_paginated/.
In the Joomla admin, go to Extensions → Discover, click Discover, then install the discovered module.
Clear the Joomla cache.

Post-Installation Verification

Go to Content → Site Modules.
Open the module.
Confirm you see the configuration tabs described in Section 4 below.
Assign the module to a position and one or more pages, then check the front end.

4. Configuration

All settings are found in the module's configuration panel at Content → Site Modules → SE News Display Paginated. They are organised into the fieldsets described below.

4.1 License

The module must be activated with a valid license key before it will display articles. This is the first tab in the module options.

Setting	Description	Default
License Server URL	The URL of your SubSeller license server. This is provided in your purchase confirmation email. Do not include a trailing slash.	empty
License Key	Your license key in the format SS-XXXX-XXXX-XXXX-XXXX. This is provided in your purchase confirmation email.	empty

Activating Your License

Open the module settings and go to the License tab.
Paste your License Server URL and License Key from your purchase confirmation email.
Save the module.
Visit any front-end page where the module is displayed while logged in as an administrator.
A red license bar will appear above the module. Click the Activate License button.
On success the bar turns green. The module is now permanently activated.

License Status Bar

The license status bar is only visible to logged-in Joomla administrators. Regular site visitors never see it. It shows one of three states:

Green (Active) — License is valid and active. Shows the masked key, expiry date, and a "Check License" button.
Amber (Expired) — License has expired. The module continues to work normally, but you won't be able to download updates until you renew. Shows a "Check License" button to re-validate after renewal.
Red (Not Activated) — License hasn't been activated yet, or the server URL / key fields are empty. Shows the specific error and an "Activate License" button.

How Activation Works

The module contacts your license server only when you click "Activate License" or "Check License". After successful activation, a permanent file is stored locally. The module never "phones home" automatically — it works offline after activation. License expiry only affects your ability to download updates; the module itself continues to work indefinitely.

Checking / Refreshing Your License

If you renew your license, click the Check License button on the green or amber bar. This wipes the local activation file, re-validates against the server, and stores the updated expiry date.

4.2 Article Selection

Setting	Description	Default
Select Categories	Choose one or more Joomla content categories. Only published articles from these categories will appear. Hold Ctrl/Cmd to select multiple.	none
Featured Articles	Filter by featured status: Both Featured and Non-Featured, Only Featured, or Only Non-Featured.	Both
Article Ordering	Sort order for the articles. Options: Created Date (newest/oldest), Modified Date (newest/oldest), Title (A-Z / Z-A), Most Popular (hits), or Random.	Created Date (Newest First)
Number of Articles	Total number of articles to retrieve. Range: 1–100.	12
Article Offset	Skip this many articles from the start. Useful when another module on the same page is already showing the latest articles and you want to avoid duplication. Range: 0–100.	0

4.3 Layout Settings

Setting	Description	Default
Number of Columns	Columns on desktop screens. Options: 1–6.	3
Columns on Tablet	Columns on tablet-sized screens. Options: 1–4.	2
Columns on Mobile	Columns on mobile screens. Options: 1 or 2.	1
Gap Between Items (px)	Space in pixels between each article card. Range: 0–100.	20

4.4 Content Display

Setting	Description	Default
Show Image	Display the article's intro image (falls back to full-text image if no intro image is set).	Yes
Image Aspect Ratio	Crop images to a fixed aspect ratio: 16:9, 4:3, 3:2, 1:1, 9:16, or Auto (original).	16:9
Show Title	Display the article title. The title links to the full article.	Yes
Show Intro Text	Display a snippet of the article's intro text below the title.	Yes
Intro Text Character Limit	Maximum number of characters to show. Text is trimmed at the last full word and an ellipsis is appended. Set to 0 for unlimited.	150
Show Date	Display the article's created date.	Yes
Date Format	PHP date format string. Examples: `d M Y` → "06 Mar 2026", `F j, Y` → "March 6, 2026", `d/m/Y` → "06/03/2026".	d M Y
Show Author	Display the article author name.	No
Show Category	Display a category badge for each article.	Yes
Show Read More Button	Display a button linking to the full article.	Yes
Read More Text	The label shown on the read more button.	Read More

4.5 Image Overlay

When enabled, the article title and meta info are displayed on top of the image instead of below it. All overlay settings are only visible when "Enable Image Overlay" is set to Yes.

Setting	Description	Default
Enable Image Overlay	Turn overlay mode on or off.	No
Overlay Position	Where to place the text on the image: Bottom Left, Bottom Centre, Bottom Right, Top Left, or Top Right.	Bottom Left
Overlay Background Colour	Background colour behind the overlay text.	#000000
Overlay Background Opacity	Transparency of the overlay background, from 0% (invisible) to 100% (solid).	70%
Overlay Text Colour	Colour of the title and meta text in the overlay.	#ffffff
Overlay Padding	CSS padding around the overlay text area, e.g. `12px 16px`.	12px 16px

4.6 Pagination

Pagination is handled entirely on the client side using JavaScript — no page reloads occur when the user changes pages.

Setting	Description	Default
Show Pagination	Enable or disable the pagination controls.	Yes
Pagination Type	Choose between Page Numbers (1, 2, 3…) or Previous/Next buttons.	Page Numbers
Items Per Page	Number of article cards shown per page. Range: 1–50.	12

4.7 Title Typography

Setting	Description	Default
Font Size (px)	Title font size. Range: 10–72.	20
Font Weight	Light (300), Normal (400), Medium (500), Semi Bold (600), Bold (700), Extra Bold (800), Black (900).	Bold (700)
Colour	Title text colour.	#1a1a1a
Hover Colour	Colour when the user hovers over the title link.	#0066cc
Line Height	Unitless line-height multiplier (e.g. 1.4 means 1.4× the font size).	1.4
Letter Spacing (em)	Additional spacing between letters. 0 for normal.	0

4.8 Intro Text Typography

Setting	Description	Default
Font Size (px)	Intro text font size. Range: 10–32.	14
Font Weight	Light (300) through Bold (700).	Normal (400)
Colour	Intro text colour.	#666666
Line Height	Line-height multiplier.	1.6

4.9 Meta Typography

Controls the appearance of date, author name, and other meta information.

Setting	Description	Default
Font Size (px)	Meta font size. Range: 8–24.	12
Font Weight	Light (300) through Bold (700).	Normal (400)
Colour	Meta text colour.	#999999
Text Transform	None, UPPERCASE, lowercase, or Capitalize.	UPPERCASE
Line Height	Line-height multiplier. Range: 1.0–3.0, step 0.1.	1.5

4.10 Category Badge Typography

Setting	Description	Default
Font Size (px)	Badge font size. Range: 8–20.	11
Font Weight	Normal (400) through Bold (700).	Semi Bold (600)
Background Colour	Badge background colour.	#0066cc
Text Colour	Badge text colour.	#ffffff
Line Height	Line-height multiplier. Range: 1.0–3.0, step 0.1.	1.4

4.11 Read More Button Typography

Setting	Description	Default
Font Size (px)	Button font size. Range: 10–24.	14
Font Weight	Normal (400) through Bold (700).	Semi Bold (600)
Background Colour	Button background colour.	#0066cc
Text Colour	Button text colour.	#ffffff
Hover Background Colour	Background colour on hover.	#0052a3
Line Height	Line-height multiplier. Range: 1.0–3.0, step 0.1.	1.5

4.12 Custom Bottom Button

An optional call-to-action button displayed below all the article cards. Leave the URL field empty to hide it.

Setting	Description	Default
Button URL	The link the button points to. Leave empty to hide the button entirely.	empty
Button Text	Label displayed on the button.	View All Articles
Open Link In	Same Window or New Window/Tab.	Same Window
Font Size (px)	Range: 10–32.	16
Font Weight	Normal (400) through Extra Bold (800).	Semi Bold (600)
Background Colour	Button background.	#0066cc
Text Colour	Button text.	#ffffff
Hover Background Colour	Background on hover.	#0052a3
Hover Text Colour	Text colour on hover.	#ffffff
Border Radius (px)	Corner roundness. 0 for square, higher for rounded. Range: 0–50.	4
Padding	CSS padding, e.g. `14px 40px`.	14px 40px

4.13 Advanced Settings

Setting	Description	Default
Custom CSS Class	Add one or more CSS class names to the module wrapper element. Useful for targeted custom styling.	empty
Animation	Animation applied when article cards first appear on screen: None, Fade In, Slide Up, Slide Left, or Scale.	None
Caching	No Caching or Use Global Cache.	Use Global Cache
Cache Time	Cache duration in minutes. Range: 1–1440 (24 hours).	15

5. Usage Tips & Best Practices

Using the Article Offset

If you have a hero or featured module that already displays the latest 3 articles from a category, set the offset to 3 on this module so it begins from the 4th article. This prevents duplicate content on the same page.

Multiple Instances

You can create multiple instances of this module, each pointing to different categories or using different styling. Assign each instance to the desired module position and pages via the standard Joomla module assignment settings.

Responsive Column Tips

A common responsive configuration is 3 or 4 columns on desktop, 2 on tablet, and 1 on mobile. If your cards have long titles or lots of text, consider using fewer columns to give the content room to breathe.

Line Height Guidelines

For headlines/titles: 1.2–1.4 (tight, impactful)
For body/intro text: 1.5–1.8 (comfortable reading)
For meta text: 1.4–1.5 (clean, compact)
For accessibility (WCAG 2.1): use at least 1.5 for paragraph text

Image Aspect Ratios

For a consistent, clean grid, pick a fixed aspect ratio (16:9 is the most common). Use "Auto" only if your images already share a consistent size, otherwise the grid will look uneven.

Pagination

Pagination is purely client-side. All articles matching your filters are loaded in one request, then split into pages by JavaScript. This means page changes are instant, but you should keep "Number of Articles" reasonable (under 100) for performance.

6. Troubleshooting

License activation fails / "Could not connect to the license server"

Double-check the License Server URL — it should be the full URL of your SubSeller site (e.g. https://yoursite.com), without a trailing slash.
Make sure your server can make outbound HTTP requests (some hosts block cURL/file_get_contents to external URLs).
Check that the license key format is correct: SS-XXXX-XXXX-XXXX-XXXX.

"License has not been activated yet" but I already activated

If you changed the license key in the module options after activating, the stored key no longer matches. Click "Activate License" again with the new key.
Check file permissions on the modules/mod_se_news_display_paginated/helpers/ directory — it needs to be writable so the activation file can be saved.

I don't see the license bar on the front end

The license status bar is only visible to logged-in users who have the core.manage permission for com_modules (typically Super Users and Administrators). Log in to the front end with an admin account.

No articles appear

Make sure you have selected at least one category in the Article Selection tab.
Verify the selected categories contain published articles.
Check that the "Featured Articles" filter isn't excluding all your content.
If using an offset, ensure it isn't larger than the number of available articles.

Settings not appearing in the backend

Clear the Joomla cache: System → Clear Cache.
Clear your browser cache or try incognito/private mode.
If you installed manually, verify that mod_se_news_display_paginated.xml was uploaded correctly.

Styling changes not visible on the front end

Clear the Joomla cache.
Hard-refresh your browser (Ctrl+F5 on Windows, Cmd+Shift+R on Mac).
Check that your template's CSS is not overriding the module styles. Use the Custom CSS Class setting to add a specific class and write higher-specificity rules if needed.

Images not showing

Ensure your articles have an intro image or a full article image set in the article's Images tab.
Verify the image files exist on the server and the paths are correct.

Pagination not working

Make sure "Show Pagination" is set to Yes.
If Items Per Page is equal to or greater than the total number of articles, pagination will have nothing to paginate and won't appear.
Check the browser console for JavaScript errors that might prevent the pagination script from running.

7. Upgrading from v1.0

Back up your current module files.
Install the v1.1 package using the same method you used for the original installation (Extension Manager or FTP).
Clear the Joomla cache.
Verify the front end still displays correctly — all defaults are backwards-compatible, so no changes should be visible.
Optionally, configure the new settings (meta line height, category badge line height, button line height) to fine-tune your typography.

No database changes are required. Existing settings are fully preserved.

8. Rollback / Uninstall

Rollback to v1.0

Restore the backed-up XML and template files, then clear the Joomla cache.

Full Uninstall

Go to System → Manage → Extensions.
Search for "SE News Display Paginated".
Select it and click Uninstall.

9. FAQ

Q: Will upgrading to v1.1 change how my site looks?
A: No. All new settings use default values that match the v1.0 appearance. Nothing changes until you adjust the new settings.

Q: Can I use different settings for different pages?
A: Each module instance has its own settings. Create multiple instances of the module and assign each to different pages with different configurations.

Q: Does this affect site performance?
A: The typography and overlay settings are pure CSS — there is no performance impact. Client-side pagination means all articles are loaded once, so keep the article count reasonable.

Q: What happens if an article has no image?
A: The image area is simply omitted for that article. The title, text, and meta still display normally.

Q: Can I use this with Joomla 3?
A: No. This module requires Joomla 4.0 or higher.

Q: How do I reset a setting to its default?
A: Enter the default value listed in the tables above. There is no automatic reset button.

File Structure

mod_se_news_display_paginated/
├── mod_se_news_display_paginated.xml   — Module manifest and all configuration fields
├── mod_se_news_display_paginated.php   — Main entry point (includes license checking)
├── helper.php                          — Article query, text truncation, date formatting
├── helpers/
│   └── LicenseChecker.php             — License validation, activation file management
├── tmpl/
│   └── default.php                     — Default grid template (includes license status bar)
├── media/mod_se_news_display_paginated/
│   ├── css/style.css                   — Module stylesheet
│   └── js/module.js                    — Client-side pagination and animations
├── LICENSE.txt
├── CHANGELOG.md
├── README.md
├── INSTALLATION.md
├── LINE_HEIGHT_GUIDE.md
├── UPDATE_SUMMARY.md
└── INDEX.md

SE News Display Paginated v1.1.0 — Licensed under GNU GPL v2+