docs-home.ejs

<% include includes/style %>
<% include includes/title %>

<blockquote class="warning">
    <h2 class="title">
        <a data-section-link id="breaking-change"></a> Breaking Change<br/>
        <small>
            From version <code>0.0.5-beta2</code> onwards, the option to trigger the dark mode theme was changed from
            <code>dark: true</code> to <code>theme: macOSNotifThemes.Dark</code> as part of the theming overhaul.
        </small>
    </h2>
</blockquote>

<h3><a data-section-link id="installation" data-section-title="Installation"></a> Installation:</h3>

<p>For the easiest use, you can simply install the plugin through NPM:</p>
<pre class="code">npm i macosnotif</pre>

<p>Or, you can manually install by copying the <code>dist</code> folder from the
    <a href="https://github.com/MattIPv4/macOSNotifJS">macOSNotifJS GitHub repository</a> to your website.</p>

<p>To then have the plugin available on a page, in your head tag have the following to load the notification
    styling:</p>
<pre class="code">&lt;link href="path/to/dist/macOSNotif.min.css" rel="stylesheet"/&gt;</pre>

<p>At the bottom of your body, you then need to have the following to load the notification script:</p>
<pre class="code">&lt;script src="path/to/dist/macOSNotif.min.js"&gt;&lt;/script&gt;</pre>

<h3><a data-section-link id="usage-options" data-section-title="Usage & Options"></a> Usage &amp; Options:</h3>

<p>
    To get started, simply call the function <code>macOSNotif</code>.
    <br/>This is a wrapper for the main class <code>macOSNotifJS</code>, which creates a new instance with the
    provided options, runs the notification and then returns the new instance.
</p>

<p>To customise your notification, you can supply an object containing any of the options listed below:</p>

<pre class="code">
options = {
    delay: 0.5,                             // Delay before display (in seconds)
    autoDismiss: 0,                         // Delay till automatic dismiss (0 = Never, in seconds)
    interactDismiss: true,                  // Toggle swipe/drag to dismiss

    sounds: false,                          // Play sounds for notification
    theme: macOSNotifThemes.Light,          // Set the theme to be used by the notification (from window.macOSNotifThemes)
    themeNative: false,                     // Attempt to detect light/dark from OS, fallback to theme
    zIndex: 5000,                           // CSS z-index value of the notification (will be adjusted for stacked notifications)

    imageSrc: null,                         // Link of the icon to display (null to hide icon)
    imageName: "",                          // Alt/Title text of the icon
    imageLink: null,                        // Link for icon click (see link functionality below)
    imageLinkDismiss: true,                 // Dismiss notification after Image Link pressed (useful if link is function)
    imageLinkNewTab: false,                 // Open Image Link in New Tab (ignored if link is set to dismiss)

    title: "macOSNotifJS",                  // Main Notif Title
    subtitle: "Default notification text",  // Main Notif Sub Title

    mainLink: null,                         // Link for the main text body (see link functionality below)
    mainLinkDismiss: true,                  // Dismiss notification after Main Link pressed (useful if link is function)
    mainLinkNewTab: false,                  // Open Main Link in New Tab (ignored if link is set to dismiss)

    btn1Text: "Close",                      // Text for Button 1 (null to hide all buttons)
    btn1Link: null,                         // Link for Button 1 (see link functionality below)
    btn1Dismiss: true,                      // Dismiss notification after Button 1 pressed (useful if link is function)
    btn1NewTab: false,                      // Open Button 1 Link in New Tab (ignored if link is set to dismiss)

    btn2Text: "Go",                         // Text for Button 2 (null to hide second button)
    btn2Link: null,                         // Link for Button 2 (see link functionality below)
    btn2Dismiss: true,                      // Dismiss notification after Button 2 pressed (useful if link is function)
    btn2NewTab: false,                      // Open Button 2 Link in New Tab (ignored if link is set to dismiss)
};

// Link functionality:
//  - Use null for no link (this will act as dismiss on btn1Link & btn2Link)
//  - Use "#" to make the element act as dismiss with no further action
//  - Use any string as a URL which will open when element is clicked
//  - Use a Javascript function to be called when element is clicked
//     (Note: The notification object is passed as the 1st parameter if required)
</pre>

<blockquote class="info">
    <h2 class="title">
        <a data-section-link id="native-theme-detection"></a> Native Theme Detection<br/>
        <small>
            This feature can be enabled by setting the option <code>themeNative</code> to true. It is designed to detect
            the theme preference from the user's device (light or dark). This makes use of
            <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme" target="_blank">
                <code>prefers-color-scheme</code></a>, which is currently
            <a href="https://caniuse.com/prefers-color-scheme" target="_blank">only supported by Safari</a> at the time
            of writing. Therefor, I suggest ensuring you set the correct fallback <code>theme</code> for your
            notifications if you are to use <code>themeNative</code>.
        </small>
    </h2>
</blockquote>

<h3><a data-section-link id="browser-support" data-section-title="Browser Support"></a> Browser Support:</h3>
<p>
    macOSNotifJS is built to have support for the following browser definitions.
    <br/><i>You can click on each one to view a full breakdown of every browser the definition covers.</i>
</p>

<ul>
    <% for (var def in browsers) { %>
        <li><a href="<%= browsers[def][0] %>" target="_blank">
                <%= browsers[def][1] %></a></li>
    <% } %>
</ul>

<hr/>

<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<!-- Banner 1 -->
<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4266526051230566"
     data-ad-slot="9114202102"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
    (adsbygoogle = window.adsbygoogle || []).push({});
</script>

<hr/>

<h3><a data-section-link id="examples" data-section-title="Examples"></a> Examples:</h3>

<h4><a data-section-link id="button-configuration" data-section-title="Examples: Button Configuration"></a>
    Button Configuration:</h4>

<button data-demo-load
        onclick="macOSNotif({title:'Dual button notification', subtitle:'Two buttons; dismiss and a link (opens in a new tab)', btn1Text:'Close', btn1Link:null, btn2Text:'Author', btn2Link:'https://mattcowley.co.uk/', btn2NewTab:true})">
    Dual button notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Dual button notification',
    subtitle:'Two buttons; dismiss and a link (opens in a new tab)',
    btn1Text:'Close',
    btn1Link:null,
    btn2Text:'Author',
    btn2Link:'https://mattcowley.co.uk/',
    btn2NewTab:true
})</pre>

<br/>

<button data-demo-load
        onclick="macOSNotif({title:'Single button notification', subtitle:'A single button to dismiss the notification', btn2Text:null})">
    Single button notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Single button notification',
    subtitle:'A single button to dismiss the notification',
    btn2Text:null
})</pre>

<br/>

<button data-demo-load
        onclick="macOSNotif({title:'Main body link notification', subtitle:'The main notification body is a link (opens in a new tab)', mainLink:'https://mattcowley.co.uk/', mainLinkNewTab:true})">
    Main body link notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Main body link notification',
    subtitle:'The main notification body is a link (opens in a new tab)',
    mainLink:'https://mattcowley.co.uk/',
    mainLinkNewTab:true
})</pre>

<br/>

<button data-demo-load
        onclick="macOSNotif({title:'No button notification', subtitle:'The main body link dismisses the notification', mainLink:'#', btn1Text:null})">
    No button notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'No button notification',
    subtitle:'The main body link dismisses the notification',
    mainLink:'#',
    btn1Text:null
})</pre>

<br/>

<button data-demo-load
        onclick="macOSNotif({title:'Javascript callback button', subtitle:'Any link can be set to call a Javascript function', mainLink:'#', btn1Text:'Ping!', btn1Link:function(){alert('Pong!');}, btn1Dismiss:false, btn2Text:null})">
    Javascript callback button
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Javascript callback button',
    subtitle:'Any link can be set to call a Javascript function',
    mainLink:'#',
    btn1Text:'Ping!',
    btn1Link:function(){alert('Pong!');},
    btn1Dismiss:false,
    btn2Text:null
})</pre>

<hr/>

<h4><a data-section-link id="notification-customisation" data-section-title="Examples: Notification Customisation"></a>
    Notification Customisation:</h4>

<button data-demo-load
        onclick="macOSNotif({title:'Image (icon) notification with link', subtitle:'Has an icon which also has a link', imageSrc:'https://mattcowley.co.uk/me.png', imageLink:'https://mattcowley.co.uk/', imageLinkNewTab:true})">
    Image (icon) notification with link
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Image (icon) notification with link',
    subtitle:'Has an icon which also has a link',
    imageSrc:'https://mattcowley.co.uk/me.png',
    imageLink:'https://mattcowley.co.uk/',
    imageLinkNewTab:true
})</pre>

<br/>

<button onclick="macOSNotif({title:'Sound (alert) notification', subtitle:'Requires user interaction first on some browsers', sounds:true})">
    Sound (alert) notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Sound (alert) notification',
    subtitle:'Requires user interaction first on some browsers',
    sounds:true
})</pre>

<hr/>

<h4><a data-section-link id="theming-support" data-section-title="Examples: Theming Support"></a> Theming Support:</h4>

<button data-demo-load
        onclick="macOSNotif({title:'Dark mode notification', subtitle:'Emulates the macOS dark mode styling', theme:macOSNotifThemes.Dark, mainLink:'#', btn1Text:'Dark', btn1Dismiss:false, btn1Link:function(n){n.theme = macOSNotifThemes.Dark;}, btn2Text:'Light', btn2Dismiss:false, btn2Link:function(n){n.theme = macOSNotifThemes.Light;}})">
    Dark mode notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Dark mode notification',
    subtitle:'Emulates the macOS dark mode styling',
    theme:macOSNotifThemes.Dark,
    mainLink:'#',
    btn1Text:'Dark',
    btn1Dismiss:false,
    btn1Link:function(n){n.theme = macOSNotifThemes.Dark;},
    btn2Text:'Light',
    btn2Dismiss:false,
    btn2Link:function(n){n.theme = macOSNotifThemes.Light;}
})</pre>

<br/>

<button onclick="macOSNotif({title:'Native theme notification', subtitle:'Attempts to match the theme preference of the OS', themeNative:true, mainLink:'#', btn1Text:'Close', btn1Link:null, btn2Text:'Support', btn2Link:'https://caniuse.com/prefers-color-scheme', btn2NewTab:true})">
    Native OS theme notification (macOS dark mode)
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Native theme notification',
    subtitle:'Attempts to match the dark/light theme of the OS',
    themeNative:true,
    btn1Text:'Close',
    btn1Link:null,
    btn2Text:'Support',
    btn2Link:'https://caniuse.com/prefers-color-scheme',
    btn2NewTab:true
})</pre>

<br/>

<button onclick="macOSNotif({title:'Info themed notification', subtitle:'Non-macOS theme to convey information', theme:macOSNotifThemes.Info, btn2Text:null})">
    Info themed notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Info themed notification',
    subtitle:'Non-macOS theme to convey information',
    theme:macOSNotifThemes.Info,
    btn2Text:null
})</pre>

<br/>

<button onclick="macOSNotif({title:'Warning themed notification', subtitle:'Non-macOS theme to convey a warning message', theme:macOSNotifThemes.Warning, btn2Text:null})">
    Warning themed notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Warning themed notification',
    subtitle:'Non-macOS theme to convey a warning message',
    theme:macOSNotifThemes.Warning,
    btn2Text:null
})</pre>

<br/>

<button onclick="macOSNotif({title:'Danger themed notification', subtitle:'Non-macOS theme to convey an immediate danger', theme:macOSNotifThemes.Danger, btn2Text:null})">
    Danger themed notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Danger themed notification',
    subtitle:'Non-macOS theme to convey an immediate danger',
    theme:macOSNotifThemes.Danger,
    btn2Text:null
})</pre>

<br/>

<button onclick="macOSNotif({title:'Success themed notification', subtitle:'Non-macOS theme to convey success', theme:macOSNotifThemes.Success, btn2Text:null})">
    Success themed notification
</button>
<br/>
<pre class="code">macOSNotif({
    title:'Success themed notification',
    subtitle:'Non-macOS theme to convey success',
    theme:macOSNotifThemes.Success,
    btn2Text:null
})</pre>

<hr/>

<h2 class="title">
    <%= name %>
    <br/>
    <small>
        <%= name %> is a plugin created by <a href="https://mattcowley.co.uk/" target="_blank">Matt Cowley</a>.
        <br/>
        <br/><i><%= `${name} - v${version} - ${dateOfBuild}` %></i>
    </small>
</h2>

<script src="/dist/macOSNotif.min.js"></script>

<script>
    // Generate section links
    var elms = document.querySelectorAll("a[data-section-link]");
    for (var i = 0; i < elms.length; i++) {
        elms[i].innerHTML = "<span>&#x1f517;</span>";
        elms[i].href = "#" + elms[i].id;
        elms[i].classList.add("section-link");
        elms[i].parentElement.classList.add("has-section-link");
    }

    // Add section links to sidebar of JSDoc
    setTimeout(function () {
        var elms = document.querySelectorAll("a[data-section-link][data-section-title]");
        var sidebar = document.querySelector("body>nav");
        if (sidebar) {
            var ul = document.createElement("ul");
            sidebar.insertBefore(ul, sidebar.children[1]);

            for (var j = 0; j < elms.length; j++) {
                var a = document.createElement("a");
                a.href = elms[j].href;
                a.textContent = elms[j].getAttribute("data-section-title");

                var li = document.createElement("li");
                li.appendChild(a);
                ul.appendChild(li);
            }

            var h3 = document.createElement("h3");
            h3.textContent = "Overview";
            sidebar.insertBefore(h3, ul);
        }
    }, 500);

    // Redirect from old domain
    if (window.location.hostname === "macosnotifjs.mattcowley.co.uk") window.location.replace("https://macosnotif.js.org");

    // Show demo notifications
    var buttons = document.querySelectorAll("button[data-demo-load]"),
        delay = 750;
    window.macOSNotifFadeThreshold = buttons.length;

    function click(i) {
        if (i < buttons.length) {
            buttons[i].click();
            i++;
            setTimeout(function () {
                click(i);
            }, delay);
        }
    }

    click(0);
</script>

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-113826252-5"></script>
<script>
    window.dataLayer = window.dataLayer || [];

    function gtag() {
        dataLayer.push(arguments);
    }

    gtag("js", new Date());

    gtag("config", "UA-113826252-5");
</script>