@shaai/scroll-ink

Ink template for Shaai

Usage no npm install needed!

<script type="module">
  import shaaiScrollInk from 'https://cdn.skypack.dev/@shaai/scroll-ink';
</script>

README

Scroll

Ink

npm version

Scrolls

Scrolls (aka templates) are a pre-defined way of displaying data from Shaai. They are named as scroll-*, * being the name. Ink's npm package, hence, is @shaai/scroll-ink.

Usage

Shaai is a pluggable blogging framework, allowing you to use elements as per your need. All the scrolls use the @shaai/core package internally to source the blog data. According to your environment, you may use a scroll in following ways:

1. Using with React

Using Shaai with React is super easy, thanks to our React wrapper @shaai/react. Install the two dependencies required.

// You can replace scroll-ink with any other scroll of your choice

npm install --save @shaai/scroll-ink @shaai/react

And use them as follows:

import withShaai from '@shaai/react'
import ScrollInk from '@shaai/scroll-ink'

const Shaai = withShaai(ScrollInk)

const App = function(props) {
    return <div>
        <Shaai config={config} />
    </div>
}

const config = {
    // Described below
}

To include styles, add this line to your CSS file: @import "~@shaai/scroll-ink/dist/main.css"

2. Using with Vanilla JavaScript

  • Using in a Node dev environment

    To use in a Node project, install scroll-ink first.

    npm install --save @shaai/scroll-ink

    Then import and initialise it with the config object.

    import ScrollInk from '@shaai/scroll-ink'

const s = new ScrollInk(config)

// define your own templates
const templates = [/* template array discussed below */]

// Load whenever ready. If no templates are sent, Ink uses its default templates.
s.load(templates)

// Subscribe to updates
s.subscribe((dom) => {
    let b = document.getElementById('blog')
    b.innerHTML = ''
    b.append(dom)
})

    To include styles, add this line to your CSS file: @import "~@shaai/scroll-ink/dist/main.css"

  • Using in the browser To use Shaai in the browser directly, we recommend using unpkg to source the build files. Just include these lines inside your <head> tag of your HTML document.

    <link rel="stylesheet" type="text/css" href="https://unpkg.com/@shaai/scroll-ink/dist/main.css">
<script src="https://unpkg.com/@shaai/scroll-ink/dist/main.js"></script>

    This will include the latest js and css build files from the scroll-ink npm package, which make the ScrollInk property available globally. The rest of the process is quite similar to the above one.

    let s = new ScrollInk(config)
window.onload = function() {
    s.load()
    s.subscribe(function(dom) {
        document.getElementById('blog').innerHTML = ''
        document.getElementById('blog').append(dom)
    })
}

Here's a short video to setup your first blog using Shaai and React.

Setting up your first blog

The config object

Each Shaai instance needs to be initialised with a config object to make Shaai work as the way you want. You can pass in following properties currently:

Property Type Description Default
source object Has information about where to source the blog data from required
basePath string Relative path where your blog will rest e.g. /blog ''
blogHeader object / HTMLElement Data to be rendered in the blog header { title: 'My blog' } Default header
blogFooter object / HTMLElement Data to be rendered in the blog footer { title: 'Some text' } Default header
globalHeader boolean If true, the header will be shown on all routes. Can be overriden at route level in the templates. false
globalFooter boolean If true, the footer will be shown on all routes. Can be overriden at route level in the templates. false
globalNav boolean If true, the nav bar will be shown on all routes. Can be overriden at route level in the templates. false
source object
Property Type Description Default
name string Name of the data source CMS / FS / MEDIUM 'CMS'
config object Contains config data for the source e.g. { blogCode: 12345asdf } for source = 'CMS' required

Templates

Templates are the route-based views in scroll-ink. It is an array of template objects which have following properties:

path

This is the path/route for the template. Whenever the window path matches this value, the corresponding template will be rendered.

fetch

This is the method which is called before rendering the respective view. It receives the shaai instance, the store and the url params. While most views would requiring fetching data, you can skip this property if only static data has to be rendered.

template

This is the function that returns the actual DOM snippet for the matched path. It receives the data received from the fetch function, if any, and should return a HTMLElement object.

name

This property is used at places like the navigation bar, to mention the matched path's name.

A template object can look as below

const templates = [
    {
        path: '/',
        name: 'Posts',
        template: (data) => s.list(data, { minimiseContent: true, viewFilter: ['title', 'content', 'publishData'] }),
        fetch: (shaai, store, params) => {
            return new Promise(res => {
                if(store.getData('posts')) {
                    res(store.getData('posts'))
                }
                shaai.getBlogs().then(data => {
                    store.setData({ posts: data.items })
                    res(data.items)
                })
            })
        }
    },
    {
        path: '/about',
        name: 'About',
        template: ({ config }) => {
            let html = `
                <div>
                    <h4 class="about-heading">About me</h4>
                    <p class="about-content">Hello there! I am <a href="https://github.com/mohtik05">@mohitk05</a></p>
                </div>
            `
            let about = document.createElement('div')
            about.className = 'about'
            about.innerHTML = html

            return about
        }
    }
]

Development

Run npm run start:dev for starting the Webpack dev server.