web-mojo

WEB-MOJO Framework 2.1.0

WEB-MOJO is a modern, lightweight JavaScript framework for building data-driven web applications. Built with a core + extensions architecture, WEB-MOJO provides maximum flexibility while maintaining clean boundaries and optimal performance.

Part of the MOJO Framework Family - WEB-MOJO is the browser-based framework. See our other MOJO frameworks for native mobile and desktop applications.

📚 Documentation

📖 View Full Documentation

Complete guides covering:

• Application Layer - WebApp, PortalApp, Pages
• Core Concepts - View, Model, Collection, Templates, Events
• Components - Sidebar, TopNav, Dialog, TableView, DataView, and more
• Extensions - Charts, Maps, Admin tools, FileUpload, LightBox, TabView, and more
• Best Practices - KISS principles, common pitfalls, optimization

✨ Key Features

🏗️ Core + Extensions Architecture - Clean separation with plugin system
📦 Subpath Exports - Import exactly what you need
⚡ Lazy Loading - Reduced bundle sizes with dynamic imports
🔌 Plugin System - Extensions enhance core without dependencies
🎯 Tree Shaking - Optimized builds with modern bundlers
🎨 Mustache Templates - Logic-less templates with 70+ formatters
📊 Data-Driven - Model and Collection classes with REST API integration
🎭 Event Delegation - Convention-based event handling

🚀 Quick Start

Installation

npm install web-mojo

Basic Usage

// Core framework
import { WebApp, Page, View } from 'web-mojo';

// Create a simple page
class HomePage extends Page {
  constructor(options = {}) {
    super({
      template: `
        <div class="home">
          <h1>Welcome to WEB-MOJO!</h1>
          <p>Building modern web apps made simple.</p>
        </div>
      `,
      ...options
    });
  }
}

// Initialize app
const app = new WebApp({
  name: 'My App',
  container: '#app'
});

app.registerPage('home', HomePage);
app.start();

With Data Models

import { View, Model } from 'web-mojo';

class User extends Model {
  urlRoot = '/api/users';
}

class UserProfileView extends View {
  template = `
    <div class="profile">
      <h2>{{model.name}}</h2>
      <p>{{model.email}}</p>
      <p>Member since: {{model.created_at|date}}</p>
    </div>
  `;
}

// Usage
const user = new User({ id: 123 });
await user.fetch();

const view = new UserProfileView({ model: user });
await view.render();
await view.mount(document.body);

📦 Architecture

WEB-MOJO uses a core + extensions architecture:

Core Package (web-mojo)

The stable runtime and building blocks:

• WebApp & PortalApp - Application containers with routing
• View & Page - Component system with lifecycle hooks
• Model & Collection - Data layer with REST API integration
• Router - URL routing and navigation
• Dialog - Modal system
• Templates - Mustache templating with 70+ data formatters
• Events - Convention-based event delegation
• Essential utilities - File upload, geolocation, utilities

Extensions

Feature-rich packages that extend core functionality:

🔐 Authentication (web-mojo/auth)

Complete authentication system with JWT tokens, login/register forms, and session management.

🖼️ Lightbox (web-mojo/lightbox)

Image and PDF viewers with editing capabilities including cropping and annotation.

📊 Charts (web-mojo/charts)

Interactive charts built on Chart.js with PieChart, SeriesChart, and more.

📚 Documentation (web-mojo/docit)

Full-featured documentation portal system with markdown editing and syntax highlighting.

🗺️ Maps (web-mojo/map)

MapLibre GL integration with geolocation tracking and custom controls.

⚡ Loader (web-mojo/loader)

Beautiful loading animations and progress indicators.

🎯 Core Concepts

Views - Component System

Views are the building blocks of your UI with a complete lifecycle:

import { View } from 'web-mojo';

class TodoView extends View {
  template = `
    <div class="todo {{#completed}}completed{{/completed}}">
      <input type="checkbox" {{#completed}}checked{{/completed}} data-action="change:toggle">
      <span>{{title}}</span>
      <button data-action="click:remove">×</button>
    </div>
  `;
  
  toggle() {
    this.model.set('completed', !this.model.get('completed'));
    this.model.save();
  }
  
  remove() {
    this.model.destroy();
  }
}

→ View Documentation

Models - Data Layer

Models manage your data with built-in REST API integration:

import { Model } from 'web-mojo';

class Todo extends Model {
  urlRoot = '/api/todos';
  
  defaults() {
    return {
      title: '',
      completed: false,
      created_at: new Date()
    };
  }
  
  validate(attrs) {
    if (!attrs.title || attrs.title.trim() === '') {
      return 'Title is required';
    }
  }
}

// Usage
const todo = new Todo({ title: 'Learn WEB-MOJO' });
await todo.save(); // POST /api/todos

todo.set('completed', true);
await todo.save(); // PUT /api/todos/123

→ Model Documentation

Templates - Mustache with Formatters

Logic-less templates with powerful data formatting:

template = `
  <div class="user-card">
    <h3>{{model.name|uppercase}}</h3>
    <p>{{model.email|lowercase}}</p>
    <p>Joined: {{model.created_at|date:'MMM dd, YYYY'}}</p>
    <p>Revenue: {{model.total_revenue|currency}}</p>
    
    {{#model.is_active|bool}}
      <span class="badge-success">Active</span>
    {{/model.is_active|bool}}
  </div>
`;

70+ built-in formatters for dates, numbers, text, HTML, and more!

→ Templates Documentation

Events - Convention-Based

Clean event handling with data attributes:

class ButtonView extends View {
  template = `
    <button data-action="click:handleClick">Click Me</button>
    <input data-action="input:handleInput" placeholder="Type here">
  `;
  
  handleClick(e) {
    console.log('Button clicked!');
  }
  
  handleInput(e) {
    console.log('Input value:', e.target.value);
  }
}

→ Events Documentation

🏗️ Portal Applications

Build admin portals and dashboards with PortalApp:

import { PortalApp, Page } from 'web-mojo';

const app = new PortalApp({
  name: 'Admin Portal',
  sidebar: {
    menus: [{
      title: 'Main',
      items: [
        { text: 'Dashboard', route: 'dashboard', icon: 'bi-speedometer2' },
        { text: 'Users', route: 'users', icon: 'bi-people' },
        { text: 'Settings', route: 'settings', icon: 'bi-gear' }
      ]
    }]
  }
});

app.registerPage('dashboard', DashboardPage);
app.registerPage('users', UsersPage);
app.start();

📖 Documentation Structure

Our documentation is organized into focused sections — browse online or click any link below:

Application Layer

• WebApp — routing, state, REST, EventBus
• PortalApp — auth, sidebar, topbar, groups
• Page — routed pages, onEnter/onExit, params

Core Concepts

• View — component lifecycle, templates, actions
• Templates — Mustache + 70+ formatters ⚠️ read pitfalls
• Model — data layer with REST integration
• Collection — lists, pagination, querying
• Events — EventBus, EventEmitter, delegation
• DataFormatter — all 80+ built-in formatters

Services

• Rest — HTTP client: GET/POST/PUT/PATCH/DELETE, file upload
• ToastService — Bootstrap 5 toast notifications
• WebSocketClient — auto-reconnect WebSocket

Components

• Sidebar & TopNav — portal navigation, homeless pages
• Dialog — modals, alerts, confirms, busy indicator
• TableView / TablePage — data tables
• ListView — list component for collections
• DataView — structured data display

Extensions

• Charts — Chart.js integration (SeriesChart, PieChart)
• Admin — pre-built admin pages and views
• TabView — tab navigation
• MapView / MapLibreView — maps
• Location — geolocation services
• LightBox — image lightbox
• FileUpload — file upload utilities
• TimelineView — timeline visualization

Essential Reading Order

• View.md — understand the component lifecycle
• Templates.md — learn Mustache + pipe formatters ⚠️ read the pitfalls!
• Model.md — connect to your REST API
• Collection.md — work with lists of data
• WebApp.md — wire the app together
• Page.md — create routed pages

🎨 Philosophy

WEB-MOJO follows these core principles:

KISS - Keep It Simple, Stupid

• Simple patterns over complex abstractions
• Readable code over clever code
• Convention over configuration

Model-First Approach

• Use models directly in templates
• Avoid custom data structures
• Let formatters handle presentation

Logic-Less Templates

• Business logic in views, not templates
• Formatters for display formatting
• View methods for computed values

→ Read More About Our Philosophy

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone repository
git clone https://github.com/NativeMojo/web-mojo.git
cd web-mojo

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Run tests
npm test

Project Structure

web-mojo/
├── src/
│   ├── core/              # Core framework (View, Model, Collection, Router…)
│   ├── extensions/        # Optional extensions (charts, maps, admin, auth…)
│   └── styles/            # CSS styles
├── docs/
│   └── web-mojo/          # Framework documentation (served on GitHub Pages)
│       ├── core/          # WebApp, PortalApp, View, Model, Collection, Events…
│       ├── pages/         # Page (routed screens)
│       ├── services/      # Rest, ToastService, WebSocketClient
│       ├── components/    # Sidebar & TopNav, Dialog, TableView, ListView…
│       ├── extensions/    # Charts, Admin, Maps, LightBox, TabView, FileUpload…
│       ├── models/        # Built-in models (User, Group, Job, Email…)
│       ├── utils/         # MOJOUtils
│       ├── mixins/        # EventEmitter & EventDelegate
│       ├── README.md      # Documentation index
│       └── index.html     # Interactive documentation portal
├── examples/              # Working example projects
└── tests/                 # Test suites

🤝 Contributing

We welcome contributions! Please:

• Read our Contributing Guide
• Check existing issues
• Follow our coding standards
• Write tests for new features
• Update documentation

Documentation Contributions

Documentation improvements are especially welcome! Ensure:

• ✅ Examples are tested and working
• ✅ Common pitfalls are documented
• ✅ Cross-references are updated
• ✅ KISS principles are followed

📝 License

Apache 2.0 - See LICENSE file

🔗 Links

• Documentation - Complete framework documentation
• NPM Package - Install from npm
• GitHub Repository - Source code
• Issues - Report bugs
• Examples - Working example projects

🌟 Community

• Website: nativemojo.com
• Discussions: GitHub Discussions
• Issues: GitHub Issues

Built with ❤️ by the NativeMojo team