WoowahanJS

The examples directory contains various implementations demonstrating the core capabilities of WoowahanJS. You can use these examples to understand specific patterns such as data binding, routing, and component management.

Key example types available:

• Data Binding: See bind for one-way data binding implementations.
• List Rendering: See listview for displaying collection data from an API server in a list view.
• Global Components: See modal to learn how to register and use common view components (e.g., Bootstrap modals) across a web app.
• Routing: See route for implementing routing within a Single Page Application (SPA) structure.
• Data Validation: See schema to understand how to define action message structures and validate data.
• Full Application Patterns: See todo for a WoowahanJS implementation of the TODO MVC specification to compare development patterns with other frameworks.

To avoid tight coupling between your view logic and your UI structure (like CSS class names), use the data-ref attribute in your templates. When an element has a data-ref attribute, it is automatically assigned to the this.refs object within your view, allowing you to access it reliably even if the underlying HTML structure or CSS classes change.

Instead of using selector-based lookups like this.$el.find('.class-name'), use this.$(this.refs.refName).

<div class="container">
    <div class="alert alert-success" role="alert" data-ref="alert">Message</div>
    <button type="button" class="btn btn-toggle">Toggle</button>
</div>

Woowahan.View.create('Foo', {
  template: Template,
  events: {
    'click .btn-toggle': 'onToggleElement'
  },

  onToggleElement(event) {
    // Access the element via this.refs instead of a CSS selector
    this.$(this.refs.alert).toggle();
  }
});

The View lifecycle follows this sequence: initialize $\rightarrow$ viewWillMount $\rightarrow$ rendering $\rightarrow$ viewDidMount $\rightarrow$ viewWillUnmount $\rightarrow$ remove.

• initialize(): Runs once when the view is created. Use it for setup.
• viewWillMount(renderData): Called before rendering. You can modify renderData (a copy of the model) to influence the final HTML. You must return renderData for changes to take effect. Modifying the model directly via this.setModel() inside this method will not reflect in the current render cycle.
• viewDidMount($el): Called immediately after rendering and DOM loading. The argument $el is a jQuery object representing the view's DOM element.
• viewWillUnmount(): Called before the view is removed.
• remove(): Final stage of destruction.

/* Correct way to modify data for rendering */
viewWillMount(renderData) {
  renderData.name = `Hello, ${renderData.name}`;
  return renderData;
}

/* Correct way to use the DOM after mount */
viewDidMount($el) {
  $el.find('.switch').toggleClass('on');
}

To avoid tight coupling between parent and child views, use @event syntax. Instead of the parent listening to specific DOM selectors inside the child, the child dispatches a custom event, and the parent listens for that event name prefixed with @.

1. In the Child View: Use this.dispatch(Woowahan.Event.create('eventName')) to broadcast an event.
2. In the Parent View: Define the event in the events object using the @eventName syntax.

If a parent has multiple child views in different containers, you can specify a selector to target a specific child: @eventName .selector.

// Child View: Dispatches the event
var childView = Woowahan.View.create('Child', {
  events: {
    'click .btn.btn-search': 'onSearch'
  },
  
  onSearch() {
    this.dispatch(Woowahan.Event.create('search'));
  }
});

// Parent View: Listens for the dispatched event
var parentView = Woowahan.View.create('Parent', {
  events: {
    '@search': 'onSearch'
  },
    
  viewDidMount() {
    this.updateView('.search-form', childView);
  },
  
  onSearch() {
    // Triggered when childView dispatches 'search'
  }
});

You can simplify event handlers by instructing the events configuration to automatically collect data from specific DOM selectors and pass them as arguments to the handler.

• Single Selector: onSearch(input[name=keyword]) passes the value of the element matching the selector.
• Multiple Selectors: onSearch(input[name=keyword], .search.option) passes multiple values.
• Form Data: If the selector is a FORM (e.g., @submit .join-form), the handler receives the form object containing all its input data (e.g., form.name, form.password).

Note: this.$el is a jQuery object representing the view's root element, allowing you to perform standard jQuery operations.

// Example: Collecting multiple inputs via selectors
var childView = Woowahan.View.create('Child', {
  events: {
    '@click .btn-search': 'onSearch(input[name=keyword], .search.option)'
  },
  
  onSearch(keyword, option) {
    // keyword and option are automatically extracted from the DOM
  }
});

// Example: Collecting all form data on submit
var childView = Woowahan.View.create('Child', {
  events: {
    '@submit .join-form': 'onJoin()'
  },
  
  onJoin(form) {
    // form contains all sub-element data (e.g., form.username)
  }
});