Spargo NPM | npm.io

Spargo.js

The lightweight JavaScript framework for inserting a little reactivity into some markup.

Why Spargo?

Spargo has many meanings: awesome, sprinkle, practicality, etc. We believe all of these represent a piece of Spargo.js; which is designed to add just a little reactivity to your otherwise boring markup.

Getting Started

NPM

npm i spargo

Then just import it and create a new instance of the Spargo class.

CDN

Just add the CDN to the head tag. There is both a minified version (cdn.min.js) and non-minified (cdn.js).

<head>
    <!-- Other Items in head tag -->
    <script src="https://unpkg.com/spargo@1.5.0/dist/cdn.min.js" defer></script>
</head>

Contributing

clone this repo locally
run npm install & npm run start
Include the /dist/cdn.js file from a script tag on a webpage and you're good to go!

Docs

Docs are available at https://spargojs.dev.

ignite

Used to make a piece of your markup reactive.

<div ignite="home">
    <!-- Reactive Content -->
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            // Pieces of data, methods, getters, setters, etc.
        }
    }
</script>

@sync

Similar to Vue's v-model, it will keep a piece of state in sync.

<div ignite="home">
    <input type="text" id="message" name="message" placeholder="Message" @sync="message" />
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            message: 'hello world',
        }
    }
</script>

@text

Used to display a piece of state as a value.

<div ignite="home">
   <span @text="message"><!-- Will have value hello world --></span>
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            message: 'hello world',
        }
    }
</script>

@if / @elseif / @else

Used to conditionally show markup.

<div ignite="home">
    <div @if="show">Showing the if</div>
    <div @elseif="orShow">Showing the else if</div>
    <div @else>Finally, show the else</div>
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            show: true,
            orShow: false,
        }
    }
</script>

@click

Used to add a click event to an element.

<div ignite="home">
     <button type="button" @click="show">Show</button>
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            display: false,
            show() {
                this.display = true;
            },
        }
    }
</script>

@class

Used to conditionally add classes to an element. The syntax is: condition => classes if true || classes if false.

<div ignite="home">
     <button type="button" @class="marginTop => mt-4 || mt-0">Show</button>
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            marginTop: true,
        }
    }
</script>

@href

Used to programmatically set an elements href attribute.

<div ignite="home">
    <a @href="href">Go Home</a>
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            href: '/home',
        }
    }
</script>

@for

Similar to Vue's v-for, it is used to iterate over a piece of state and display markup in the process.

<div ignite="home">
    <div>
        <button type="button" @click="addPortugal">Add Portugal</button>
        <!-- Doing a named value tells Spargo it is a flat array -->
        <div @for="country in countries">
            <p @text="country"></p>
        </div>
        <!-- Doing an unnamed value (with an underscore) tells Spargo it is an array of objects -->
        <div @for="_ in users">
            <!-- Since Spargo is aware it is supposed to expect an array of objects, there is -->
            <!-- no need to include the value followed by a dot and a key (dot-notation). The @for -->
            <!-- could have been "user in users", and the @text user.name - going with convention. -->
            <!-- However, Spargo decided to keep things simple, and go a shorthand route. -->
            <p @text="name"></p>
            <p @text="email"></p>
        </div>
    </div>
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            users: [
                {
                    name: 'Jon Doe',
                    email: 'jdoe@example.org'
                },
                {
                    name: 'Jane Cool',
                    email: 'jcool@example.org'
                },
                {
                    name: 'Jack Foo',
                    email: 'jfoo@example.org'
                },
                {
                    name: 'Jim Bar',
                    email: 'jbar@example.org'
                }
            ],
            countries: [
                'America',
                'Canada',
                'Mexico',
                'England'
            ],
            addPortugal() {
                // Spargo.js will not react to array or object changes. 
                // A simple workaround is to overwrite.
                this.countries = [...this.countries, 'Portugal'];
            },
        }
    }
</script>

@mask

Used to automatically format a text input field as a user types. Right now, there are only certain options:

phone (US Format)
currency (Any Format)
date (US Format, mm/dd/yyyy)

<div ignite="home">
    <!-- As the user types, the value will be masked and updated 
         to a properly formatted US phone number -->
    <input 
        type="tel" 
        id="mask-phone" 
        name="mask-phone" 
        placeholder="Phone" 
        @sync="maskPhone" 
        @mask="phone" 
    />
    <!-- As the user types, the value will be masked and updated 
         to a properly formatted US currency value -->
    <input 
        type="text" 
        id="mask-currency-usd" 
        name="mask-currency-usd" 
        placeholder="USD" 
        @sync="maskCurrencyUsd" 
        @mask="currency" 
    />
    <!-- You may pass arguments to the currency mask via @mask-args.
         It is a pipe (|) delimited string of {local}|{currency} -->
    <input
        type="text"
        id="mask-currency-gbp"
        name="mask-currency-gbp"
        placeholder="GBP"
        @sync="maskCurrencyGbp"
        @mask="currency"
        @mask-args="en-GB|GBP"
    />
    <!-- As the user types, the value will be masked and updated 
         to a properly formatted US date (mm/dd/yyyy) -->
    <input
        type="text"
        id="mask-date"
        name="mask-date"
        placeholder="Date"
        @sync="date"
        @mask="date"
    />
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            maskPhone: '',
            maskCurrencyUsd: '',
            maskCurrencyGbp: '',
            date: '',
        }
    }
</script>

getters

Used to add a more complicated expression to other features.

<div ignite="home">
    <div @if="show">Showing the if</div>
    <div @elseif="shouldShowElseIf">Showing the else if</div>
    <div @else>Finally, show the else</div>
    <button type="button" @click="showElse" @if="shouldShowElse">Show Else</button>
    <label for="latin">Latin</label>
    <input type="text" id="latin" name="latin" placeholder="Latin" @sync="latin" />
    <div>
        <span @text="getter"></span>
    </div>
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            show: true,
            orShow: false
            latin: 'dum spiro spero',
            get getter() {
                return `Will add on to latin: ${this.latin}`
            },
            get shouldShowElseIf() {
                return this.orShow;
            },
            get shouldShowElse() {
                return this.show || this.orShow;
            },
            showElse() {
                this.show = false;
                this.orShow = false;
            },
        }
    }
</script>

setters

Used to conduct several actions off of setting a value.

<div ignite="home">
     <div>
        <label for="setter">
            Setter
        </label>
        <input type="text" id="setter" name="setter" placeholder="Setter" @sync="updateSetterValue" />
    </div>
    <div>
        <span @text="setterValue"></span>
        <span @text="setterCount"></span>
    </div>
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            setterCount: 0,
            setterValue: null,
            set updateSetterValue(value) {
                this.setterCount++;
                this.setterValue = value;
            },
        }
    }
</script>

ignited

One of the lifecycle methods. This method will be run once the initialization process is done.

<div ignite="home">
    <!-- Reactive Content -->
</div>
<script nonce="someRandomNonce">
    function home() {
        return {
            message: 'hello world',
            ignited() {
                // This is a good spot to do an API request for data!
                console.log(this.message);
            },
        }
    }
</script>