NewsLoopVersion 1.0.0 · offline copyGuides

Themes ​

A theme decides how the public site looks. NewsLoop ships three:

Theme Look
Classic A busy news portal with a picture mosaic of top stories, coloured section blocks with a sidebar, a video strip and a dark footer. Every other theme builds on it.
Magazine A compact header, a big hero story and large pictures.
Minimal One column and words first. Suits newsletters and columnists.

You switch themes under Site → Themes and adjust them under Site → Customise. You don't need to edit any files for that. This guide is for changing a theme's files or making your own.

Editing themes needs no build tools ​

Themes are plain Blade templates, CSS and JavaScript. Edit a file and upload it. You don't need Node or a build step.

The Themes screen with Classic, Magazine and Minimal

After you edit theme files on a live site, click Refresh theme files on the Themes screen, or run this:

php artisan newsloop:themes:publish

This copies the theme's assets folder to public/themes, where browsers can load it. With APP_DEBUG=true the site notices changes by itself.

Make your own theme ​

The safest way is a child theme. It changes only what you want, and it keeps getting fixes when Classic is updated.

  1. Create the folder themes/my-paper. Use lowercase letters, numbers and dashes only.

  2. Add themes/my-paper/theme.json:

    json
    {
        "name": "My Paper",
        "version": "1.0.0",
        "author": "Your name",
        "description": "Our newspaper's look.",
        "parent": "classic",
        "styles": ["assets/my-paper.css"]
    }
  3. Add themes/my-paper/assets/my-paper.css with your changes. Classic's stylesheet loads first, so you only write the differences.

  4. Choose My Paper under Site → Themes.

To change a template, copy it from themes/classic/views to the same place under themes/my-paper/views, then edit the copy. Everything you don't copy still comes from Classic.

Folder layout ​

themes/my-paper/
  theme.json           the manifest (required)
  screenshot.jpg       shown on the Themes screen, 1280×800
  assets/              CSS, JavaScript, fonts and images, copied to public/themes/my-paper
  views/               Blade templates
  lang/                optional JSON translations, such as lang/fr.json

theme.json ​

Key What it does
name Required. Shown on the Themes screen.
version Change it when you release an update, so the site refreshes the copied files.
parent The folder name of the theme to build on.
styles, scripts Files in the theme folder to load on every page. A parent's files load first.
menus Menu locations the theme shows, as location: label. The built-in locations are header, top, footer and footer-legal.
areas Places where the admin arranges blocks under Site → Layout. See below.
settings Options for Site → Customise. See below.
supports Informational flags, such as dark-mode and rtl.

Layout areas ​

json
"areas": {
    "home": {
        "label": "Home page",
        "kind": "sections",
        "defaults": [
            { "type": "featured", "settings": { "layout": "hero", "count": 4 } },
            { "type": "latest", "settings": { "title": "Latest", "count": 8 } }
        ]
    },
    "sidebar": { "label": "Sidebar", "kind": "widgets", "defaults": [{ "type": "popular" }] }
}

Block types are featured, latest, category, sections, popular, picks, live, videos, gallery, series, tags, categories, social, ad, newsletter, text, banner and html.

A main column and a sidebar ​

Add "columns": true to a sections area to let each block choose where it sits. The admin picks Full width, Main column or Sidebar beside it under Site → Layout. The setting is stored as _column, and in defaults you set it the same way:

json
{ "type": "category", "settings": { "position": 1, "_column": "main" } },
{ "type": "social", "settings": { "style": "counter", "_column": "side" } },
{ "type": "sections", "settings": { "position": 3, "_column": "full" } }

Blocks in the main column and the sidebar that follow each other share a row:

html
<div class="nf-row">
    <div class="nf-row__main">…</div>
    <aside class="nf-row__side">…</aside>
</div>

A full-width block ends the row. A row with nothing in the sidebar gets nf-row--no-side. Block templates receive $column (full, main or side).

Sections by number ​

category and sections blocks can leave the section empty and use position, meaning "the Nth main section" in the order of Organise → Categories. A theme's default home page can then show real sections on any site without knowing their IDs. Section blocks pass the section's colour to their heading as --nf-section-color. A section without a colour uses the accent colour.

Layouts ​

Block Layouts
featured hero, grid, mosaic (two big stories above three smaller ones)
latest, category, picks grid, list, compact, lead, rows, overlay
popular numbered, thumbs (numbered, with pictures), slider
videos style: dark or light
social style: links (icons) or counter (coloured tiles with follower counts)
categories counts: show the number of articles in each section

Classic's theme.js adds arrow buttons to sliders and rotates the header ticker. Without it, sliders still scroll by swiping, and the ticker shows its first headline.

Customizer settings ​

json
{ "key": "accent_color", "section": "Colours", "type": "color", "label": "Accent colour",
  "default": "#c8102e", "css_var": "--nf-accent" }
Type Stored as Reaches the page as
color #rrggbb The CSS variable named in css_var
number A number between min and max The CSS variable, plus unit such as px
select One of the options keys data-nf-{key}="value" on <html>
boolean On or off data-nf-{key}="on" or "off" on <html>
text, textarea, media Text, or a media library ID $site->option('key') in templates

Add "scope": "dark" to a colour to use it only in dark mode.

Every value is validated before it is saved. A colour can only be a hex code, so a setting can never inject CSS.

Templates ​

The site looks for templates in your theme, then its parent, then the core. The first one found wins.

Page Template, most specific first
Home home
Section category-{slug}, then category
Article article-{type} (live, video, audio, gallery), then article
Page page-{layout} (full-width, contact), then page
Tag, author, series, search tag, author, series, search
Not found 404 (410 for removed pages)
A block blocks/{type}

Every layout must include the core head and foot inside <head> and before </body>:

blade
<head>@include('nf::head')</head>
...
@include('nf::foot')

The head prints the title, SEO and social tags, structured data, hreflang, stylesheets and customizer colours. The foot prints scripts, the cookie banner and the view counter.

What templates receive ​

Every template gets $site and $seo. Page templates also get their own data: $post, $page, $category, $posts (paginated), $tag, $author, $series, and $query with $results.

Commonly used $site methods:

Method Returns
name(), tagline(), logo() Site details from System → Site settings → General
menu('header') Links, each with label, url, new_tab and children
url($post) An article's address
section($post) The article's section: name, url and color
image($media, 'card', eager: false) A responsive <img> with srcset. Presets are thumb, card, lead and full.
date($time), time($time), ago($time) Dates in the site's timezone and language
option('key') A customizer value
area('sidebar') The blocks arranged in an area
breaking() Breaking news from the last two days
languages(), locale(), dir() Language details. dir() is ltr or rtl.

Reusable pieces live in resources/views/public/partials: card, byline, share, comments, live-updates, pagination, breadcrumbs, language-switcher, paywall and contact-form. Include them with @include('theme::partials.card', ['post' => $post, 'variant' => 'grid']). To change one, copy it to your theme's views/partials folder.

Styles ​

The core stylesheet styles article content, comments, live blogs, forms and sharing. It reads these variables, which your theme can set:

css
:root {
    --nf-accent: #c8102e;        /* links and buttons */
    --nf-accent-contrast: #fff;  /* text on the accent colour */
    --nf-bg: #fff;
    --nf-surface: #f5f5f3;       /* panels and boxes */
    --nf-text: #151515;
    --nf-muted: #5a5a5a;
    --nf-border: #e2e2de;
    --nf-radius: 4px;
    --nf-font-body: system-ui, sans-serif;
    --nf-font-heading: Georgia, serif;
    --nf-article-size: 18px;
}
:root[data-nf-scheme="dark"] { /* the same variables for dark mode */ }

Use logical properties such as margin-inline-start instead of margin-left. Then Arabic, Hebrew and Urdu sites work without extra CSS.

Interactive features ​

The core script adds behaviour to plain markup, so themes need no JavaScript of their own:

Attribute Feature
data-nf-toggle="element-id" Opens and closes a menu or panel. Escape closes it.
data-nf-scheme-toggle Switches light and dark mode
data-nf-progress A reading progress bar
data-nf-share, data-nf-copy="url" The phone's share sheet, and copying a link

Comments, live blog updates, the contact form, the view counter and cookie consent work automatically when you use the core partials.

Rules for theme authors ​

Checking a theme ​