MediaBrain Theme System: Developer Reference

This guide provides a comprehensive reference for implementing themes, components, containers, and utility classes in MediaBrain apps. All code samples are copy-paste ready and follow a MaterializeCSS-like approach for rapid development.

Getting Started

1. Choose a theme: default, startrek, or your custom theme.
2. Include theme assets in your view:

<?php
include_theme_css('default', ['components.css', 'dashboard.css']);
include_theme_js('default', ['theme.js']);
include_theme_audio('default', ['click', 'notify']);
?>

Theme File Structure

/themes/{theme}/
    components.css
    dashboard.css
    theme.js
    audio/
        click.mp3
        notify.mp3
/apps/{app}/themes/{theme}/
    (app-level overrides)

Utility Classes Reference

Buttons

<button class="mb-btn">Default Button</button>
<button class="mb-btn mb-btn-primary">Primary Button</button>
<button class="mb-btn mb-btn-accent">Accent Button</button>
<button class="mb-btn mb-btn-large">Large Button</button>

Cards

<div class="mb-card">
  <div class="mb-card-content">
    <h3 class="mb-card-title">Card Title</h3>
    <p class="mb-text">Card content goes here.</p>
    <button class="mb-btn mb-btn-primary">Action</button>
  </div>
</div>

Panels

<div class="mb-panel">Basic Panel</div>
<div class="mb-panel mb-panel-primary">Primary Panel</div>
<div class="mb-panel mb-panel-dark">Dark Panel</div>

Alerts

<div class="mb-alert mb-alert-info">Info message</div>
<div class="mb-alert mb-alert-success">Success message</div>
<div class="mb-alert mb-alert-error">Error message</div>

Navigation

<nav class="mb-nav">
  <a href="#" class="mb-nav-link mb-nav-active">Home</a>
  <a href="#" class="mb-nav-link">Dashboard</a>
</nav>

Forms

<input type="text" class="mb-input" placeholder="Text input">
<select class="mb-select">
  <option>Option 1</option>
</select>

Grid & Layout

<div class="mb-container">
  <div class="mb-row">
    <div class="mb-col-6">Half width</div>
    <div class="mb-col-6">Half width</div>
  </div>
</div>

Spacing Utilities

<div class="mb-m-2">Medium margin</div>
<div class="mb-p-2">Medium padding</div>

Typography

<h1 class="mb-heading mb-heading-1">Large Heading</h1>
<p class="mb-text mb-text-muted">Muted text</p>

Theme Audio Usage

<audio id="theme-click" src="/themes/default/audio/click.mp3" preload="auto"></audio>
<button onclick="document.getElementById('theme-click').play()">Play Click</button>

Overriding Theme Assets

To override any theme asset for a specific app, place your file in /apps/{app}/themes/{theme}/. The system will use the override if it exists, otherwise it falls back to the global theme asset.

<?php
$audioPath = get_theme_file('default', 'audio/click.mp3', 'myapp');
// Returns /apps/myapp/themes/default/audio/click.mp3 if it exists
// Otherwise returns /themes/default/audio/click.mp3
?>

Best Practices

• Always use utility functions for asset inclusion.
• Use utility classes for consistent styling.
• Document overrides and customizations in your app's README.
• Test your app with multiple themes for compatibility.

Advanced: Creating a New Theme

1. Create a new directory in /themes/{newtheme}/
2. Add your CSS, JS, and audio files.
3. Use the utility functions to include assets in your views.
4. Override assets in /apps/{app}/themes/{newtheme}/ as needed.

Reference: Utility Functions

include_theme_css($theme, $files)
include_theme_js($theme, $files)
include_theme_audio($theme, $files, $type)
get_theme_file($theme, $file, $app = null)

Need Help?

Contact the MediaBrain development team or see code comments in includes/util.php for more info.

OAuth Provider Setup

To enable Google, Facebook, and Apple login for your app, follow these steps:

• Register your app with each provider to obtain credentials.
• Edit C:\var\data\mediabrain\oauth_config.json (Windows) or /var/data/mediabrain/oauth_config.json (Linux/Docker) and add your credentials as shown below.

Google OAuth

1. Go to Google Cloud Console
2. Create a project and OAuth client ID (Web application).
3. Set redirect URI: https://yourdomain.com/oauth/google.php?action=callback
4. Copy your Client ID and Client Secret.
5. Edit your config:

   "google": {
     "enabled": true,
     "client_id": "YOUR_GOOGLE_CLIENT_ID",
     "client_secret": "YOUR_GOOGLE_CLIENT_SECRET",
     "scopes": ["openid", "email", "profile"]
   }

Facebook Login

1. Go to Facebook for Developers
2. Create an app and add Facebook Login.
3. Set redirect URI: https://yourdomain.com/oauth/facebook.php?action=callback
4. Copy your App ID and App Secret.
5. Edit your config:

   "facebook": {
     "enabled": true,
     "client_id": "YOUR_FACEBOOK_APP_ID",
     "client_secret": "YOUR_FACEBOOK_APP_SECRET",
     "scopes": ["email", "public_profile"]
   }

Apple Sign In

1. Go to Apple Developer Account
2. Enroll, create a Service ID, and generate a key.
3. Set redirect URI: https://yourdomain.com/oauth/apple.php?action=callback
4. Copy your Client ID, Team ID, Key ID, and download the private key file (.p8).
5. Edit your config:

   "apple": {
     "enabled": true,
     "client_id": "YOUR_APPLE_CLIENT_ID",
     "team_id": "YOUR_APPLE_TEAM_ID",
     "key_id": "YOUR_APPLE_KEY_ID",
     "private_key_path": "C:\\var\\data\\mediabrain\\AuthKey_YOUR_KEY_ID.p8",
     "scopes": ["name", "email"]
   }

After setup, your login and contact forms will support Google, Facebook, and Apple authentication. For more details, see html/includes/OAuthHandler.php and apps/help/docs/oauth-provider-setup.md.