hedberg/marko-router

Marko Frontend Router using PageJS

marko-router

Frontend Router for your Marko project.

Dependencies and Compatibilities

• Marko 4.x
• Lasso (tested with 2.x)

Install

$ npm install --save marko-router

Getting Started

This is a suggested tree view of what your Marko + Lasso project should look like when integrating with marko-router:

...
|- package.json
  ...
|- views
  |- marko.json
  |- components
    |- marko-router
      |- browser.json
      |- component.js
      |- index.marko
      |- marko-router-config.json
      |- marko-tag.json
    ...
  |- pages
    |- myRootState
      |- browser.json
      |- index.marko
      |- routeComponents
        |- myRootState-route-loading
          |- index.marko
          ...
        |- myRootState-route-myPageStart
          |- index.marko
          ...
        |- myRootState-route-myPageNext
          |- index.marko
          ...
        ...
        |- myRootState-route-myPageLast
          |- index.marko
          ...
        |- myRootState-route-notfound
          |- index.marko
          ...
    ...

Marko Router Component

After installing marko-router copy the folder ./node_modules/marko-router/components/marko-router into your Marko components folder. This component will ease the interaction with marko-router and it's fully customizable for your needs. Due to Marko/Lasso limitation I was unable to make marko-router an actual Marko component with all the features this alternative approach introduced.

Marko Router Config

// views/components/marko-router/marko-router-config.json

{
  // Root State
  "myRootState": {
    // Base path for this root state (e.g. handle all the requests at .../myRootState/*)
    "_base": "/myRootState",
    // Default state (default redirects for '/')
    "_default": "myPageStart",
    // State for myPageStart
    "myPageStart": {
      // Route segment for this state
      "path": "/myPageStart",
      // Component Details
      "component": {
        // Component Key
        "key": "myRootState-route-myPageStart",
        // Static Component Params
        "params": {}
      }
    },
    // State for myPageNext
    "myPageNext": {
      // Route segment for this state
      "path": "/myPageNext",
      // Component Details
      "component": {
        // Component Key
        "key": "myRootState-route-myPageNext",
        // Static Component Params
        "params": {}
      }
    },
    // State for myPageNext with url params
    "myPageNextWithParam": {
      // Route segment for this state
      "path": "/myPageNext/:p",
      // Component Details
      "component": {
        // Override state
        "state": "myPageNext",
        // Component Key
        "key": "myRootState-route-myPageNext",
        // Static Component Params
        "params": {}
      }
    },
    ...
    // Redirect
    "/myPageLast": "/myPageStart",
    // State to handle Not Found
    "notfound": {
      // Route segment for this state
      "path": "*",
      // Component Details
      "component": {
        // Component Key
        "key": "myRootState-route-notfound",
        // Static Component Params
        "params": {}
      }
    }
  }
}

Essentially the marko-router-config.json has the following constraints:

• Root states are always first level properties
• Root state must always define _base, _default
• Root state _base must be a url segment just starting with /
• Root state _default must be a state correctly defined within the root state
• States are always second level properties
• States cannot start with _
• States must always define path, component.key, component.params
• State path must be defined accordingly PageJS documentation
• State component.key must be exactly the key of the state component
• State component.param must be an object and if not defined must be an empty object {}

Marko Tags Definition

// views/marko.json

{
  "tags-dir": [
    "./components"
    "./pages/myRootState/routeComponents"
  ]
}

Root State - Browser

// views/pages/myRootState/browser.json

{
  "dependencies": [
    "./routeComponents/myRootState-route-loading/index.marko",
    "./routeComponents/myRootState-route-myPageStart/index.marko",
    "./routeComponents/myRootState-route-myPageNext/index.marko",
    ...
    "./routeComponents/myRootState-route-myPageLast/index.marko",
    "./routeComponents/myRootState-route-notfound/index.marko"
  ]
}

Root State - Marko

// views/pages/myRootState/index.marko

<lasso-page package-path="./browser.json" />

<!doctype html>
<html lang="en">

<head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <title>
    Root
  </title>
  <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport" />
  <meta name="viewport" content="width=device-width" />

  <lasso-head />
</head>

<body>

  <my-header selected="root" />

  <marko-router
    rootState="myRootState"
    componentPath="~/views/pages/myRootState/routeComponents" />

  <my-footer />

  <lasso-body />

  <browser-refresh />
</body>

</html>

Parameter Name	Type	Required	Default	Description
rootState	string	x		Name of the root state
configPath	string		'./marko-router-config.json'	Location of the marko-router-config.json
debug	boolean		false	Initialize marko-router with or without debug
componentPath	string		'../'	Where the route components are located
routeDelimiter	string		'-route-'	Delimiter to set between root state and state for the component
loadingState	string		loading	Name of the component to launch during loading

Events

state.change

state.change will be triggered every time the frontend router will have to handle the change of url within the same root state.

Doubts

Please check my sample at sample-marko-router

Credits

• Marko
• PageJS as Frontend Router

Please Contribute!

I'm happy to receive contributions of any kind!

Did you like my work?

Help me out with a little donation, press on the button below.