SE Paginated News Display Documentation

Table of Contents

1. Overview
2. Requirements
3. Installation
4. Configuration
   1. License
   2. Article Selection
   3. Layout Settings
   4. Content Display
   5. Image Overlay
   6. Pagination
   7. Title Typography
   8. Intro Text Typography
   9. Meta Typography
   10. Category Badge Typography
   11. Read More Button Typography
   12. Custom Bottom Button
   13. Advanced Settings
5. Usage Tips & Best Practices
6. Troubleshooting
7. Upgrading from v1.0
8. Rollback / Uninstall
9. 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)

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

Option B — Manual Upload via FTP

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

Post-Installation Verification

1. Go to Content → Site Modules.
2. Open the module.
3. Confirm you see the configuration tabs described in Section 4 below.
4. 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.

Activating Your License

1. Open the module settings and go to the License tab.
2. Paste your License Server URL and License Key from your purchase confirmation email.
3. Save the module.
4. Visit any front-end page where the module is displayed while logged in as an administrator.
5. A red license bar will appear above the module. Click the Activate License button.
6. 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

4.3 Layout Settings

4.4 Content Display

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.

4.6 Pagination

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

4.7 Title Typography

4.8 Intro Text Typography

4.9 Meta Typography

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

4.10 Category Badge Typography

4.11 Read More Button Typography

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.

4.13 Advanced Settings

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

1. Back up your current module files.
2. Install the v1.1 package using the same method you used for the original installation (Extension Manager or FTP).
3. Clear the Joomla cache.
4. Verify the front end still displays correctly — all defaults are backwards-compatible, so no changes should be visible.
5. 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

1. Go to System → Manage → Extensions.
2. Search for "SE News Display Paginated".
3. 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+