Flatly Theme Laravel Package

Getting Started

1. Prereqs. You need a working AsgardCMS install (not vanilla Laravel). This theme depends on the AsgardCMS theme/module architecture, the Menu and Block modules, and a Blade layout convention — it will not drop into a stock Laravel app without those modules.
2. Install (fork it). Treat upstream as a template, not a dependency:

   git clone [email protected]:Idavoll/Flatly.git theme/flatly
   # or, if you accept the risk:
   composer require idavoll/flatly-theme
   

   Add the fork to your composer.json repositories and pin an exact commit — this package has 0 stars and 0 dependents, so there is no community to catch a breaking change.
3. Register the provider. AsgardCMS themes pre-date Laravel package auto-discovery. Add the theme's service provider to config/app.php (or bootstrap/providers.php on newer apps) and register the theme in config/cms/core.php under themes.
4. Publish and activate.

   php artisan vendor:publish --provider="Idavoll\Flatly\Providers\FlatlyServiceProvider"
   php artisan theme:list          # confirm it's registered
   php artisan view:clear && php artisan cache:clear
   

   Then activate it in the admin (Settings → Themes) or set 'theme' => 'flatly' in config/cms/core.php.
5. First place to look. Open resources/theme.json (theme metadata, slug, preview, block registrations) and resources/views/layouts/master.blade.php (the layout contract every page inherits). Between those two files you'll understand how the theme wires into AsgardCMS.
6. First use case. Stand up a marketing site: activate Flatly, populate a Home page and a Menu from the admin, and drop the theme's block regions into master.blade.php so blocks render. The Flatly palette (Bootstrap 3 flat design) is the immediate win — you get a clean, dark-accented UI with no design work.

Implementation Patterns

• Override, don't edit vendor. The day-1 rule: never edit files under vendor/ or the published theme directory directly if you can help it. AsgardCMS resolves theme views through the view finder; place your overrides in resources/views/vendor/<theme-slug>/… (or a child theme) so composer update never clobbers your work.
• Layout composition. layouts/master typically @extends a base and includes partials/header, partials/footer, and a @yield('content'). Pages render through pages/*.blade.php. Keep business logic out of these — push it into the page's presenter or a view composer so the templates stay swappable.
• Menu and block regions. The header partial usually loops Menu-module items. Register block regions in theme.json (or via @block('sidebar') style directives) so the Block module renders admin-configured widgets into them. This is the main integration point between the theme and the rest of AsgardCMS.
• Rebrand without forking the layout. Flatly's colors come from Bootswatch's _variables.scss. Add resources/assets/sass/app.scss that sets your brand variables before importing bootswatch/flatly/_variables.scss and bootstrap, then rebuild. You keep the theme's blade markup and swap only the design tokens.
• Asset pipeline for a modern app. The theme ships a period-appropriate Gulp/Elixir pipeline — replace it with Vite or Laravel Mix. Compile SASS to public/themes/flatly/css, then re-publish:

  npm install && npm run build
  php artisan vendor:publish --tag=flatly-assets --force
  

• Multi-theme / child theme. Keep a small child theme whose theme.json declares Flatly as its parent and overrides only 2–3 blade files. This lets you upgrade the parent while keeping bespoke branding, mirroring the same pattern you'd use with a Laravel package's vendor:publish + view:cache workflow.
• Wire the theme to app-level concerns. View composers for partials/header (nav data), partials/footer (contact/legal data), and any block view keep the theme purely presentational so it can be swapped to another AsgardCMS theme without touching domain code.

Gotchas and Tips

• This is effectively unmaintained. 0 stars, 0 dependents, a 0.33 score. There is no release note to read when something breaks. Vendor it, pin the commit, and add a smoke test that renders the home page after every deploy.
• Version drift is the primary failure mode. The theme targets an older AsgardCMS/Laravel combination (Bootstrap 3 era). Porting to Laravel 10+/AsgardCMS 4 usually requires: (a) namespace updates if AsgardCms\ was renamed to Modules\, (b) replacing Gulp with Vite, (c) fixing blade class names if you upgrade to Bootstrap 4/5 — panel, col-xs-*, and pull-right all changed. Grep every partial before you touch the vendor CSS.
• theme.json is a hard contract. It must live at resources/theme.json with slug, name, author, version; a typo silently drops the theme from theme:list and makes it unselectable in the admin. Validate the JSON before debugging anything else.
• Asset publishing traps. Published theme assets are copied, not symlinked — the single most common "why is my nav still the old blue" is that you edited resources/assets/ and forgot to re-publish. Chain vendor:publish --tag=… --force && view:clear && cache:clear into one make/npm script.
• View cache makes edits invisible. Blade compiles to storage/framework/views. If a published view change isn't showing, php artisan view:clear first. If a php artisan view:cache was ever run in a deploy hook, forget to re-run it and production will serve stale templates.
• Provider ordering matters. If the theme registers a view namespace like flatly, and another package registers the same name, whichever provider loads last wins. Check the order in config/app.php/bootstrap/providers.php when you get an unexpected view.
• Debugging "is it even active?" Two commands answer it: php artisan theme:list (is it registered?) and inspecting config('cms.core.theme') (is it selected?). If both look right but you still see the default theme, the cached config is stale — php artisan config:clear.
• Extension points worth knowing. theme.json preview image (admin thumbnail), the config/cms/core.php themes array (theme registration), Bootswatch SASS variables (design tokens), and the Block module regions (composition without touching blade).
• Don't inherit Flatly's JS if you modernize. The theme bundles older Bootstrap JS. If you upgrade to Bootstrap 5, swap in the new bundle explicitly, or you'll get dropdown/tooltip failures that look like your own bug.