-
-
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/addons.gts b/docs/app/templates/public-pages/addons.gts
new file mode 100644
index 00000000..991f5174
--- /dev/null
+++ b/docs/app/templates/public-pages/addons.gts
@@ -0,0 +1,7 @@
+
+
+
+ {{outlet}}
+
+
+
diff --git a/docs/app/templates/public-pages/addons.hbs b/docs/app/templates/public-pages/addons.hbs
deleted file mode 100644
index cc2edaa5..00000000
--- a/docs/app/templates/public-pages/addons.hbs
+++ /dev/null
@@ -1,5 +0,0 @@
-
-
- {{outlet}}
-
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/addons/index.gts b/docs/app/templates/public-pages/addons/index.gts
new file mode 100644
index 00000000..70897ea0
--- /dev/null
+++ b/docs/app/templates/public-pages/addons/index.gts
@@ -0,0 +1,44 @@
+
+
Addons
+
+
+ Ember Power Calendar is designed to allow users to customize it to fit their
+ needs, and hopefully that work could be also released to the public to others
+ use it.
+
+
+
+ If you develop an addon that builds on top of Ember Power Calendar, there are
+ three things you should do:
+
+
+
+
+ Remember to list it as a dependency, not a devDependency in your addon's
+ package.json. Otherwise, apps will not be able to find any of the
+ components.
+
+
+ Add
+ "ember-power-calendar-addon"
+ to the keywords section of your
+ package.json
+ so I can scan the npm registry and find them.
+
+
Let me know about it!
+
+
+
+ In case you want inspiration, this are some ideas that could be cool:
+
+
+
+
A datepicker with a nice API based on contextual components
+
A calendar-subcomponent that displays weeks instead of months
- Ember Power Calendar is designed to allow users to customize it to fit their
- needs, and hopefully that work could be also released to the public to others
- use it.
-
-
-
- If you develop an addon that builds on top of Ember Power Calendar, there are
- three things you should do:
-
-
-
-
- Remember to list it as a `dependency`, not a `devDependency` in your addon's
- `package.json`. Otherwise, apps will not be able to find any of the
- components.
-
-
- Add
- "ember-power-calendar-addon"
- to the keywords section of your
- package.json
- so I can scan the npm registry and find them.
-
-
Let me know about it!
-
-
-
- In case you want inspiration, this are some ideas that could be cool:
-
-
-
-
A datepicker with a nice API based on contextual components
-
A calendar-subcomponent that displays weeks instead of months
- One very common use case of calendars is as part of another datepicker
- component. That is, a calendar associated with an input field, in which when
- the input is clicked, the calendar appears in a floating box to ease choosing
- a date.
-
-
-
- It might seem that this would take a lot of code, but the Ember ecosystem is
- amazing, and there are already some components that act as building blocks for
- other components that we can leverage.
-
-
-
- One of them is
- Ember Basic
- Dropdown. It does only one thing, but it does it well: Display a
- floating box next to another element when that element is clicked.
-
-
-
Let's build a naive datepicker in 20 lines of code!
- We've just
- composed
- two battle-tested community addons into an entirely new component without a
- single line of Javascript! How cool is that?
-
-
-
- You can style it in any way you want, add wrapper divs like the ones required
- by some CSS frameworks (I'm looking at you, Bootstrap), format the text of the
- input using some helper. You could also modify it to use a textarea or to
- format ranges in a breeze.
-
-
-
- Admittedly, there is some room for refinement.
-
-
- For example, you could want to close the dropdown when a day is selected or
- allow the users to type on the input and parse the date as they type, but this
- gives a starting point for anyone to create - and publish ;) - their own
- datepicker component.
-
-
-
- < System-wide config
- Nav with select >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/cookbook/index.gts b/docs/app/templates/public-pages/cookbook/index.gts
new file mode 100644
index 00000000..adab6e78
--- /dev/null
+++ b/docs/app/templates/public-pages/cookbook/index.gts
@@ -0,0 +1,64 @@
+import CodeExample from 'docs/components/code-example';
+import Datepicker1 from '../../../components/snippets/datepicker-1';
+import { LinkTo } from '@ember/routing';
+
+
+
Datepicker
+
+
+ One very common use case of calendars is as part of another datepicker
+ component. That is, a calendar associated with an input field, in which when
+ the input is clicked, the calendar appears in a floating box to ease choosing
+ a date.
+
+
+
+ It might seem that this would take a lot of code, but the Ember ecosystem is
+ amazing, and there are already some components that act as building blocks for
+ other components that we can leverage.
+
+
+
+ One of them is
+ Ember Basic
+ Dropdown. It does only one thing, but it does it well: Display a
+ floating box next to another element when that element is clicked.
+
+
+
Let's build a naive datepicker in 20 lines of code!
+
+
+ {{Datepicker1}}
+
+
+
+ We've just
+ composed
+ two battle-tested community addons into an entirely new component without a
+ single line of Javascript! How cool is that?
+
+
+
+ You can style it in any way you want, add wrapper divs like the ones required
+ by some CSS frameworks (I'm looking at you, Bootstrap), format the text of the
+ input using some helper. You could also modify it to use a textarea or to
+ format ranges in a breeze.
+
+
+
+ Admittedly, there is some room for refinement.
+
+
+ For example, you could want to close the dropdown when a day is selected or
+ allow the users to type on the input and parse the date as they type, but this
+ gives a starting point for anyone to create - and publish ;) - their own
+ datepicker component.
+
- There is a fair amount of option on this component that allow to configure how
- it looks and how it behaves, if you want all the calendars of your app to
- always behave the same, it can be tiring to pass the same options over and
- over.
-
-
-
- Is there a way of changing the defaults of the component(s) in a way that you
- don't have to pass the same options everywhere?
-
-
-
- Yes, and it's simpler than you think.
-
-
-
- Inside your app's
- /app/components/
- folder create a
- power-calendar.js
- file that exports a component inherits from the one provided by the addon, and
- define on it the values you want them to be the new defaults.
-
-
-
- By example, if you develop a nicer
- <calendar.Nav/>
- component that you want to user in every calendars, you could do this:
-
-
-
-
-
- That's all. No new concepts to learn, just your usual ember-cli work flow.
-
-
-
- In this example the component is also named
- <PowerCalendar />
- but if you want the default component to still be available, just define it in
- a file with a different name.
-
-
-
- Datepicker >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/cookbook/multiple-months.gts b/docs/app/templates/public-pages/cookbook/multiple-months.gts
new file mode 100644
index 00000000..0a60b074
--- /dev/null
+++ b/docs/app/templates/public-pages/cookbook/multiple-months.gts
@@ -0,0 +1,64 @@
+import CodeExample from 'docs/components/code-example';
+import MultipleMonths1 from '../../../components/snippets/multiple-months-1';
+import MultipleMonths2 from '../../../components/snippets/multiple-months-2';
+import { LinkTo } from '@ember/routing';
+
+
+
Display Multiple Months
+
+
+ You might want to display multiple months simultaneously. Displaying multiple
+ months is a nice especially when you might want people to select dates across
+ month boundaries.
+
+
+
+ We are in luck! Versions of Ember Power Calendar greater than 0.11.0 can
+ support this with a few little twix.
+
+
+
+ {{MultipleMonths1}}
+
+
+
+ How? Well. In versions of ember-power-calendar greater than 0.11.0 we can pass
+ a
+ center
+ property to the
+ calendar.Days
+ component. This center property must be a valid date. As long as you use the
+ ember-power-calendar-range
+ component, months will render with the correct center and everything still
+ works! If you want the months to be changeable you will need to wire that up
+ yourself similar to how we demonstate above. You might need to bust out some
+ fancy styling, but we are web developers... are we not?
+
+
+
+ Another nice pattern for mobile is to render all 12 months vertically and let
+ the user scroll them.
+
+
+
+ {{MultipleMonths2}}
+
+
+
+ In this example, we create an array of all the month centers and loop over
+ them. A little dash of CSS to align them correct. Easy peasy lemon-squeezy.
+
- You might want to display multiple months simultaneously. Displaying multiple
- months is a nice especially when you might want people to select dates across
- month boundaries.
-
-
-
- We are in luck! Versions of Ember Power Calendar greater than 0.11.0 can
- support this with a few little twix.
-
- How? Well. In versions of ember-power-calendar greater than 0.11.0 we can pass
- a
- center
- property to the
- calendar.Days
- component. This center property must be a valid date. As long as you use the
- ember-power-calendar-range
- component, months will render with the correct center and everything still
- works! If you want the months to be changeable you will need to wire that up
- yourself similar to how we demonstate above. You might need to bust out some
- fancy styling, but we are web developers... are we not?
-
-
-
- Another nice pattern for mobile is to render all 12 months vertically and let
- the user scroll them.
-
- In this example, we create an array of all the month centers and loop over
- them. A little dash of CSS to align them correct. Easy peasy lemon-squeezy.
-
-
-
- < Nav with select
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/cookbook/nav-select.gts b/docs/app/templates/public-pages/cookbook/nav-select.gts
new file mode 100644
index 00000000..1c6b372e
--- /dev/null
+++ b/docs/app/templates/public-pages/cookbook/nav-select.gts
@@ -0,0 +1,98 @@
+import CodeExample from 'docs/components/code-example';
+import NavSelect1 from '../../../components/snippets/nav-select-1';
+import NavSelect2 from '../../../components/snippets/nav-select-2';
+import NavSelect3 from '../../../components/snippets/nav-select-3';
+import { LinkTo } from '@ember/routing';
+
+
+
Nav with select
+
+
+ A couple people asked me if I was considering adding a feature present in the
+ well known
+ Pickaday
+ library where you can click in the month or year to quicky navigate to far
+ away dates.
+
+
+
+ The answer I gave was that I wasn't considering it, but not because I don't
+ think it is a good pattern, but because the flexible nature of Ember Power
+ Calendar makes it unnecesary!
+
+
+
+ Let's build it in a few lines of code.
+
+
+
+ {{NavSelect1}}
+
+
+
+ Ok, let's disect what is going on here.
+
+
+
+ We pass a block to the
+ calendar.Nav
+ component to replace the default markup with the name of the component with
+ our own markup. In that markup we add two invisible select on top of the text
+ of the month and year that when interacted call an action that builds a new
+ date and pass it to
+ calendar.actions.changeCenter
+ public action to center the calendar on that action.
+
+
+
+ The markup itself is a bit verbose because we're coding a select outselves,
+ but the logic is easy to follow.
+
+
+
+ Ember Power Calendar prefers to let users enhance the calendar themselves
+ instead of attempting to imagine all the possible scenarios.
+
+
+
+ What if you prefer to use Ember Power Select with the years grouped by decade
+ and some fancy animations instead of a native select?
+
+
+
+ {{NavSelect2}}
+
+
+
+ Or maybe an
+ <input type="number">
+ for the year only?
+
+
+
+ {{NavSelect3}}
+
+
+
+ Since you can replace any part of the component by your own code and
+ templates, there is no limits in what you can do.
+
+
+
+ Go ahead, build something cool and publish it!
+
- A couple people asked me if I was considering adding a feature present in the
- well known
- Pickaday
- library where you can click in the month or year to quicky navigate to far
- away dates.
-
-
-
- The answer I gave was that I wasn't considering it, but not because I don't
- think it is a good pattern, but because the flexible nature of Ember Power
- Calendar makes it unnecesary!
-
- We pass a block to the
- calendar.Nav
- component to replace the default markup with the name of the component with
- our own markup. In that markup we add two invisible select on top of the text
- of the month and year that when interacted call an action that builds a new
- date and pass it to
- calendar.actions.changeCenter
- public action to center the calendar on that action.
-
-
-
- The markup itself is a bit verbose because we're coding a select outselves,
- but the logic is easy to follow.
-
-
-
- Ember Power Calendar prefers to let users enhance the calendar themselves
- instead of attempting to imagine all the possible scenarios.
-
-
-
- What if you prefer to use Ember Power Select with the years grouped by decade
- and some fancy animations instead of a native select?
-
+ Ember Power Calendar aims to be very customizable and because of that it also
+ has to be very explicit about its behaviour, even if that makes it slightly
+ verbose.
+
+
+
+ The data flow from the app to the addon is strictly unidirectional. Data comes
+ into the component, and actions are fired from the inside. The user must
+ handle those actions in order for
+ anything
+ to happen.
+
+
+
Let's start with the basics, adding month navigation.
+
+
onCenterChange
+
+
+ In the previous section we mentioned that if you pass
+ center=someDate
+ to the component, that month is displayed. If that option gets updates the
+ calendar will render the new month. That means that you can create your own
+ interface to navigate months, it only has to update the
+ center
+ property.
+
+
+
+ However, it would be inconvenient to force everyone to do that, so if you pass
+ onCenterChange
+ action to the component, the
+ calendar.Nav
+ component gets some built-in controls to navigate to the previous and next
+ month. Use that action to update the displayed month and you have a navigable
+ calendar!
+
+
+
+ {{ActionHandling1}}
+
+
+
+ Making this interaction so explicit might seem verbose. It does force you to
+ type a few characters for the simplest use case, but in exchange makes some
+ usages that are usually very hard to implement extremely simple.
+
+
+
+ For example, imagine that changing to a different month needs to make an ajax
+ call to the server to gather all the events that are going to happen that
+ month (we haven't seen how to display events on the calendar, but use your
+ imagination) before showing the next month. While those events are loaded, we
+ want to hold changing the month and show a loading state with an animated
+ spinner.
+
+
+
It doesn't seem like the kind of thing you'd dare to attempt with
+ bootstrap-datepicker, right?
+
+
+ {{ActionHandling2}}
+
+
+
+ While the calendar is performing a task, its yielded public API has the
+ loading
+ flag enabled, and since you can interleave the subcomponents in your own
+ markup, you use that flag to create an overlay.
+
+
+
+ No black magic. Just the way you usually manage sync actions in your own code.
+ Ember Power Calendar is promise-aware and task-aware, all the way down.
+
+
+
onSelect
+
+
+ One very common use case of a calendar is to select one (or many) days. For
+ that purpose it exposes an
+ onSelect
+ action that is called when the user clicks (or presses Enter over) a day.
+
+
+
+ That action is fired with a
+ day
+ object as first argument. This object built by Ember Power Calendar contains
+ many useful information that we will explore in detail, but for now we'll hold
+ to the idea that it has a
+ date
+ property that contains a native
+ Date
+ object and a
+ moment
+ property that contains the same value but wrapped by
+ MomentJS, so you can use the one you prefer.
+
+
+
+ Like with the previous action, it's your responsibility to react to this
+ action, but in the most typical case you just want to update the
+ selected
+ value. Let's see how to do it, and we are going to use the plain
+ Date
+ version of the date.
+
+
+
Go, click one day.
+
+
+ {{ActionHandling3}}
+
+
+
+ You will notice a couple more things happening here.
+
+
+
+ To begin with, the days of the calendar highlight when you hover them. This is
+ because the presence of an
+ onSelect
+ action makes the component enter an interactive mode, which adds a class to
+ it.
+
+
+
+ Also, if you inspect the html, you'll see that the days are now
+ <button>s instead of
+ <div>s. This, besides of making them clickable to select a
+ day, makes them focusable, which is important to make the component
+ accessible. The currently focused day is shown with a blue underline, and once
+ one day is focused you can use the arrows,
+ TAB,
+ ENTER
+ and
+ SPACE
+ keys to move around and interact with the component.
+
+
+
+ This action is fired when the selection changes, but the selection doesn't
+ need to be a single date. It can be a range or a set of sparse dates! The next
+ page is all about this topic.
+
- Ember Power Calendar aims to be very customizable and because of that it also
- has to be very explicit about its behaviour, even if that makes it slightly
- verbose.
-
-
-
- The data flow from the app to the addon is strictly unidirectional. Data comes
- into the component, and actions are fired from the inside. The user must
- handle those actions in order for
- anything
- to happen.
-
-
-
Let's start with the basics, adding month navigation.
-
-
onCenterChange
-
-
- In the previous section we mentioned that if you pass
- center=someDate
- to the component, that month is displayed. If that option gets updates the
- calendar will render the new month. That means that you can create your own
- interface to navigate months, it only has to update the
- center
- property.
-
-
-
- However, it would be inconvenient to force everyone to do that, so if you pass
- onCenterChange
- action to the component, the
- calendar.Nav
- component gets some built-in controls to navigate to the previous and next
- month. Use that action to update the displayed month and you have a navigable
- calendar!
-
- Making this interaction so explicit might seem verbose. It does force you to
- type a few characters for the simplest use case, but in exchange makes some
- usages that are usually very hard to implement extremely simple.
-
-
-
- For example, imagine that changing to a different month needs to make an ajax
- call to the server to gather all the events that are going to happen that
- month (we haven't seen how to display events on the calendar, but use your
- imagination) before showing the next month. While those events are loaded, we
- want to hold changing the month and show a loading state with an animated
- spinner.
-
-
-
It doesn't seem like the kind of thing you'd dare to attempt with
- bootstrap-datepicker, right?
- While the calendar is performing a task, its yielded public API has the
- loading
- flag enabled, and since you can interleave the subcomponents in your own
- markup, you use that flag to create an overlay.
-
-
-
- No black magic. Just the way you usually manage sync actions in your own code.
- Ember Power Calendar is promise-aware and task-aware, all the way down.
-
-
-
onSelect
-
-
- One very common use case of a calendar is to select one (or many) days. For
- that purpose it exposes an
- onSelect
- action that is called when the user clicks (or presses Enter over) a day.
-
-
-
- That action is fired with a
- day
- object as first argument. This object built by Ember Power Calendar contains
- many useful information that we will explore in detail, but for now we'll hold
- to the idea that it has a
- date
- property that contains a native
- Date
- object and a
- moment
- property that contains the same value but wrapped by
- MomentJS, so you can use the one you prefer.
-
-
-
- Like with the previous action, it's your responsibility to react to this
- action, but in the most typical case you just want to update the
- selected
- value. Let's see how to do it, and we are going to use the plain
- Date
- version of the date.
-
- You will notice a couple more things happening here.
-
-
-
- To begin with, the days of the calendar highlight when you hover them. This is
- because the presence of an
- onSelect
- action makes the component enter an interactive mode, which adds a class to
- it.
-
-
-
- Also, if you inspect the html, you'll see that the days are now
- <button>s instead of
- <div>s. This, besides of making them clickable to select a
- day, makes them focusable, which is important to make the component
- accessible. The currently focused day is shown with a blue underline, and once
- one day is focused you can use the arrows,
- TAB,
- ENTER
- and
- SPACE
- keys to move around and interact with the component.
-
-
-
- This action is fired when the selection changes, but the selection doesn't
- need to be a single date. It can be a range or a set of sparse dates! The next
- page is all about this topic.
-
-
-
- < How to use it
- Date ranges >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/api-reference.gts b/docs/app/templates/public-pages/docs/api-reference.gts
new file mode 100644
index 00000000..4d0f70af
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/api-reference.gts
@@ -0,0 +1,117 @@
+
+
API Reference
+
+
+ Ember Power Calendar aims to allow users to create the ideal calendar they
+ need using only the properties and actions defined in its public API, so it is
+ important to have a comprehensive list of all the available options.
+
+
+
The day object
+
+
+ The day object is an object received by many actions, blocks and components
+ and one of the interfaces you will use more often.
+
+
+
+
+
+
Option
+
Type
+
Description
+
+
+
+
+
id
+
String
+
A unique identified of the day. It has the format
+ YYYY-MM-DD
+
+
+
number
+
Number
+
The day's number. From 1 to 31
+
+
+
date
+
Date
+
The native Date object representing that day.
+
+
+
moment
+
MomentJS
+
The
+ moment
+ representing that day. (only when
+ ember-power-calendar-moment
+ is installed)
+
+
+
datetime
+
DateTime
+
The Luxon's
+ DateTime
+ instance representing that day. (only when
+ ember-power-calendar-luxon
+ is installed)
+
+
+
isFocused
+
Boolean
+
It is true when the the cell of that day has the focus
+
+
+
isCurrentMonth
+
Boolean
+
It is true for those days in the current day, and false for those days
+ for the previous/next months shown around.
+
+
+
isToday
+
Boolean
+
It is true if this day is today
+
+
+
isSelected
+
Boolean
+
It is true if the date of this day is the selected one. In multiple
+ select it is true if the date of this day is among the selected ones. In
+ range selects, it is true if the date if this day is in the range,
+ including both ends.
+
+
+
isRangeStart
+
Boolean
+
It is true if this day is the beginning of a range. It is false in
+ non-range calendars
+
+
+
isRangeEnd
+
Boolean
+
It is true if this day is the end of a range. It is false in non-range
+ calendars
+ {
+ uniqueId: <string>, // Contains the unique of this instance of EmberPowerSelect. It's of the form "ember1234".
+ selected: <Date>, // The selected date
+ loading: <boolean>, // True when the async operation of changing the center is in progress
+ center: <Date>, // The date that acts as the center for the displayed date information
+ locale: <string> // The ISO code of the locale used to format dates in the calendar
+ type: <string> // The type of calendar. One of: "multiple" | "range" | "single"
+ actions: {
+ changeCenter(newCenter, calendar, event) { ... }, // Changes the center of the calendar (invoking "@onCenterChange")
+ moveCenter(step, unit, calendar, event) { ... }, // Moves the center of the calendar the given number of units (invoking "@onCenterChange")
+ select(day, calendar, event) { ... }, // Selects the given date (invoking "onSelect")
+ }
+ }
+
- Ember Power Calendar aims to allow users to create the ideal calendar they
- need using only the properties and actions defined in its public API, so it is
- important to have a comprehensive list of all the available options.
-
-
-
The day object
-
-
- The day object is an object received by many actions, blocks and components
- and one of the interfaces you will use more often.
-
-
-
-
-
-
Option
-
Type
-
Description
-
-
-
-
-
id
-
String
-
A unique identified of the day. It has the format
- YYYY-MM-DD
-
-
-
number
-
Number
-
The day's number. From 1 to 31
-
-
-
date
-
Date
-
The native Date object representing that day.
-
-
-
moment
-
MomentJS
-
The
- moment
- representing that day. (only when
- ember-power-calendar-moment
- is installed)
-
-
-
datetime
-
DateTime
-
The Luxon's
- DateTime
- instance representing that day. (only when
- ember-power-calendar-luxon
- is installed)
-
-
-
isFocused
-
Boolean
-
It is true when the the cell of that day has the focus
-
-
-
isCurrentMonth
-
Boolean
-
It is true for those days in the current day, and false for those days
- for the previous/next months shown around.
-
-
-
isToday
-
Boolean
-
It is true if this day is today
-
-
-
isSelected
-
Boolean
-
It is true if the date of this day is the selected one. In multiple
- select it is true if the date of this day is among the selected ones. In
- range selects, it is true if the date if this day is in the range,
- including both ends.
-
-
-
isRangeStart
-
Boolean
-
It is true if this day is the beginning of a range. It is false in
- non-range calendars
-
-
-
isRangeEnd
-
Boolean
-
It is true if this day is the end of a range. It is false in non-range
- calendars
- {
- uniqueId: <string>, // Contains the unique of this instance of EmberPowerSelect. It's of the form `ember1234`.
- selected: <Date>, // The selected date
- loading: <boolean>, // True when the async operation of changing the center is in progress
- center: <Date>, // The date that acts as the center for the displayed date information
- locale: <string> // The ISO code of the locale used to format dates in the calendar
- type: <string> // The type of calendar. One of: "multiple" | "range" | "single"
- actions: {
- changeCenter(newCenter, calendar, event) { ... }, // Changes the center of the calendar (invoking `@onCenterChange`)
- moveCenter(step, unit, calendar, event) { ... }, // Moves the center of the calendar the given number of units (invoking `@onCenterChange`)
- select(day, calendar, event) { ... }, // Selects the given date (invoking `onSelect`)
- }
- }
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/how-to-use-it.gts b/docs/app/templates/public-pages/docs/how-to-use-it.gts
new file mode 100644
index 00000000..018ed023
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/how-to-use-it.gts
@@ -0,0 +1,145 @@
+
+import CodeExample from 'docs/components/code-example';
+import HowToUseIt1 from '../../../components/snippets/how-to-use-it-1';
+import HowToUseIt2 from '../../../components/snippets/how-to-use-it-2';
+// import HowToUseIt3 from '../../../components/snippets/how-to-use-it-3';
+import HowToUseIt4 from '../../../components/snippets/how-to-use-it-4';
+import HowToUseIt5 from '../../../components/snippets/how-to-use-it-5';
+import { LinkTo } from '@ember/routing';
+
+
+
How to use it
+
+
+ This component is built with a technique known as
+ Contextual Components. If you haven't heard of it, check
+ the official guides
+ for some background.
+
+
+
+ The basic usage is pretty simple. There are no mandatory fields. Just invoke
+ the
+ power-calendar
+ component and yield the calendar to the block. Once inside the block, the
+ yielded calendar has a couple of components inside, but the one you probably
+ care most about is named
+ days.
+
+
+
+ {{HowToUseIt1}}
+
+
+
+ Nice, but not very interesting. The
+ calendar.Days
+ component renders a grid of days, and it is smart enough to display the
+ current month but that's it. Let's see how to show a different month.
+
+
+
center
+
+
+ To make the calendar render centered on a different month just pass
+ center=someDate
+ and the calendar will display the month of that date.
+
+
+ It is important to note that
+ center
+ is a date in which we center our attention but not necessarily the center of
+ the time window we display. In the month view (the default) it doesn't matter
+ if that date is the 1st day or the 31st, the rendered month will be the same.
+ Let's render October of 2013.
+
+
+
+ {{HowToUseIt2}}
+
+
+
+ The month above is November of 2013, but that's hard to know if there is
+ nothing else telling us. The second component that the calendar has and that
+ you will find yourself using often is
+ calendar.Nav. This component displays the name of the month and,
+ optionally, some actions to navigate to the previous/next month.
+
+
+
+ {{HowToUseIt2}}
+
+
+
+ Oh, and by the way, ember-power-calendar and all its sub-components can
+ receive native
+ Date, and depending on wether you installed
+ ember-power-calendar-moment
+ or
+ ember-power-calendar-luxon, also
+ moment
+ objects or Luxon's
+ DateTime
+ instances. All options that are dates can take values of any type, and all
+ actions that this component fires will contain dates in both formats too.
+
+
+
+ Most of the time however, you just want the
+ nav
+ and
+ days
+ components rendered. For this scenario, simply invoke
+ power-calendar
+ without a block, like so:
+
+
+
+ {{HowToUseIt5}}
+
+
+
selected
+
+
+ Sometimes you want a day of the month to be highlighted. To do it pass
+ selected=someDate
+ to the component.
+
+
+
+ {{HowToUseIt4}}
+
+
+
+ You can see that the calendar shows the selected date in blue. You may have
+ also noticed that despite only passing a
+ selected
+ option, the month is not the current one. That is because in the absence of a
+ specific
+ center, the calendar will show the month of the selected date. If
+ both options are provided,
+ center
+ always
+ prevails.
+
+
+
+ Enough of static calendars. If you just wanted to display a static grid of
+ days you probably wouldn't be using an ember-addon for that. You want to
+ navigate months, you want to select days and ranges. Let's see how to do these
+ things in the next chapter.
+
- This component is built with a technique known as
- Contextual Components. If you haven't heard of it, check
- the official guides
- for some background.
-
-
-
- The basic usage is pretty simple. There are no mandatory fields. Just invoke
- the
- power-calendar
- component and yield the calendar to the block. Once inside the block, the
- yielded calendar has a couple of components inside, but the one you probably
- care most about is named
- days.
-
- Nice, but not very interesting. The
- calendar.Days
- component renders a grid of days, and it is smart enough to display the
- current month but that's it. Let's see how to show a different month.
-
-
-
center
-
-
- To make the calendar render centered on a different month just pass
- center=someDate
- and the calendar will display the month of that date.
-
-
- It is important to note that
- center
- is a date in which we center our attention but not necessarily the center of
- the time window we display. In the month view (the default) it doesn't matter
- if that date is the 1st day or the 31st, the rendered month will be the same.
- Let's render October of 2013.
-
- The month above is November of 2013, but that's hard to know if there is
- nothing else telling us. The second component that the calendar has and that
- you will find yourself using often is
- calendar.Nav. This component displays the name of the month and,
- optionally, some actions to navigate to the previous/next month.
-
- Oh, and by the way, ember-power-calendar and all its sub-components can
- receive native
- Date, and depending on wether you installed
- ember-power-calendar-moment
- or
- ember-power-calendar-luxon, also
- moment
- objects or Luxon's
- DateTime
- instances. All options that are dates can take values of any type, and all
- actions that this component fires will contain dates in both formats too.
-
-
-
- Most of the time however, you just want the
- nav
- and
- days
- components rendered. For this scenario, simply invoke
- power-calendar
- without a block, like so:
-
- You can see that the calendar shows the selected date in blue. You may have
- also noticed that despite only passing a
- selected
- option, the month is not the current one. That is because in the absence of a
- specific
- center, the calendar will show the month of the selected date. If
- both options are provided,
- center
- always
- prevails.
-
-
-
- Enough of static calendars. If you just wanted to display a static grid of
- days you probably wouldn't be using an ember-addon for that. You want to
- navigate months, you want to select days and ranges. Let's see how to do these
- things in the next chapter.
-
-
-
- < Installation & setup
- Action handling >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/i18n.gts b/docs/app/templates/public-pages/docs/i18n.gts
new file mode 100644
index 00000000..cd3dfa4f
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/i18n.gts
@@ -0,0 +1,49 @@
+import CodeExample from 'docs/components/code-example';
+import I18n1 from '../../../components/snippets/i18n-1';
+import I18n2 from '../../../components/snippets/i18n-2';
+import { LinkTo } from '@ember/routing';
+
+
+
I18n
+
+
+ Ember Power Calendar uses exposes a power-calendar service that has a locale
+ property and uses that locale to format dates. If you want to change the
+ locale for all your calendars, set the
+ locale
+ property on that service and every calendar will update.
+
+
+
+ When the locale is updated not only the language changes but also the first
+ day of the week and any other configuration.
+
+
+
+ {{I18n1}}
+
+
+
+ Also, you can override the global locale on a per-instance basis passing
+ locale="some-locale". The next calendar is going to be in russian
+ no matter what the global locale is.
+
+
+
+ {{I18n2}}
+
+
+
+ In the next sections you are going to see how to customize the sub-components
+ of the calendar.
+
- Ember Power Calendar uses exposes a `power-calendar` service that has a locale
- property and uses that locale to format dates. If you want to change the
- locale for all your calendars, set the
- locale
- property on that service and every calendar will update.
-
-
-
- When the locale is updated not only the language changes but also the first
- day of the week and any other configuration.
-
- Also, you can override the global locale on a per-instance basis passing
- locale="some-locale". The next calendar is going to be in russian
- no matter what the global locale is.
-
- In the next sections you are going to see how to customize the sub-components
- of the calendar.
-
-
-
- < Multiple selection
- The
- nav >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/index.gts b/docs/app/templates/public-pages/docs/index.gts
new file mode 100644
index 00000000..1e694674
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/index.gts
@@ -0,0 +1,83 @@
+import { LinkTo } from "@ember/routing";
+
+
+
Overview
+
+
+ Calendars.
+
+
+
+ I don't know about you, but every time I found myself adding a calendar or
+ datepicker to an Ember app, I
+ never
+ had a good time.
+
+
+
+ There are some addons out there that wrap jQuery libraries which claim to make
+ your life easier. And they do at first. Having a basic calendar rendered with
+ the default styles takes minutes and you feel very productive. However, there
+ is always something else that makes you push your calendar a little bit beyond
+ the basic usage, and this is where things get
+ unpleasant.
+
+
+
+ Sometimes it is customizing the appearance, sometimes it is hooking your app
+ into the calendar to do things when you hover or click a day. Maybe
+ highlighting days, or adding tooltips to days with events... Ugh.
+
+
+
The problem is not in the addons, it's in the libraries they wrap.
+
+
+ Most jQuery libraries for calendars act as blackboxes where you don't get to
+ choose how they render or how they work. You just have a public javascript API
+ with options that allow you to tweak here and there. That is understandable
+ because they were designed to be used in an imperative environment, so I'm not
+ critisizing those libraries either.
+
+
+
+ The problem is that those APIs are imperative and wrapping them in a way that
+ can be used from a declarative language like
+ Handlebars
+ is not simple, and even if you get it right you are naturally limited by the
+ public API that they wrap.
+
+
+
+ Generally speaking I think wrapping an imperative library is a convenient
+ solution for simple use cases, but it doesn't scale well beyond a certain
+ complexity level. It also has inherent problems playing nicely with Ember: no
+ fastboot rendering, manual bookkeeping of event handlers and data bindings,
+ inability to use your own templates and difficulty to interact with it in
+ tests, to identify a few.
+
+
+
+ Ember Power Calendar
+ aims to solve the calendar problem
+ The Ember Way: Providing sensible defaults but allowing users to hook
+ into what is going on and how things look, just the way they do with their own
+ components: Handling actions, passing data, providing their own blocks to
+ replace the parts that don't fit their needs.
+
+
+
+ While achieving this flexibility, it also attempts to make the simple case
+ simple by bringing some conventions, defaults and good patterns to the table.
+
+
+
Just the Ember philosophy, but with days, weeks and stuff like that.
- I don't know about you, but every time I found myself adding a calendar or
- datepicker to an Ember app, I
- never
- had a good time.
-
-
-
- There are some addons out there that wrap jQuery libraries which claim to make
- your life easier. And they do at first. Having a basic calendar rendered with
- the default styles takes minutes and you feel very productive. However, there
- is always something else that makes you push your calendar a little bit beyond
- the basic usage, and this is where things get
- unpleasant.
-
-
-
- Sometimes it is customizing the appearance, sometimes it is hooking your app
- into the calendar to do things when you hover or click a day. Maybe
- highlighting days, or adding tooltips to days with events... Ugh.
-
-
-
The problem is not in the addons, it's in the libraries they wrap.
-
-
- Most jQuery libraries for calendars act as blackboxes where you don't get to
- choose how they render or how they work. You just have a public javascript API
- with options that allow you to tweak here and there. That is understandable
- because they were designed to be used in an imperative environment, so I'm not
- critisizing those libraries either.
-
-
-
- The problem is that those APIs are imperative and wrapping them in a way that
- can be used from a declarative language like
- Handlebars
- is not simple, and even if you get it right you are naturally limited by the
- public API that they wrap.
-
-
-
- Generally speaking I think wrapping an imperative library is a convenient
- solution for simple use cases, but it doesn't scale well beyond a certain
- complexity level. It also has inherent problems playing nicely with Ember: no
- fastboot rendering, manual bookkeeping of event handlers and data bindings,
- inability to use your own templates and difficulty to interact with it in
- tests, to identify a few.
-
-
-
- Ember Power Calendar
- aims to solve the calendar problem
- The Ember Way: Providing sensible defaults but allowing users to hook
- into what is going on and how things look, just the way they do with their own
- components: Handling actions, passing data, providing their own blocks to
- replace the parts that don't fit their needs.
-
-
-
- While achieving this flexibility, it also attempts to make the simple case
- simple by bringing some conventions, defaults and good patterns to the table.
-
-
-
Just the Ember philosophy, but with days, weeks and stuff like that.
-
-
I hope you find it useful.
-
-
- Installation >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/installation.gts b/docs/app/templates/public-pages/docs/installation.gts
new file mode 100644
index 00000000..5644a3f1
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/installation.gts
@@ -0,0 +1,199 @@
+import { LinkTo } from "@ember/routing";
+import CodeExample from "docs/components/code-example";
+
+
+
Installation & setup
+
+
+ Ember-power-calendar is distributed as an
+ Ember-cli
+ addon, so the major part of installation will be done by following command on
+ your ember project
+
+
+
+
$ ember install
+ ember-power-calendar
+
+
+
But this is not enough to put the calendar to work.
+
+
Choose your preferred date library
+
+
+ Date manipulation is
+ hard. Date internationalization is even harder. That's why this
+ component needs help from a third party date library to display and manipulate
+ dates.
+
+
+
+ From the ones available out there
+ Moment.js
+ and
+ Luxon
+ are my favorites, and I created two addons you can choose from to make Ember
+ Power Calendar work that use those libraries:
+
+ Note:
+ Although the calendars should behave the same regardless of the option you
+ choose, there might be subtle differences in how dates are displayed, as
+ Moment.js bundles its own translations while Luxon uses the
+ Intl.DateTimeFormat
+ native API to localize dates into the user's language (that also means Luxon
+ is a lighter library).
+
+
+
+ Choose the one you prefer and just install it as any other addon, for instance
+ ember install ember-power-calendar-luxon, and your calendar will
+ work, but will look ugly.
+
+
+
+ After you have installed you need to register the date library to
+ ember-power-calendar. For
+ ember-power-calendar-moment
+ you need to add this lines.
+
+
+ If you are using any other date library please check the ReadMe of the
+ package.
+
+
+
Add the styles
+
+
+ If you use vanilla CSS, you need to add the following line into
+ app.js
+ or in any route/controller/component
+ .js/.ts
+ file:
+
+
+
+
+
+ Instead of adding the styling in an
+ .js
+ file and depending from your build config you can also add the css in any
+ template/component css file by using following line
+
+
+
+
+
+ However, if you are using SASS or LESS you need to add an import statement to
+ your styles.
+
+
+
+
+
+ Doing that will bring in all of the styles except those related to the size of
+ the calendar. For defining the size of the calendar there is a mixin that
+ takes the size of the cell you want your calendar to be. By example:
+
+
+
+
+
+
+
+ The
+ ember-power-calendar
+ mixin also allows a great amount of customization regarding the coloring of
+ the calendar.
+
+
+
+
+
+
+ For those using Less, the process is very similar. Import the addon styles
+ with:
+
+
+
+
+
+ The mixin provided can be used like so:
+
+
+
+
+
+ This code above will make each one of those classes have a different size.
+
- Ember-power-calendar is distributed as an
- Ember-cli
- addon, so the major part of installation will be done by following command on
- your ember project
-
-
-
-
$ ember install
- ember-power-calendar
-
-
-
But this is not enough to put the calendar to work.
-
-
Choose your preferred date library
-
-
- Date manipulation is
- hard. Date internationalization is even harder. That's why this
- component needs help from a third party date library to display and manipulate
- dates.
-
-
-
- From the ones available out there
- Moment.js
- and
- Luxon
- are my favorites, and I created two addons you can choose from to make Ember
- Power Calendar work that use those libraries:
-
- Note:
- Although the calendars should behave the same regardless of the option you
- choose, there might be subtle differences in how dates are displayed, as
- Moment.js bundles its own translations while Luxon uses the
- Intl.DateTimeFormat
- native API to localize dates into the user's language (that also means Luxon
- is a lighter library).
-
-
-
- Choose the one you prefer and just install it as any other addon, for instance
- ember install ember-power-calendar-luxon, and your calendar will
- work, but will look ugly.
-
-
-
- After you have installed you need to register the date library to
- ember-power-calendar. For
- ember-power-calendar-moment
- you need to add this lines.
-
-
- If you are using any other date library please check the ReadMe of the
- package.
-
-
-
Add the styles
-
-
- If you use vanilla CSS, you need to add the following line into
- app.js
- or in any route/controller/component
- .js/.ts
- file:
-
-
-
-
-
- Instead of adding the styling in an
- .js
- file and depending from your build config you can also add the css in any
- template/component css file by using following line
-
- However, if you are using SASS or LESS you need to add an import statement to
- your styles.
-
-
-
-
-
- Doing that will bring in all of the styles except those related to the size of
- the calendar. For defining the size of the calendar there is a mixin that
- takes the size of the cell you want your calendar to be. By example:
-
-
-
-
-
-
- The
- ember-power-calendar
- mixin also allows a great amount of customization regarding the coloring of
- the calendar.
-
-
-
-
-
- For those using Less, the process is very similar. Import the addon styles
- with:
-
-
-
-
-
- The mixin provided can be used like so:
-
-
-
-
-
- This code above will make each one of those classes have a different size.
-
- The addon is using internal ember-concurrency. For installation see
- ember-concurrency
- installation page.
-
-
-
- <
- Overview
- How to use it >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/multiple-selection.gts b/docs/app/templates/public-pages/docs/multiple-selection.gts
new file mode 100644
index 00000000..ff31012c
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/multiple-selection.gts
@@ -0,0 +1,104 @@
+import CodeExample from 'docs/components/code-example';
+import MultipleSelection1 from '../../../components/snippets/multiple-selection-1';
+import MultipleSelection2 from '../../../components/snippets/multiple-selection-2';
+import MultipleSelection3 from '../../../components/snippets/multiple-selection-3';
+import MultipleSelection4 from '../../../components/snippets/multiple-selection-4';
+import { LinkTo } from '@ember/routing';
+
+
+
Multiple dates
+
+
+ The last use case is allowing the user to select several non-consecutive
+ dates. Enter
+ power-calendar-multiple.
+
+
+
There is no much need of explanation, so lets see it in action. Play with it,
+ click around and use the keyboard.
+
+
+ {{MultipleSelection1}}
+
+
+
+ When you want to select multiple dates, the
+ selected
+ property is, unsurprisingly, an array of dates.
+
+
+
+ Every time you select a day, the
+ onSelect
+ action is called not with the date, but with an object. That object has a
+ date
+ property, containing the selected value as a native Javascript date, and if
+ you have decided to use
+ Moment.js, a
+ moment
+ property containing the same dates as a moment object, or a
+ datetime
+ property containing the array Luxon.DateTime if you are using Luxon.
+
+
+
+ It's worth noticing that clicking on a selected day unselects it and that the
+ days are passed in the order they are clicked.
+
+
+
+ Since what the
+ onSelect
+ action does is up to you, you can implement any logic you want, no matter how
+ absurd
+ complex it is.
+
+
+
+ By example, let's implement a calendar that allows you to click on any day,
+ and when you do, it selects the nearest day which number is prime, selecting
+ the lowest one in case of a tie.
+
+
+
+ {{MultipleSelection2}}
+
+
+
+ Why would anyone want to do that?! No clue.
+
+
+
+ Another thing to note is that selection order is preserved. The last clicked
+ element is at the last position of the array, so you can use this kind of
+ calendar to perform order sensitive selections:
+
+
+
+ {{MultipleSelection3}}
+
+
+
+ You can also set a
+ maxLength
+ property on the days component for the maximum number of days that can be
+ selected
+
+
+
+ {{MultipleSelection4}}
+
+
+
+ Now lest talk about serious business. Customization.
+
- When you want to select multiple dates, the
- selected
- property is, unsurprisingly, an array of dates.
-
-
-
- Every time you select a day, the
- onSelect
- action is called not with the date, but with an object. That object has a
- date
- property, containing the selected value as a native Javascript date, and if
- you have decided to use
- Moment.js, a
- moment
- property containing the same dates as a moment object, or a
- datetime
- property containing the array Luxon.DateTime if you are using Luxon.
-
-
-
- It's worth noticing that clicking on a selected day unselects it and that the
- days are passed in the order they are clicked.
-
-
-
- Since what the
- onSelect
- action does is up to you, you can implement any logic you want, no matter how
- absurd
- complex it is.
-
-
-
- By example, let's implement a calendar that allows you to click on any day,
- and when you do, it selects the nearest day which number is prime, selecting
- the lowest one in case of a tie.
-
- Another thing to note is that selection order is preserved. The last clicked
- element is at the last position of the array, so you can use this kind of
- calendar to perform order sensitive selections:
-
- Now lest talk about serious business. Customization.
-
-
-
- < Range selection
- I18n
- >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/range-selection.gts b/docs/app/templates/public-pages/docs/range-selection.gts
new file mode 100644
index 00000000..591438cb
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/range-selection.gts
@@ -0,0 +1,167 @@
+import CodeExample from 'docs/components/code-example';
+import RangeSelection1 from '../../../components/snippets/range-selection-1';
+import RangeSelection2 from '../../../components/snippets/range-selection-2';
+import RangeSelection3 from '../../../components/snippets/range-selection-3';
+import RangeSelection4 from '../../../components/snippets/range-selection-4';
+import RangeSelection5 from '../../../components/snippets/range-selection-5';
+import RangeSelection6 from '../../../components/snippets/range-selection-6';
+import RangeSelection7 from '../../../components/snippets/range-selection-7';
+import { LinkTo } from '@ember/routing';
+
+
+
Range selection
+
+
+ The most common use case of calendars is selecting a single day. The second
+ most common one is selecting a duration, aka, a range.
+
+
+
+ The only differences in the API between a calendar for selecting a single day
+ and a calendar for selecting a range are that the name of the component is now
+ power-calendar-range
+ and that the
+ selected
+ option has to implement the
+ Range
+ interface. It might sound scary, but it only means that it has to be an object
+ with
+ start
+ and
+ end
+ properties.
+
+
+
+ The same
+ onSelect
+ action used in the previous chapter to select one date, is now used to select
+ a range. The object that this action receives has a
+ date
+ and either
+ moment
+ or
+ datetime
+ properties, each one containing a range with the dates in native Date objects
+ or in momentJS/Luxon.DateTime objects.
+
+
+
+ Lets see this in action.
+
+
+
+ {{RangeSelection1}}
+
+
+
+ All the days in the range are selected, and the ends of the range have some
+ special classes so you can style them differently.
+
+
+
+ Let's see an example:
+
+
+
+ {{RangeSelection2}}
+
+
+
Hey, I never said I was a brilliant designer! But you get the idea.
+
+
The minRange and maxRange option
+
+
+ Usually the only restriction in ranges is that they have to start in one day
+ and end in a different day, but sometimes you want to be more restrictive on
+ the length of the range, so the
+ minRange
+ and
+ maxRange
+ cover this they way you expect them to.
+
+
+
+ Those options accept a
+ number
+ and a
+ string. If you are using Moment, it can also take a
+ moment.Duration
+ object, and if you are using Luxon a
+ Luxon.Duration
+ one. The default minimum range is one day, so the range has to start in a
+ different date from where it begins and there is no maximum range.
+
+
+
If you want to force the user to pick a range of at least 3 days you can just
+ pass a number:
+
+
+ {{RangeSelection3}}
+
+
+
+ Notice that once you select one end of the range the days that cannot be
+ selected are disabled automatically.
+
+
+
+ This property accepts humanized durations which makes it very nice to use with
+ different units other than days. Let's make the range be of at most one week.
+
+
+
+ {{RangeSelection4}}
+
+
+
+ As you'd expect, you can also use the abbreviations accepted by
+ MomentJs
+ and combine
+ minRange
+ and
+ maxRange
+ as you want.
+
+
+
+ {{RangeSelection5}}
+
+
+
+ If you want to allow ranges to begin and end on the same day, pass
+ minRange=0.
+
+
+
+ {{RangeSelection6}}
+
+
+
The proximitySelection option
+
+ This option changes the behaviour of date selection after a choosing a start
+ and an end date. The default behaviour on the third click will select a new
+ start date of a brand new range. With this flag enabled, once you have a
+ range, clicking a third time will move the closest of the extremes, narrowing
+ or extending the range.
+
+
+
+ {{RangeSelection7}}
+
+
+
+ Now let's see how to select several non-consecutive dates.
+
- The most common use case of calendars is selecting a single day. The second
- most common one is selecting a duration, aka, a range.
-
-
-
- The only differences in the API between a calendar for selecting a single day
- and a calendar for selecting a range are that the name of the component is now
- power-calendar-range
- and that the
- selected
- option has to implement the
- Range
- interface. It might sound scary, but it only means that it has to be an object
- with
- start
- and
- end
- properties.
-
-
-
- The same
- onSelect
- action used in the previous chapter to select one date, is now used to select
- a range. The object that this action receives has a
- date
- and either
- moment
- or
- datetime
- properties, each one containing a range with the dates in native Date objects
- or in momentJS/Luxon.DateTime objects.
-
Hey, I never said I was a brilliant designer! But you get the idea.
-
-
The minRange and maxRange option
-
-
- Usually the only restriction in ranges is that they have to start in one day
- and end in a different day, but sometimes you want to be more restrictive on
- the length of the range, so the
- minRange
- and
- maxRange
- cover this they way you expect them to.
-
-
-
- Those options accept a
- number
- and a
- string. If you are using Moment, it can also take a
- moment.Duration
- object, and if you are using Luxon a
- Luxon.Duration
- one. The default minimum range is one day, so the range has to start in a
- different date from where it begins and there is no maximum range.
-
-
-
If you want to force the user to pick a range of at least 3 days you can just
- pass a number:
- Notice that once you select one end of the range the days that cannot be
- selected are disabled automatically.
-
-
-
- This property accepts humanized durations which makes it very nice to use with
- different units other than days. Let's make the range be of at most one week.
-
- This option changes the behaviour of date selection after a choosing a start
- and an end date. The default behaviour on the third click will select a new
- start date of a brand new range. With this flag enabled, once you have a
- range, clicking a third time will move the closest of the extremes, narrowing
- or extending the range.
-
- Now let's see how to select several non-consecutive dates.
-
-
-
- < Action handling
- Multiple selection >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/test-helpers.gts b/docs/app/templates/public-pages/docs/test-helpers.gts
new file mode 100644
index 00000000..20769887
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/test-helpers.gts
@@ -0,0 +1,73 @@
+import { LinkTo } from "@ember/routing";
+import CodeExample from "docs/components/code-example";
+
+
+
Test helpers
+
+
+
Acceptance Tests
+
+
+ Ember Power Calendar provides two acceptance helpers (calendarCenter
+ and
+ calendarSelect) that make it nicer to interact with the component
+ during tests.
+
+
+
calendarCenter(cssSelector, date)
+
+
+ This async helper allows you to move the center (change the month) of the
+ calendar in the given selector without interacting with the nav.
+
+
+
+
+
If the calendar does not have an
+ onCenterChange
+ action it will throw a helpful error message.
+
+
calendarSelect(cssSelector, date)
+
+
+ Use this helper to select a day of the calendar like if you clicked on it. If
+ to do so the calendar has to display a different month, it will do that
+ automatically.
+
+
+
+
+
+ If you are dealing with a multiple or range calendar you can just call it more
+ than once.
+
+
+
Integration Tests
+
+
+ Just import the helpers like
+ import { calendarCenter, calendarSelect } from
+ 'ember-power-calendar/test-support/helpers';
+ and use them as any other helper 😀
+
- Ember Power Calendar provides two acceptance helpers (calendarCenter
- and
- calendarSelect) that make it nicer to interact with the component
- during tests.
-
-
-
- To use those helpers in acceptance tests you need to register them in the
- /tests/helpers/start-app.js
- file.
-
-
-
- For that import the registration function and invoke it immedialty.
-
-
-
-
-
- Important note:
- Since version 0.6.0, all the test helpers can also be imported like
- import { calendarCenter, calendarSelect } from
- 'ember-power-calendar/test-support/helpers';
- and used indistinctly in acceptance or integration tests, with or without
- async/await. If you use this approach you don't need to register them as
- global helpers anymore.
-
-
-
calendarCenter(cssSelector, dateOrMoment)
-
-
- This async helper allows you to move the center (change the month) of the
- calendar in the given selector without interacting with the nav.
-
-
-
-
-
If the calendar does not have an
- onCenterChange
- action it will throw a helpful error message.
-
-
calendarSelect(cssSelector, dateOrMoment)
-
-
- Use this helper to select a day of the calendar like if you clicked on it. If
- to do so the calendar has to display a different month, it will do that
- automatically.
-
-
-
-
-
- If you are dealing with a multiple or range calendar you can just call it more
- than once.
-
-
-
- Note:
- Remember to whitelist
- calendarCenter
- and
- calendarSelect
- in the list of allowed globals in your
- tests/.jshintrc
- or
- tests/.eslintrc.js
- manifest.
-
-
-
Integration Tests
-
-
- Just import the helpers like
- import { calendarCenter, calendarSelect } from
- 'ember-power-calendar/test-support/helpers';
- and use them as any other helper 😀
-
-
-
- < The days
- Api reference >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/the-days.gts b/docs/app/templates/public-pages/docs/the-days.gts
new file mode 100644
index 00000000..996258aa
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/the-days.gts
@@ -0,0 +1,211 @@
+import CodeExample from 'docs/components/code-example';
+import TheDays0 from '../../../components/snippets/the-days-0';
+import TheDays1 from '../../../components/snippets/the-days-1';
+import TheDays2 from '../../../components/snippets/the-days-2';
+import TheDays3 from '../../../components/snippets/the-days-3';
+import TheDays4 from '../../../components/snippets/the-days-4';
+import TheDays5 from '../../../components/snippets/the-days-5';
+import TheDays6 from '../../../components/snippets/the-days-6';
+import TheDays7 from '../../../components/snippets/the-days-7';
+import TheDays8 from '../../../components/snippets/the-days-8';
+import { LinkTo } from '@ember/routing';
+
+
+
The days
+
+
+ A calendar is basically a list of days, typically (although not necessarily)
+ displayed in a grid with 7 columns. So the first thing you might want to
+ customize is the content of each day.
+
+
+
Pass a custom class for each day
+
+
+ You can pass to this component a
+ dayClass
+ argument. If this argument is a string, that string will be added as a class
+ to every rendered day.
+
+
+
+ This on itself is not amazing, but if instead of a string
+ dayClass
+ is a function, it will be invoked for every day, receiving the day object and
+ the calendar. You can then implement any custom logic to add classes to
+ buttons.
+
+
+
+ Using this technique we can create complex things, like a calendar with
+ multiple selection in which the selected days have a
+ "magnetic"
+ border.
+
+
+
+ {{TheDays0}}
+
+
+
Passing a block
+
+
+ There are many ways of doing it, but the simplest one is passing a block that
+ will be the content of each cell of the grid. It's not the most versatile, but
+ it can be used for simple customizations.
+
+
+
+ The block receives two arguments. The first one is a useful day object and the
+ second is the public API of the component. You can check the API of both
+ objects
+ API reference
+ section.
+
+
+
+ Let's start by making the number of the days of the weeked be strong and pink,
+ because we like weekends.
+
+
+
+ {{TheDays1}}
+
+
+
+ The properties of they so called "day" object to make most common
+ customizations easy.
+
+
+
Just using the public API
+
+
+ Like with
+ The nav
+ component, all the behaviour is implemented using the public API of the
+ calendar, so you can build your calendar and replace it.
+
+
+
+ This is a non-trivial example where I build a weird month grid that has no
+ Mondays or Wednesdays. Yay short weeks!
+
+
+
+ {{TheDays2}}
+
+
+
Passing a custom component
+
+
+ Just like with the nav component, you can encapsulate this weird grid with 5
+ days week into a component to reuse it all over the place. Maybe if you use it
+ often enough the boss end up thinking weeks have 3 working days.
+
+
+
+ {{TheDays3}}
+
+
+
+ This options is the one that gives you more power, but it would be silly to
+ make users create their own components for very common changes like
+ customizing the start of the week and things like that, so the default
+ calendar.Days
+ component has a few configuration options to tweak for the most common use
+ cases.
+
+
+
startOfWeek
+
+
+ By default, weeks will start on the appropriate day of the week based on the
+ locale configured in the
+ service:power-calendar
+ (which defaults to the global locale configured in MomentJS if you are using
+ it). There is a built in option to tweak the locale's default, pass
+ startOfWeek=[NUMBER]
+ to change the first day of the week. Values go from
+ 0
+ (Sunday) to
+ 6
+ (Saturday).
+
+
+
+ {{TheDays4}}
+
+
+
showDaysAround
+
+
+ By default the calendar displays the days of the surrounding months in the
+ first and last week but if you want to hide them pass
+ showDaysAround=false.
+
+
+
+ {{TheDays5}}
+
+
+
minDate and maxDate
+
+
+ If you want to prevent some days before a particular date from being selected,
+ pass
+ minDate=someDate
+ and/or
+ maxDate=someOtherDate. Dates before/after those values can be
+ selected (those dates included), but the rest of the days cannot be selected
+ or focused.
+
+
+
By example, in the next example, only days between 11th and 21th can be
+ selected (both inclusive)
+
+
+ {{TheDays6}}
+
+
+
disabledDates
+
+
+ Sometimes you don't want to disabled dates before or after some marks but some
+ specific list of dates, like holidays or birthdays. The
+ disabledDates
+ is what you want. Pass a collection of Date or Moment objects and those days
+ will be disabled.
+
+
+
+ {{TheDays7}}
+
+
+
weekdayFormat
+
+
+ By default the name of the days of the week is in its abbreviated form, but
+ you can use the
+ weekdayFormat
+ to change it. The accepted values are
+ short
+ (the default),
+ long
+ (the full day name) and
+ min
+ (an even shorter abbreviation).
+
- A calendar is basically a list of days, typically (although not necessarily)
- displayed in a grid with 7 columns. So the first thing you might want to
- customize is the content of each day.
-
-
-
Pass a custom class for each day
-
-
- You can pass to this component a
- dayClass
- argument. If this argument is a string, that string will be added as a class
- to every rendered day.
-
-
-
- This on itself is not amazing, but if instead of a string
- dayClass
- is a function, it will be invoked for every day, receiving the day object and
- the calendar. You can then implement any custom logic to add classes to
- buttons.
-
-
-
- Using this technique we can create complex things, like a calendar with
- multiple selection in which the selected days have a
- "magnetic"
- border.
-
- There are many ways of doing it, but the simplest one is passing a block that
- will be the content of each cell of the grid. It's not the most versatile, but
- it can be used for simple customizations.
-
-
-
- The block receives two arguments. The first one is a useful day object and the
- second is the public API of the component. You can check the API of both
- objects
- API reference
- section.
-
-
-
- Let's start by making the number of the days of the weeked be strong and pink,
- because we like weekends.
-
- The properties of they so called "day" object to make most common
- customizations easy.
-
-
-
Just using the public API
-
-
- Like with
- The nav
- component, all the behaviour is implemented using the public API of the
- calendar, so you can build your calendar and replace it.
-
-
-
- This is a non-trivial example where I build a weird month grid that has no
- Mondays or Wednesdays. Yay short weeks!
-
- Just like with the nav component, you can encapsulate this weird grid with 5
- days week into a component to reuse it all over the place. Maybe if you use it
- often enough the boss end up thinking weeks have 3 working days.
-
- This options is the one that gives you more power, but it would be silly to
- make users create their own components for very common changes like
- customizing the start of the week and things like that, so the default
- calendar.Days
- component has a few configuration options to tweak for the most common use
- cases.
-
-
-
startOfWeek
-
-
- By default, weeks will start on the appropriate day of the week based on the
- locale configured in the
- service:power-calendar
- (which defaults to the global locale configured in MomentJS if you are using
- it). There is a built in option to tweak the locale's default, pass
- startOfWeek=[NUMBER]
- to change the first day of the week. Values go from
- 0
- (Sunday) to
- 6
- (Saturday).
-
- By default the calendar displays the days of the surrounding months in the
- first and last week but if you want to hide them pass
- showDaysAround=false.
-
- If you want to prevent some days before a particular date from being selected,
- pass
- minDate=someDate
- and/or
- maxDate=someOtherDate. Dates before/after those values can be
- selected (those dates included), but the rest of the days cannot be selected
- or focused.
-
-
-
By example, in the next example, only days between 11th and 21th can be
- selected (both inclusive)
- Sometimes you don't want to disabled dates before or after some marks but some
- specific list of dates, like holidays or birthdays. The
- disabledDates
- is what you want. Pass a collection of Date or Moment objects and those days
- will be disabled.
-
- By default the name of the days of the week is in its abbreviated form, but
- you can use the
- weekdayFormat
- to change it. The accepted values are
- short
- (the default),
- long
- (the full day name) and
- min
- (an even shorter abbreviation).
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/docs/the-nav.gts b/docs/app/templates/public-pages/docs/the-nav.gts
new file mode 100644
index 00000000..2a4f09d0
--- /dev/null
+++ b/docs/app/templates/public-pages/docs/the-nav.gts
@@ -0,0 +1,97 @@
+import CodeExample from 'docs/components/code-example';
+import TheNav1 from '../../../components/snippets/the-nav-1';
+import TheNav2 from '../../../components/snippets/the-nav-2';
+import TheNav3 from '../../../components/snippets/the-nav-3';
+import { LinkTo } from '@ember/routing';
+
+
+
+ The contextual components are
+ mostly
+ presentationals and you can customize how they look without much knowledge of
+ how the calendar works. The
+ calendar.Nav
+ component is the simplest one.
+
+
+
+ By default it displays the displayed month in
+ MMMM YYYY
+ format and a couple buttons to move to other months. Let's change that.
+
+
+
Passing a block
+
+
+ If you pass a block to this component, that block will replace the month/year
+ text. It can be used by example if you want to display the month in a
+ different format, maybe a more compact one for very small calendars.
+
+
+
+ {{TheNav1}}
+
+
+
Just using the public API
+
+
+ If the thing you want is beyond what you can do with the block, Ember Power
+ Calendar doesn't try to provide a miriad of option to configure the component.
+ Instead it gives you the tools to build it yourself using the yielded
+ calendar. It's easy!
+
+
+
+ For example, let's build a different nav that, by reusing the existing CSS
+ classes, allows you to change months
+ and years.
+
+
+
+ {{TheNav2}}
+
+
+
Passing your own component
+
+
+ The example above is simple and works if you only have one calendar, but if
+ you have several calendars it becomes repetitive. The last way of customizing
+ your calendar is replacing the
+ nav
+ component with your own component.
+
+
+
Let's encapsulate the same logic above into a component and use that instead
+
+
+ {{TheNav3}}
+
+
+
+ Now you have the same logic but to use it the only thing you have to do is
+ tell the calenda to use your component with
+ navComponent="name-of-my-component". Much easier to reuse across
+ your app.
+
- The contextual components are
- mostly
- presentationals and you can customize how they look without much knowledge of
- how the calendar works. The
- calendar.Nav
- component is the simplest one.
-
-
-
- By default it displays the displayed month in
- MMMM YYYY
- format and a couple buttons to move to other months. Let's change that.
-
-
-
Passing a block
-
-
- If you pass a block to this component, that block will replace the month/year
- text. It can be used by example if you want to display the month in a
- different format, maybe a more compact one for very small calendars.
-
- If the thing you want is beyond what you can do with the block, Ember Power
- Calendar doesn't try to provide a miriad of option to configure the component.
- Instead it gives you the tools to build it yourself using the yielded
- calendar. It's easy!
-
-
-
- For example, let's build a different nav that, by reusing the existing CSS
- classes, allows you to change months
- and years.
-
- The example above is simple and works if you only have one calendar, but if
- you have several calendars it becomes repetitive. The last way of customizing
- your calendar is replacing the
- nav
- component with your own component.
-
-
-
Let's encapsulate the same logic above into a component and use that instead
- Now you have the same logic but to use it the only thing you have to do is
- tell the calenda to use your component with
- navComponent="name-of-my-component". Much easier to reuse across
- your app.
-
-
-
- Enough about the nav. Now it's the days turn.
-
-
-
- <
- I18n
- The
- days >
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/index.gts b/docs/app/templates/public-pages/index.gts
new file mode 100644
index 00000000..746ca491
--- /dev/null
+++ b/docs/app/templates/public-pages/index.gts
@@ -0,0 +1,66 @@
+import { LinkTo } from "@ember/routing";
+import { formatDate } from "ember-power-calendar/utils";
+
+const today = new Date();
+
+
+
+
+ Powerful and customizable calendar component for
+
+
+
+
+
+
+
+
Feature rich
+ Out of the box support for mouse and keyboard, highlighting, events,
+ selection, esparse-dates and ranges, it gives you the tools to build the
+ awesome calendar your app needs.
+
+
+
+
+
+ {{formatDate
+ today
+ "D"
+ }}
+
+
+
+
With Ember for Ember
+ Built in Ember for Ember apps, it works like you expect it to so it blends
+ naturally into your usual worlflow like it you built it yourself.
+
+
+
+
+
+
+
Personalize it your way
+ Designed inside out to allow you to adjust it the way you want. Custom
+ days, a different grid, popups... Multiple extension point allow you to
+ tame it to your taste.
+
- Powerful and customizable calendar component for
-
-
-
-
-
-
-
-
Feature rich
- Out of the box support for mouse and keyboard, highlighting, events,
- selection, esparse-dates and ranges, it gives you the tools to build the
- awesome calendar your app needs.
-
-
-
-
-
- {{format-date
- this.today
- "D"
- }}
-
-
-
-
With Ember for Ember
- Built in Ember for Ember apps, it works like you expect it to so it blends
- naturally into your usual worlflow like it you built it yourself.
-
-
-
-
-
-
-
Personalize it your way
- Designed inside out to allow you to adjust it the way you want. Custom
- days, a different grid, popups... Multiple extension point allow you to
- tame it to your taste.
-
-
-
-
-
- Get started
-
-
\ No newline at end of file
diff --git a/docs/app/templates/public-pages/support-the-project.hbs b/docs/app/templates/public-pages/support-the-project.hbs
deleted file mode 100644
index 4c799c81..00000000
--- a/docs/app/templates/public-pages/support-the-project.hbs
+++ /dev/null
@@ -1,112 +0,0 @@
-
-
-
Support the Ember Power Project
-
-
- The Ember Power Project started with the goal of providing the Ember
- ecosystem with a set of curated components that cover common UX needs,
- built in Ember and designed work well in Ember apps., from following good
- patterns like DDAU to also be test-friendly and render properly in
- Fastboot.
-
-
-
- Over the time this evolved a bit into a theory of how an ecosystem should
- shape it's addons: Basic components that compose to create more complex
- components using good practices and allowing programmers to customize or
- directly replace the parts they don't like.
-
-
-
- Those components are divided in three tiers of complexity:
-
-
Building blocks: Components that do only one thing
- but do it right. They are low-level, take very few opinions and are
- focused on flexibility.
- Ember Basic
- Dropdown
- and
- ember-text-measurer
- are two of them.
-
- Power Components: Components that solve an UX problen
- The Ember Way. That is, they provide opinions and work out of
- the box with a nice public API, yet provide hooks for the users to
- customize or replace parts of it.
- Ember Power Calendar
- and
- Ember Power Select
- are of this kind.
-
-
- Power Meta-addons: Components that based on other
- components of the second tier but customize them for a specific
- purpose or pattern that is common enough to deserve to be shared so
- other users can use them without having to do the customization
- themselves.
- ember-power-select-sortable,
- ember-power-select-typeahead,
- ember-power-select-with-fallback
- are some examples, but there is many more.
-
-
-
-
-
- By creating a network if addons that compose between them to create even
- more addons, we share more. The more we share, the smaller our apps become
- because we don't need to reinvent wheels.
-
-
-
- If you enjoy the addons this project provides and they help you in your
- daily work, you can support the development of the addons and it's
- documentation pages with any contribution you feel appropiate by clicking
- on the button below but above all, by contributing, opening issues and
- Pull Requests, answering questions in Slack or StackOverflow and above
- all, showing appreciation for everyone who works on the Open Source
- Software we all use everyday.
-