GithubHelp home page GithubHelp logo

scroll-ink's Introduction

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 "[email protected]/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 "[email protected]/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.

scroll-ink's People

Contributors

mohitk05 avatar littlestar642 avatar dependabot[bot] avatar kunalpanchal avatar

Stargazers

JaspreetKaberwal avatar Ajit jain avatar Biplab Malakar avatar Mohit Karekar avatar Kay avatar

Watchers

James Cloos avatar

Forkers

littlestar642

scroll-ink's Issues

Implement code syntax highlighting

Currently the code block is a simple <code> tag, a better implementation would be having highlighted syntax using some libraries like highlight.js.

Create generalised elements like profile section, recent blogs

Profile section can include elements like person's photo, their name and short bio. This section would appear always at some position at selected routes.

Injection of elements like profile needs to be discussed, as it would create a bit of chaos in thehandleRoutes() function. We can have some sort of generalised way of adding such elements.

Other such elements could include:

  • Recent items
  • Tagged items
  • Year wise sort

Inject meta tags inside load() and handleRoutes()

Accept meta tags related config, and dynamically add them to the <head>. Currently only a title tag is added to the global document.
For single post, inject relevant data from the blog data, e.g. title, description (subtitle) etc.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.