87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
# numberFormat.js
|
|
A simple JS library that automatically formats numbers on your web page.
|
|
This is accomplished using the Intl.NumberFormat library to format the
|
|
numbers, and some custom elements to locate the numbers that need
|
|
formatting and allow them to be replaced by the correct value.
|
|
Designed mainly for use on static websites to avoid the bother of
|
|
formatting numbers manually.
|
|
|
|
## A more succinct description
|
|
This library allows DOM modification based on the Intl.NumberFormat library
|
|
which is part of JS. Providing a custom element that allows you to
|
|
specify number formatting declaratively and without needing to know how to
|
|
format numbers.
|
|
|
|
## Basic Usage
|
|
- Host the script somewhere on your system.
|
|
- Ensure you set the language for your HTML element
|
|
- Add a script tag to your document head that has the `src` set to this script.\
|
|
The script tag must also be set to defer
|
|
- Surround any numbers you want formatting with `<num>` tags.\
|
|
These 'custom' tags are used so the script can efficiently find numbers
|
|
without needing to resort to jQuery or regex.\
|
|
This also allows you to specify numbers you don't want formatted.
|
|
|
|
## Formatting Currencies
|
|
To format a currency you need to add the `currency` attribute to your num
|
|
element with the value set in the format `CURRENCY-FORMAT`.
|
|
With currency being the three letter code for the currency.
|
|
And format being one of:
|
|
- symbol
|
|
- narrowSymbol
|
|
- code
|
|
- name
|
|
This is exactly parallel to the Intl.NumberFormat constructor for
|
|
formatting currencies.
|
|
|
|
### Example
|
|
```html
|
|
<html lang="YOUR-LANGUAGE">
|
|
<head>
|
|
<title>test</title>
|
|
<script defer src="https://{YOUR_DOMAIN}/somewhere/numberFormat.js"></script>
|
|
</head>
|
|
<body>
|
|
<p>This is a formatted number <num>1234567890</num></p>
|
|
<p>This is a simple formatted currency <num currency=GBP>123</num></p>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
## Design goals
|
|
- Code simplicity
|
|
- Easily extendable
|
|
- Using only native JS
|
|
|
|
## Design non-goals
|
|
- Locale detection\
|
|
This is not useful since web pages should be consistent.\
|
|
Locale detection would break this.
|
|
- Date formatting\
|
|
This should be an entirely different package.\
|
|
It is a completely different task.
|
|
|
|
## TODO:
|
|
- Check for optimisations
|
|
- If this becomes popular host to a CDN
|
|
- Change custom element\
|
|
Technically the WHATWG specifies that custom elements should be in
|
|
kebab case.
|
|
|
|
## MightDO:
|
|
- Allow for setting locale for individual numbers.
|
|
- Automate releases that include a minified version\
|
|
I personally don't care for minified JS but some people love it\
|
|
This is an extremely low-priority task.
|
|
|
|
## Changelog
|
|
- 2022-10-08\
|
|
Get language from DOM
|
|
Robert Morrison \<sherlock5512\>
|
|
- 2022-10-07{2}\
|
|
Add Logo\
|
|
Robert Morrison \<sherlock5512\>
|
|
- 2022-10-07\
|
|
Initial Upload of basic script\
|
|
Robert Morrison \<sherlock5512\>
|