## tl;dr
**modern (module):**
```Bash
pnpm add birthdaypicker
```
```html
```
```js
import BirthdayPicker from 'birthdaypicker';
const options {}; // options (see below)
const bp = new BirthdayPicker('#my-div', options);
```
**classic:**
complete example:
```html
demo
```
## About The Project
I needed a birthday input field that is easy to use and without JS dependencies. "Simple" in this context means: with as few clicks as possible to the result!
### Features
* Coded in vanilla JS.
* Internationalization (i18n)
* change the language on the fly
* BirthdayPicker is dependency-free ;)
**[BirthdayPicker Demo >>](https://lemon3.github.io/birthdaypicker/)**
## Usage
### First Steps
#### module js approach
use pnpm / npm / yarn to install the package
```Bash
pnpm add birthdaypicker
```
or:
```Bash
npm install birthdaypicker
```
or:
```Bash
yarn add birthdaypicker
```
and then us it with
```html
```
```js
import BirthdayPicker from 'birthdaypicker';
const options = {}
const bp = new BirthdayPicker('#my-div', options);
```
#### classic js approach
if you use the classic js approach by loading scripts in html code, just download and integrate the **birthdaypicker.umd.js** script in your code:
```html
```
### Examples via data API
#### html:
```html
```
**Don't forget to call the init function if using the data API**.
```html
```
### Example via data API (select boxes in DOM)
Select-boxes boxes must be inside the main container (where the **data-birthdaypicker** attribute is defined)!
If the data attributes are set to the select-boxes, the plugin knows which box should be used for what.
Correct syntax for the data attributes (select element):
- year: data-birthdaypicker-year
- month: data-birthdaypicker-month
- day: data-birthdaypicker-day
This scenario (select-boxes in DOM) works best with [tailwindcss](https://tailwindcss.com/), as the select-boxes can be styled with classes here.
| :memo: INFO |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| If select-boxes already exist in the DOM you cannot use the **arrange** option, eg.: { arrange: 'dmy' }, as this plugin doesn't rearrange existing Elements |
#### 1) with special data attribute on the select boxes
html
```html
```
... or use with specified selectors (these selectors take precedence over the data attribute values like **data-birthdaypicker-year**)
#### 2) with id's
html
```html
```
#### 2) with just 'blank' select boxes
html
```html
```
**Don't forget to call the init function if using the data API**.
```html
```
### Example via js
#### js Example #1
just a div, js does the "magic"!
```html
```
#### js Example #2
html file with defined select boxes.
Reference these in the options object.
```html
## API
### initialize
```js
// element: a dom reference to one element, or a querySelector string
const element = '#my-div';
// an options-object, see below
const options = {};
const myBirthdayPicker = new BirthdayPicker(element, options);
```
### API / options
```js
options = {
// sets the minimal age for a person, animal,...
// if set > 0 it changes the maximal selectable year by it's value
// e.g.: maxYear: 2022, minAge: 10 -> max selectable year: 2012!
// default: 0
// example: 10
minAge: 0,
// sets the maximal age for a person, animal,...
// min selectable year is 1922 if maxYear is 2022 (2022 - 100)
// default: 100,
maxAge: 100,
// sets the minimal year (overrides maxAge)
// default: null
// example: 1980
minYear: null,
// sets the maximal year
// default: '(new Date()).getFullYear()'
// example: 2040 | 'now'
maxYear: 'now',
// coming soon
lowerLimit: null,
// coming soon
upperLimit: null,
// sets the month format for the select box
// available: 'short', 'long', 'numeric'
// default: 'short'
monthFormat: 'short',
// shows a placeholder for each select box
// available: true | false
// default: true
placeholder: true,
// if set, name will be added to each select box
// and [name]-year [name]-month [name]-day (will be added too)
// where name is the className chosen.
// e.g.: 'my-class' results in:
//
className: null,
// sets the selected start date
// available: 'now' | new Date() | '2020-10-12' (YYYY-MM-DD)
// default: null
// example: '2012-12-04'
defaultDate: null,
// if the init method should be called on creating an instance:
// const myBp = new BirthdayPicker(el, {})
// if set to false, you have to call myBp.init() afterwards.
// available: true | false
// default: true
autoInit: true,
// if the month and day values in the select-box should have a leading
// zero or not. If set to true, you will get: 01, 02, 03, ... 10, 11, ...
// if set to false, you will get: 1, 2, 3, ... 10, 11, ...
// available: true | false
// default: true
leadingZero: true,
// sets the language to be used
// available: 'en', 'de', 'fr', ... all country codes with 2chars (ISO 3166-1 alpha-2)
// default: 'en'
locale: 'en',
// if it should be possible to select a 'future' date
// false means: unable to select a date in the future
// available: true | false
// default: false
selectFuture: false,
// to arrange the select-boxes
// y: year, m: month, d: day
// so ymd means: year | month | day
// ordering is only available, if select boxes are not present in the DOM
// available: 'ymd', 'ydm', 'myd', 'mdy', 'dmy', 'dym'
// default: 'ymd'
arrange: 'ymd',
// specify a custom select-box for the year
// must be inside the main element
// all valid query-strings allowed
// available: null, valid query-strings (querySelector), or html reference
// default: null
// example: '#my-year-select'
yearEl: null,
// specify a custom select-box for the month
// must be inside the main element
// all valid query-strings allowed
// available: null, valid query-strings (querySelector), or html reference
// default: null
// example: '#my-month-select'
monthEl: null,
// specify a custom select-box for the day
// must be inside the main element
// all valid query-strings allowed
// available: null, valid query-strings (querySelector), or html reference
// default: null
// example: '#my-day-select'
dayEl: null,
// sets days to highest possible value, if the month (or in special cases
// the year) is changed and the current selected day-value is higher than
// the possible value for the new month (year).
// true: rounds down
// false: returns undefined for the day (so nothing is selected)
// available: true | false
// default: true
//
// Example:
// Current date is 2024-02-29 (yyyy-mm-dd)
// set year back to 2023
// if roundDownDay is true: day will be: 28
// if roundDownDay is false: day will be: undefined
roundDownDay: true
};
```
### API / methods
```js
const element = '#my-div';
const options = {
autoInit: false
};
const myBirthdayPicker = new BirthdayPicker(element, options);
// init: initializes the picker
myBirthdayPicker.init();
// getDate returns the current selected date with the language default date-formatting!
// you can change the format, by calling the method with a specific date-format value.
// e.g.: 'yyyy-m-d'
// if date is 2. Sep. 1994
// return values are:
// 'yy' -> 94
// 'yyyy' -> 1994
// 'mm' -> 09
// 'm' -> 9
// 'dd' -> 02
// 'd' -> 2
myBirthdayPicker.getDateString('yyyy-m-d');
// returns a Date object (like new Date())
// for the current year, month, day values
myBirthdayPicker.getDate();
// returns the age of the subject (person)
myBirthdayPicker.getAge();
// just a small helper method, returns true or false
myBirthdayPicker.isLeapYear(2020); // true
// listen to different events eg.
// available events: init | datechange
const myEventListener = () => {};
myBirthdayPicker.addEventListener('datechange', myEventListener, false);
// remove the event listener
myBirthdayPicker.removeEventListener('datechange', myEventListener);
// set the date to a given value
// e.g.: '2020-10-22' // yyyy-mm-dd: this is the 22. oct. 2020
// or to the current date with new Date()
myBirthdayPicker.setDate(new Date());
// resets the date
// true: resets to the defaultDate (start date);
// false: all select boxes will be reset to default value (if available)
myBirthdayPicker.resetDate(true);
// sets the language for the current instance
// e.g.: 'en', 'de', 'fr', ...
myBirthdayPicker.setLanguage('en');
// sets the month format for the current instance
// available: 'short', 'long', 'numeric'
myBirthdayPicker.setMonthFormat('short');
// setter, if the
myBirthdayPicker.useLeadingZero(true); // true | false
// kills the current instance and removes all event-listeners
myBirthdayPicker.kill();
```
### API / event-listeners
```js
const element = document.querySelector('#my-element');
const options = {};
const myPicker = new BirthdayPicker(element, options);
// available event listeners
const available = [
'init', // triggered after init
'kill', // triggered when the kill was called
'daychange', // triggered when the day value was changed
'monthchange', // triggered when the month value was changed
'yearchange', // triggered when the year value was changed
'datechange', // triggered when day, month or year value was changed
]
// use the instance as event listener
myPicker.addEventListener('datechange', (evt) => {
// todo something ...
});
// or the element itself
element.addEventListener('datechange', (evt) => {
// todo something ...
});
```
### API / event-listeners (as callback)
inside the option object
```js
const options = {
// ...
datechange: (evt) => { /* do stuff */ },
monthchange: (evt) => { /* do stuff */ },
// ...
};
const myPicker = new BirthdayPicker('#my-element', options);
```
#### example using all event-listener possibilities
see the event sequence!
```js
import BirthdayPicker from 'birthdaypicker';
const options = {
datechange: (evt) => {
console.log('i am: 1st');
},
};
const pickerEl = document.getElementById('my-element');
const picker = new BirthdayPicker(pickerEl, options);
// on instance
picker.addEventListener('datechange', (evt) => {
console.log('i am: 2nd');
});
// on DOM element
pickerEl.addEventListener('datechange', (evt) => {
console.log('i am: 3rd');
});
```
### API / static Methods
#### createLocale()
```js
// used to create a locale object for the selected language
// parameter: (string, required)
// eg.: 'de' | 'en' | 'fr'
// returns an object for the given language (if language not found defaults to english 'en')
// is added to BirthdayPicker.i18n
BirthdayPicker.createLocale('de')
```
#### getInstance()
```js
// returns the instance
// (if the element has previously been initialized with new BirthdayPicker('#myBP')
// returns either the instance ore false
htmlElement = document.getElementById('#myBP');
BirthdayPicker.getInstance(htmlElement)
```
#### setMonthFormat()
```js
// sets the MonthFormat (select boxes) for all instances
// format: 'short' | 'long' | 'numeric'
BirthdayPicker.setMonthFormat('short')
```
#### kill()
```js
// kill all eventListeners
htmlElement = document.getElementById('#myBP');
BirthdayPicker.kill(htmlElement)
```
#### killAll()
```js
// kill all registered instances
BirthdayPicker.killAll()
```
### API / static Properties
```js
// an object with all languages cerated
BirthdayPicker.i18n
// shows the current global language as string (2 chars, e.g.: 'en' | 'de')
BirthdayPicker.currentLocale
```
### Demo
A **small demo** of this tool can be view here: [BirthdayPicker Demo](https://lemon3.github.io/birthdaypicker/)
## Getting Started
### Prerequisites
you need to have **node** and **pnpm**.
skip to prerequisites if you already have this installed ;)
1. Install node
1. download [download here](https://nodejs.org/en/download/)
2. via brew
```Bash
brew install node
```
2. Install pnpm:
see here: https://pnpm.io/installation
### Installation
1. Clone the repo
```Bash
git clone https://github.com/lemon3/birthdaypicker.git
```
2. cd into the cloned repo
```Bash
cd birthdaypicker
```
3. Install packages
```Bash
pnpm install
```
4. start (dev)
```Bash
pnpm dev
```
To see all available scripts, open the **package.json** file or run
```Bash
pnpm run
```
