Skip to content

UPGRADING.md

Latest commit

 

History

History
232 lines (147 loc) · 10.3 KB

UPGRADING.md

File metadata and controls

232 lines (147 loc) · 10.3 KB
Raw

Upgrading

v4.0 to v4.1

v4.1 is a minor release with no breaking changes. The theme now ships its own config file, config/northwestern-filament-theme.php, for the lockup, your unit's footer details, the footer's Quick Links and its social accounts.

You don't have to change anything. The theme still reads config/northwestern-theme.php from northwestern-sysdev/northwestern-laravel-ui, and ->footer() arguments and footer component props still take precedence. The footer and brand logo render exactly as they did in 4.0.

Moving to the new config is optional in 4.x:

  1. Publish it:

    php artisan vendor:publish --tag=northwestern-filament-theme-config

  2. Copy your values across. office.addr becomes unit.address, and the NU_THEME_OFFICE_* env vars become NU_UNIT_*. The README has the full key map. Values in the new file win over the legacy file, so you can move one field at a time.

  3. Move ->footer() office and links arguments, and footer component props, into the config. These are deprecated and will be removed only in a future major release, after northwestern-laravel-ui is retired. ->footer(enabled:) is not deprecated.

If you published footer.blade.php, it keeps working, but it hardcodes the social accounts and ignores footer.links from the config. Re-publish it to pick those up.

v3.x to v4.0

v4.0 moves the theme from Northwestern's v8 global template to Department Templates 4.0. The footer is on by default, and the fonts, the default wordmark and the footer markup all change. Panel interiors look the same apart from the details below.

  1. Update the package:

    composer require northwestern-sysdev/northwestern-filament-theme:^4.0

  2. Re-publish assets if you use automatic asset registration:

    php artisan filament:assets

    If you import the theme in a Vite panel theme, rebuild instead (npm run build).

The footer is on by default

Every panel that registers the plugin now renders the Northwestern footer. It used to be opt-in through ->footer().

  • To keep a panel without a footer, opt out:

    NorthwesternTheme::make()
    ->footer(enabled: false)

  • ->footer() with no arguments is now the default, so you can delete that call. Calls with office arguments keep working.

  • On full pages the footer still renders at PanelsRenderHook::BODY_END, after the layout, so it spans the window below the sidebar and the content. On simple pages such as login it now renders inside the simple layout through PanelsRenderHook::SIMPLE_LAYOUT_END, so it sits below the card instead of after the full-height layout.

  • If you rendered the footer yourself, for example through your own BODY_END render hook, remove that hook to avoid two footers.

The footer has new markup

The footer follows the dept 4.0 structure and adds the three required links the v8 footer was missing: Building Access, Privacy Statement and Report a Concern. Its class names changed, for example from .nu-footer-grid and .nu-pin-* to .nu-footer-columns and .nu-footer-icon. The outer .nu-footer element is unchanged.

  • Published views: if you published footer.blade.php, delete your copy, or re-publish and re-apply your edits:

    php artisan vendor:publish --tag=northwestern-filament-theme-views --force

  • Custom CSS: rules that targeted the old footer classes no longer match.

  • Required links can't be removed. To add your own, pass links. They render under "Quick Links":

    NorthwesternTheme::make()
    ->footer(links: [
        'Help' => 'https://example.northwestern.edu/help',
    ])

  • Outside a panel: use <x-northwestern-filament-theme::footer />. It renders without Filament, auth or the database. On a page without the theme CSS, load dist/tokens.css too (see below).

Office configuration

The office fields still resolve from ->footer(), then config('northwestern-theme.office.*'), then the Information Technology defaults. There is one addition:

// config/northwestern-theme.php
'office' => [
    // ...
    'fax' => env('NU_THEME_OFFICE_FAX'), // optional; hidden when empty
],

Or pass officeFax: to ->footer(). A field that resolves to an empty string is now hidden instead of rendering an empty row.

Fonts and wordmark

  • Fonts load as .woff2 from https://common.northwestern.edu/dept/4.0/css/fonts/ instead of v8. The CDN host is the same, so CSP allowlists don't change. Poppins 400 now uses the regular face instead of light, so text at that weight renders slightly heavier. Noto Serif is new and is available as --nu-font-display.
  • Default brand logo. When config('northwestern-theme.lockup') is not set, the logo is the dept 4.0 "Northwestern" wordmark as inline SVG instead of v8/css/images/northwestern.svg, so $panel->getBrandLogo() returns an Htmlable. It is Northwestern Purple on light backgrounds and white in the topbar and in dark mode.
  • Configured lockups win. If your config/northwestern-theme.php sets lockup to the v8 URL (the northwestern-laravel-ui default), you keep the v8 image. Set it to null to use the dept 4.0 wordmark.
  • Favicon. The default is https://common.northwestern.edu/favicon.ico instead of v8/icons/favicon-32.png. The artwork is the same.

New dist/ files

  • dist/tokens.css is new. It contains the dept 4.0 @font-face rules and the --nu-* custom properties, with no Filament selectors, for pages that render outside Filament such as an error layout. dist/theme.css already includes it, so panels don't need it.
  • dist/tailwind-tokens.css keeps its name and its --color-nu-* utilities, and adds font-nu-body, font-nu-heading, font-nu-display and the square-corner radius scale. It still needs the custom properties from theme.css or tokens.css.

The palette now comes from @nu-appdev/northwestern-tokens, bundled at build time. You don't need to install it: everything ships in dist/. The --nu-* names and values are unchanged.

Environment indicator on simple pages

The environment indicator now also renders at the top of simple pages, such as login, through PanelsRenderHook::SIMPLE_LAYOUT_START. It follows the same ->environmentIndicator() settings. ->withoutEnvironmentIndicator() removes it from both places.

v2.0 to v2.1

v2.1 adds a built-in environment indicator and impersonation banner. If you were using third-party packages or custom views for these features, you can remove them.

Environment Indicator

If you are using pxlrbt/filament-environment-indicator:

  1. Remove the package:

    composer remove pxlrbt/filament-environment-indicator

  2. Remove the plugin registration from your panel provider:

    - use Pxlrbt\FilamentEnvironmentIndicator\EnvironmentIndicatorPlugin;

  return $panel
      ->plugins([
          NorthwesternTheme::make(),
-         EnvironmentIndicatorPlugin::make(),
      ]);

The theme's indicator is enabled by default and hides in production. To customize or disable it, see the Environment Indicator section.

Impersonation Banner

If you have a custom impersonation banner (e.g. a Blade view registered via FilamentView::registerRenderHook):

  1. Remove your custom banner view and its render hook registration.

  2. The built-in banner auto-detects lab404/laravel-impersonate sessions. If you are using lab404, no configuration is needed. Just remove your custom implementation.

  3. If you have custom visibility, label, or leave URL logic, migrate it to the plugin API:

    NorthwesternTheme::make()
    ->impersonationBanner(
        visible: fn () => session()->has('impersonating'),
        label: fn () => 'Acting as ' . auth()->user()->name,
        leaveUrl: '/stop-impersonating',
    )

To disable the banner entirely, call ->withoutImpersonationBanner().

Footer

Footer CSS is now inlined in the Blade view. If you previously needed to run php artisan filament:assets specifically for footer styles, that step is no longer necessary (though you should still run it for the main theme CSS unless you use Vite integration).

v1.x to v2.0

v2.0 consolidates the theme's CSS into a single barrel file (dist/theme.css) instead of shipping individual module files.

Required Steps

  1. Update the package:

    composer require northwestern-sysdev/northwestern-filament-theme:^2.0

  2. Clear previously published CSS assets:

    rm -rf public/css/northwestern-sysdev

  3. Re-publish assets:

    php artisan filament:assets

That's it for the default integration path. The plugin will register the single theme.css file automatically through @filamentStyles.

Optional: Vite Theme Integration

If you already have a custom Filament panel theme (created via php artisan make:filament-theme) and want Northwestern color tokens as Tailwind utilities, a single compiled CSS bundle, or the ability to override theme styles in your own CSS, you can switch to Vite integration.

Steps:

  1. Run the install command:

    php artisan northwestern-theme:install

    This will:

    • Create a panel theme CSS file if one doesn't exist
    • Inject the Northwestern theme @import after the Filament base import
    • Optionally inject Tailwind v4 design tokens for color utilities

  2. Disable automatic asset registration in your panel provider:

    use Northwestern\FilamentTheme\NorthwesternTheme;

NorthwesternTheme::make()
    ->withoutAssetRegistration()

    This prevents the theme CSS from loading twice. Once through your Vite bundle and once through @filamentStyles.

  3. Compile your assets:

    npm run build

Breaking Changes

  • Individual CSS module files (variables.css, typography.css, etc.) are no longer registered separately. They're concatenated into dist/theme.css.
  • The public/css/northwestern-sysdev/ directory from v1 should be removed to avoid stale files.