ncCounter v3.0.1

A simple and customizable web counter for Neocities sites.

This counter is actually a script that runs on the browser on demand. You can use as many counters as you'd like per page, as long as you specify which one to act upon when you call the function.

You don't need to register, a database, specialized software. Incredibly, you don't need to give the site name! It just works. Neocities exposes a nifty API, with a get-info call that supports calling anonymously, visitors' browsers can fetch the info themselves!

Do note that, for this script to work, a CORS proxy is used. By default, it uses CORS-Anywhere.HerokuApp.com, but can be changed.

Usage

To use ncCounter, you need to have at least one element with the "ncCounter" class. From within that ".ncCounter", there are a few elements with classes that get parsed. Any element with these classes will work:

• "ncHits" will show how many hits or views (including non-unique ones) your site has.
• "ncViews" will show how many unique visitors your site has had.
• "ncUp" will show the date and time of when the site was last updated. This class takes an argument, and possible values are "Date" and "Time", to show just that.
• "ncThisUp" will show the date and time of when the page you're viewing was last updated. Has the same structure as "ncUp"
• "ncUsername" will shor you your username on NeoCities, mine is Hibi!

Classes can take an argument, in the form of an attribute with the same name as the class. For example, getting just the date your site requires class="ncUp" ncUp="Date".

ncCounter provides an option to use localized time and date strings. To activate it, set "ncCounter.localeDate" to true before calling the script.

To call ncCounter, call "ncCounter.LoadData(0)", where the 0 is the numeric index of the counter you wish to update.

Tutorial

Using ncCounter is simple. First, you can either copy it to your site, or you can link directly to my copy (at "/ncCounter.js"). In the HTML file, add a reference to the script.

To make a counter, simply make something the "ncCounter" class. To make it count anything, make an element inside the "ncCounter" any of the classes above, like "ncViews" for unique visitors.

You can now call "ncCounter.LoadData(i)" where i is the index of the counter you want to update and as many times as you want. For most use cases, a simple call to update counter 0 on DOMContentLoaded will suffice.

The end result (preview, centered)

Technical Reference

• "ncCounter.version": Holds version info in semver "M.N.P" format.
• "ncCounter.apiData": Holds data returned from an API call. Undefined on failure or non-Neocities site.
• "ncCounter.extraData": Holds additional data not needed from an API call. This is used to save calls and net usage.
• "ncCounter.localeDate": Option to use the visitor's locale for writing date and time. Defaults to false.
• "ncCounter.LoadData(index)": Function to fetch data and fill the contents of a counter.
  1. If a successful call has been made, then jump to step 8.
  2. If a we don't have extra data, fetch them.
  3. If the counter doesn't have a blank that requires an API call,then jump to step 8.
  4. If the domain name does not end with ".neocities.org", throw "nc_domain_error".
  5. Send the info API call through the proxy (configurable, line 73).
  6. If there has been an error, throw the error type from the response.
  7. Save the returned info.
  8. Fill() the index^th counter.
• "ncCounter.Fill(index)": Fill the index^th counter with the specified data. Only selects the first element of each class.
• "ncCounter.blankClasses": Holds a registry of blank classes. Each class requires a boolean "requiresApiCall" and a string "getValue()". Classes can have subclasses, but there's no inheritance.
• "ncCounter.blankClasses.getClasses()": Returns an array of class names.

Do note that blank classes are not actual program classes, but rather the HTML classes given some functionality.

Additionally, given how JavaScript is structured, "requiresApiCall" can be left undefined if your class doesn't require a call, as undefined == false.

Changes from v3.0.0

• Fix: ncCounter would die if you tried to get views or hits

Changes from v2.0.1

• Breaking: merged ".ncUpDate" and ".ncUpTime" into ".ncUp" and made it take an argument: class="ncUp" ncUp="Date".
• Fix: ".ncUpDate" and ".ncUpTime" wouldn't work at all (.toDate/TimeString() of String).
• Added: classes taking an argument, in the form of its own name being an attribute name.
• Added: ".ncThisUp": follows the same structure as ".ncUp", but applies only to this document.
• Improve: The script will not make API calls where not needed, such as using it for a document's last modified date.