Skip to content

Latest commit

 

History

History
260 lines (189 loc) · 5.89 KB

README.md

File metadata and controls

260 lines (189 loc) · 5.89 KB
Raw

mtos

Npm Version Minified Size Total Downloads

Gives MPA a SPA-like user experience with no refreshing and incremenal loading.

Getting Started

Install

npm install --save-dev mtos

CDN

IIFE

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mtos-iife.min.js"></script>

UMD

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mtos-umd.min.js"></script>

ESM

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mtos-esm.js"
></script>

Static

Copy

You can copy the scripts in the dist folder directly to your web server static folder.

Recommendations:

Download

You can also download the script using npm.

npm pack mtos
tar -xzf mtos-0.8.0.tgz
mv package/dist/mtos-iife.min.js .
rm -r mtos-0.8.0.tgz package

API

goto

Goto target href.

Type

function goto(href: string, push?: boolean): boolean;

Example

mtos.goto("/blog/1");

check

Check if link is internal link.

Type

function check(a: HTMLAnchorElement): boolean;

Example

mtos.check("https://localhost:5050/blog/1"); // true

setup

Setup mtos with user configuration.

Type

interface Config {
  /** Eval Script Element When Update, Default is false */
  eval?: boolean;

  /** Fetch Options */
  fetch?: RequestInit;

  /** Auto Scroll Behavior */
  scroll?: {
    enable?: boolean;
    left?: number;
    top?: number;
    behavior?: "auto" | "smooth";
  };

  /** Fetch Hooks */
  onMatch: (a: HTMLAnchorElement) => boolean;
  onFetchStart?(href: string): boolean | undefined | void;
  onFetchEnd?: (html: string, href: string) => string | undefined | void;
  onFetchError?: (error: Error, href: string) => void;

  /** Render Hooks */
  onBeforePageRendered?: (href: string) => void;
  onPageRendered?: (href: string) => void;

  /** Dom Patch Hooks */
  getNodeKey?: (node: Node) => any;
  onBeforeNodeAdded?: (node: Node) => Node;
  onNodeAdded?: (node: Node) => Node;
  onBeforeElUpdated?: (fromEl: HTMLElement, toEl: HTMLElement) => boolean;
  onElUpdated?: (el: HTMLElement) => void;
  onBeforeNodeDiscarded?: (node: Node) => boolean;
  onNodeDiscarded?: (node: Node) => void;
  onBeforeElChildrenUpdated?: (
    fromEl: HTMLElement,
    toEl: HTMLElement
  ) => boolean;
}

function setup(userConfig: Config): void;

Example

  • Use New Match Function

    Replace default match function, check if link is internal link, if true enable mtos, if false ignore this link. By default, the function is check.

    mtos.setup({
  onMatch({ host, href }) {
    return !href.endsWith("refresh") && host === window.location.host;
  },
});

  • Use Fetch Options

    Setup the fetch request options.

    mtos.setup({
  fetch: {
    headers: {
      Cookie: "xxx=yyy",
    },
    credentials: "same-origin",
  },
});

  • Use Hooks

    Use patch hooks to enable transition animation.

    mtos.setup({
  onBeforeElUpdated(fromEl, toEl) {
    if (toEl.tagName === "MAIN") {
      toEl.classList.add("animated", "fadeIn");
    }
  },
  onElUpdated(el) {
    if (el.tagName === "MAIN") {
      setTimeout(() => {
        el.classList.remove("animated", "fadeIn");
      }, 500);
    }
  },
});

  • Life Cycle

    Using life cycle hooks to update progress.

    mtos.setup({
  onFetchStart() {
    updateProgress(0);
  },
  onFetchEnd() {
    updateProgress(60);
  },
  onBeforePageRendered() {
    updateProgress(80);
  },
  onPageRendered() {
    updateProgress(100);
  },
});

mtos

Main function, add onclick property to all matched link elements.

function mtos(): void;

How It Works

Mtos works similar to SPA, but is based on native dom. The workflow like this:

  1. Query all <a> elements which property href includes current host.
  2. Add a onclick function, when clicked, fetch the html content from target link.
  3. Push link to history state.
  4. Diff current document with fetched content, update changed elements.
  5. Goto 1.

Use Cases

  • Enhance traditional Multi Page Application, so that pages do not need to be refreshed for a better user experience and no changes to the project structure are required.

  • Enhance Static Site Generators to give the original multi-page architecture a SPA-like experience.

  • Creating simple websites using just html can be used to replace the SPA + SSR architecture in many simple cases.

TODOs

  • fix: eval script block
  • feat: support diff root elements that not head and body
  • feat: cache page when hover link (optional)
  • feat: support update part of elements, like htmx
  • fix: restore scrolling position when go back
  • feat: support animation between pages
  • feat: support filer target link
  • feat: support onMount, onUnmount, ...hooks
  • feat: support fetch hook, enable request with cookie

License

MIT

Copyright (c) 2022, Raven Satir