2.4.0 • Published 2 years ago

point-system v2.4.0

Weekly downloads
-
License
MIT
Repository
github
Last release
2 years ago

Point system

A Javascript point system for websites

This point system stores points for individual users with which users are able to buy/unlock some items you provide. These items may be some parts of your website or just some decoration.
Please note that the data is not encrypted and that this library should not be used for securing important parts of your website!
For a live example take a look at this page

Installation

To add the library to your project run the following command in your terminal

npm install point-system

and import the script via the script tag

<script src="./node_modules/point-system/script.js"></script>

or use the import via unpkg

<script src="https://unpkg.com/point-system/script.js"></script>

After importing the script, you have access to the PTM Class and you can intialize it like so. The constructor awaits a array of items as the first argument.

const ptm = new PTM(items);

After initializing you can setup buttons for buying items like the following given that the name of the item you want to buy is 'javascript badge'

btnElement.addEventlistener("click", () => {
	ptm.buyItem("javascript badge"); // will add the item to user's items and charge the user accordingly, only possible if user's balance is sufficient
});

You can check the items owned by the user via the hasItem method and pass it the item name which will return a boolean indicating whether the item is owned by the user.

ptm.hasItem("javascript badge"); // true if the item is owned by the user

You can charge the user without buying an item by using the chargeUser method and pass the amount the should be added to the user's balance. For example, every ten minutes the user is on the website he earns 100 points.

ptm.chargeUser(100); // positive amount -> adding to user's balance

For displaying the user's balance you can use the balance read-only property.

ptm.balance; // returns the user's balance

Available Methods And Properties

Methods

nameparameterreturn valuedescription
hasItemitemNamebooleanReturns a boolean indicating whether user has the specified item
buyItemitemNamethisAdds the item (if existing) to the user's items if the user has enough balance
getItemitemNameItemReturns the data for a specified item from the item list
chargeUseramountthisCharges the user with the given amount. Negative values will be subtracted, positive added
sellItemitemNamethisRemoves the item from the user's items if the user previously bought the item

Properties

namereadablewriteabletypedescription
balance x numberCurrent user's balance
userItems x Items[]The items owned by the user
items x x Items[]All available items
user x User
VERSION x VERSIONThe installed version
options x OptionsUpdates the options
callback x function(user, items)Updates the callback called when user gets updated

Customization

The PTM class provides a couple of options to customize the behavior. If you want to change the default options pass an object containing the changed options as the second parameter to the class constructor.

Available options

option keydefaulttypedescription
startBalance100numberThe start balance with which each new user starts
storagelocalStorageStorageThe storage where the user data gets saved persistently
storagePrefixptm-stringThe prefix for all data saved in the storage
logLevel2LogLevelIndicating which types of events get logged
namePTMstringThe name visible in the logs
currencyNameptstringThe currency appended to the item price in the logs
removeUnavailableItemsfalsebooleanWhether to remove items from the user if they are not present in the available items list
removeInvalidItemstruebooleanWhether to remove items from the user if they are not longer valid caused by validFrom or validUntil
loggingToconsoleLoggerThe logger used to log events
itemIdentifierFieldidstringThe field on the item object which is used to identify the item
savesaveFunctionSaveFunctionThe function used to save the user
loadloadFunctionLoadFunctionThe function used to load the user

Refreshing the data

For the ease of refreshing data after a interaction with the PTM, you can pass a callback function as the third parameter to the constructor of the PTM Class, which will be called everytime the user changes.
The callback will be called with the user information as the first parameter, all the available items as the second parameter and the PTM instance as the third parameter.

Types

Type definitions for clarity about the types used in the documentation. The described fields are mandatory until stated otherwise, however any additional fields won't affect the PTM.

Item

fieldoptionaltypedescription
idanyItem id used to identifiy the item if option.itemIdentifierField wasn't changed
namestringName of the item
pricenumberNegative amount if user has to pay, positive if the user gets points
validFrom x Date as ISO StringThe date and time from which the item can be bought
validUntil x Date as ISO StringThe date and time until which the item can be purchased

Storage

Every storage object implementing the following methods can be used to store the data persistently (e.g. localStorage)

fieldtypedescription
setItemfunction(key, value)A function taking a key and a value as parameters and saves the value referenced by the key
getItemfunction(key)A function taking a key and returning the value saved with it

LogLevel

A number indicating which type of events get logged.

levelevents
0nothing
>= 1errors
>= 2warnings
>= 3infos
>= 4logs

User

fieldtypedescription
balancenumberThe current balance of the user
ownedItemsitem[]All the items which the user owns

Logger

Every logger implementing the following methods can be used to log the events

fieldtypedescription
logfunction(...args)A function accepting a undefined number of arguments as input and logs them as a log entry
infofunction(...args)A function accepting a undefined number of arguments as input and logs them as a info entry
warnfunction(...args)A function accepting a undefined number of arguments as input and logs them as a warning entry
errorfunction(...args)A function accepting a undefined number of arguments as input and logs them as a error entry

SaveFunction

The save function's this value is binded to the ptm instance. The only parameter passed to the save function is the user that should be saved.

LoadFunction

The load function's this value is binded to the ptm instance. The load function has to return the user object as defined in the User type and may not return a promise.

2.4.0-beta.1

2 years ago

2.4.0-beta

2 years ago

2.3.0

2 years ago

2.3.0-beta.1

2 years ago

2.4.0

2 years ago

2.3.1

2 years ago

2.3.0-beta

2 years ago

2.3.0-beta.2

2 years ago

2.2.1

2 years ago

2.2.0

2 years ago

2.1.0

2 years ago

2.0.0

2 years ago

2.0.0-beta.1

2 years ago

2.0.0-beta

2 years ago