fuelux/_includes/js/datepicker.html

<!-- datepicker
================================================== -->
<div class="fu-docs-section">
  <h1 id="datepicker" class="page-header">Datepicker <a href="{{ site.repo }}/blob/{{ site.current_version }}/js/datepicker.js"><small>datepicker.js</small></a></h1>
  <p>The <code>datepicker()</code> control provides the user with the ability to choose a date from a highly customizable calender. Datepicker also offers many <a href="#datepicker-usage-methods">methods</a> that allow you to programmatically manipulate it.</p>

  <form class="form-horizontal" style="width: 300px;">
    <div class="form-group">
      <label for="datepickerIllustration" class="col-sm-2 control-label">Date</label>
      <div class="col-sm-10">
        <div class="datepicker" data-initialize="datepicker" id="datepickerIllustration">
          {% include js/datepicker-example.html %}
        </div>
      </div>
    </div>
  </form>


  <div style="width: 140px; margin-left: 150px;">
  </div>

  <h2 id="datepicker-usage">Usage</h2>

  <h3 id="datepicker-usage-javascript">Via JavaScript</h3>
  <p>Initialize the <code>datepicker()</code> via JavaScript (accepting <a href="#datepicker-usage-options ">default options</a>):</p>
  {% highlight js %}$('#myDatepicker').datepicker();{% endhighlight %}

  <p>Initialize the <code>datepicker()</code> via JavaScript specifying your own <a href="#datepicker-usage-options ">options</a>:</p>
{% highlight js %}
$('#myDatepicker').datepicker({
  allowPastDates: true
});
{% endhighlight %}

  <h3 id="datepicker-usage-data-attributes">Via data-attributes</h3>
  <ul>
    <li>Datepicker controls that exist when <code>$().ready()</code> executes that have <code>data-initialize="datepicker"</code> on them will be initialized immediately</li>
    <li>Datepicker controls that are created with <code>data-initialize="datepicker"</code> after <code>$.ready()</code> executes will initialize when a <code>mousedown</code> event occurs on them.</li>
  </ul>

  <h3 id="datepicker-usage-markup">Markup</h3>
  <p>The <code>datepicker()</code> markup is complex and specific. On initialization, the <code>datepicker()</code> plugin searches inside of the specified element for the components used to build the control. For your convenience, we have written the <span class="text-danger">required</span> markup for you. Writing custom <code>datepicker()</code> markup is not recommended; if you choose to do so, understanding the <a href="{{ site.repo }}/blob/{{ site.current_version }}/js/datepicker.js">datepicker.js</a> code will be necessary.</p>
  <div class="truncate-highlight">
{% highlight html %}
{% include js/datepicker-example.html %}
{% endhighlight %}
  </div>

  <h3 id="datepicker-usage-options">Options</h3>
  <p>If <a href="#datepicker-usage-javascript">initializing through JavaScript</a>, <code>datepicker()</code> allows you to specify options.</p>
  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
        <tr>
          <th style="width: 100px;">Name</th>
          <th style="width: 100px;">type</th>
          <th style="width: 115px;">default</th>
          <th>description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>allowPastDates</td>
          <td>boolean</td>
          <td>false</td>
          <td>Dictates whether past dates can be input or selected by the user.</td>
        </tr>
        <tr>
          <td>date</td>
          <td>Date object, string, or falsy value ('', null, or false)</td>
          <td>new Date()</td>
          <td>Specifies the date that is set upon initialization. If using a string, the format must be a
          valid date string as supported by the browser or by moment.js if available. Falsy values will result
          in no date being set upon initialization.</td>
        </tr>
        <tr>
          <td>formatDate</td>
          <td>function or null</td>
          <td>null</td>
          <td>Function that is called for formatting a valid date object. Should only be overriden if the
          datepicker's default formatDate method is not sufficient for your needs. The formatDate function takes
          a date object as an argument, and should return a string.</td>
        </tr>
        <tr>
          <td>momentConfig</td>
          <td>object</td>
          <td>{<br/>&nbsp;&nbsp;&nbsp;&nbsp;culture: 'en',<br/>&nbsp;&nbsp;&nbsp;&nbsp;format: 'L'<br/>}</td>
          <td>Settings used to configure moment.js, if available. Both <code>culture</code> and <code>format</code>
          attributes must be present for moment features to be utilized. The <code>culture</code> attribute is a string
          representing the desired <code>datepicker()</code> language. The <code>format</code> attribute is a string representing the
          desired date format that appears in the input upon date selection. Consult the <a href="https://momentjs.com/docs/">moment.js</a>
          docs for more information on supported cultures and formats.</td>
        </tr>
        <tr>
          <td>parseDate</td>
          <td>function or null</td>
          <td>null</td>
          <td>Function that is called for parsing date strings input by the user. Should only be overriden if the
          datepicker's default parseDate method is not sufficient for your needs. The parseDate function takes a
          date object, string, or falsy value as an argument, and should return either a valid date object representing
          the successfully parsed value or invalid date object (<code>new Date(NaN)</code>)</td>
        </tr>
        <tr>
          <td>restricted</td>
          <td>array</td>
          <td>[]</td>
          <td>Specifies dates that are restricted from user input and selection. Uses an array of objects to provide
          the ranges. Each of the object must have the following format: <code>{ from: '03/31/2015', to: '03/31/2016' }</code>, but multiple ranges are supported. The <code>from</code> attribute represents the start date of the restricted range, and the <code>to</code> attribute represents the end date of the range, inclusively. Both attributes can be set to either a valid date
          string or a date object. <code>-Infinity</code> and <code>Infinity</code> are valid delimiters. View this gist to see <a href="https://gist.github.com/interactivellama/eee7795377b2914ca1c4">how to set the datepicker to only allow dates from the past 365 days</a>.</td>
        </tr>
        <tr>
          <td>sameYearOnly</td>
          <td>boolean</td>
          <td>false</td>
          <td>Prevents the user from selecting dates outside the current year if true.</td>
        </tr>
        <tr>
          <td>twoDigitYearProtection</td>
          <td>boolean</td>
          <td>true</td>
          <td>Attempts to accommodate for people entering two digit years. Only works if moment is being used to parse date. Otherwise browser parsing is used (which is inconsistent)</td>
        </tr>
      </tbody>
    </table>
  </div><!-- ./fu-table-responsive -->

  <h3 id="datepicker-usage-moment">Date Parsing and MomentJS</h3>

  <p><a href="https://momentjs.com/docs/">MomentJS</a> parsing is the <b>same format</b> for the API as the output within the <code>input</code> element. Datepicker's default MomentJS locale is regionalistic (American). If you are using MomentJS (and it is recommended that you do), option strings such as those within restricted date ranges expect the format that you provide within <code>momentConfig</code>. Locales and formats are available in the <a href="https://momentjs.com/docs/#/customization/long-date-formats/">MomentJS documentation</a>. The default locale configuration is <code>momentConfig: { culture: 'en', format: 'L' }</code></p>

  <p>Therefore if you do not specify your own locale and format, <code>restricted</code> will be expecting an array of objects of the<code>'MM/DD/YYYY'</code> format--that is the <code>'L'</code> MomentJS format. An example of this would be <code>restricted: [{ from: '08/10/2014', to: '08/15/2014' }]</code></p>

  <h3 id="datepicker-usage-methods">Methods</h3>
  <dl>
    <dt>.datepicker('destroy')</dt>
    <dd>Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.</dd>

    <dt id="datepicker-usage-methods-disable">.datepicker('disable')</dt>
    <dd>Ensures the component is disabled</dd>

    <dt id="datepicker-usage-methods-enable">.datepicker('enable')</dt>
    <dd>Ensures the component is enabled</dd>

    <dt id="datepicker-usage-methods-get-date">.datepicker('getDate')</dt>
    <dd>Returns the selected date (not formatted)</dd>

    <dt id="datepicker-usage-methods-get-formatted-date">.datepicker('getFormattedDate')</dt>
    <dd>Returns the selected formatted date</dd>

    <dt id="datepicker-usage-methods-set-date">.datepicker('setDate')</dt>
    <dd>
      Sets <code>datepicker()</code> to date provided. Date provided must be a valid Date object or date string.
      {% highlight js %}$('#myDatepicker').datepicker('setDate', new Date());{% endhighlight %}
    </dd>


    <dt id="datepicker-usage-methods-get-culture">.datepicker('getCulture')</dt>
    <dd>Returns the culture the <code>datepicker()</code> is currently using. <em>Only available using <code>moment.js</code> with langs</em></dd>

    <dt id="datepicker-usage-methods-set-culture">.datepicker('setCulture')</dt>
    <dd>
      Updates the culture the <code>datepicker()</code> uses. <em>Only available using <code>moment.js</code> with langs</em>
      {% highlight js %}$('#myDatepicker').datepicker('setCulture', 'fr');{% endhighlight %}
    </dd>


    <dt id="datepicker-usage-methods-get-format">.datepicker('getFormat')</dt>
    <dd>Returns the format the <code>datepicker()</code> is currently using. <em>Only available using <code>moment.js</code> with langs</em></dd>

    <dt id="datepicker-usage-methods-set-format">.datepicker('setFormat')</dt>
    <dd>
      Updates the format the <code>datepicker()</code> uses. <em>Only available using <code>moment.js</code> with langs</em>
      {% highlight js %}$('#myDatepicker').datepicker('setFormat', 'L');{% endhighlight %}
    </dd>
  </dl>


  <h3 id="datepicker-usage-events">Events</h3>
  <div class="table-responsive">
  <table class="table table-bordered table-striped">
    <thead>
    <tr>
      <th style="width: 150px;">Event Type</th>
      <th>Description</th>
    </tr>
    </thead>
    <tbody>
      <tr>
        <td>changed.fu.datepicker</td>
        <td>This event is fired when the date value has been changed by the user inputing text into the input box. <em>Choosing the date by clicking in the datepicker will not fire this event</em>. Arguments include <code>event, date</code> where date is a JavaScript <code>Date</code> object.</td>
      </tr>
      <tr>
        <td>dateClicked.fu.datepicker</td>
        <td>This event is fired when a day has been selected on the calendar. Arguments include <code>event, date</code> where date is a JavaScript <code>Date</code> object.</td>
      </tr>
      <tr>
        <td>inputParsingFailed.fu.datepicker</td>
        <td>This event is fired when an invalid date is parsed on blur of the datepicker. Arguments include <code>event, date</code> where date is a JavaScript <code>Date</code> object.</td>
      </tr>
      <tr>
        <td>inputRestrictedDate.fu.datepicker</td>
        <td>This event is fired when an restricted date is parsed on blur of the datepicker. Arguments include <code>event, date</code> where date is a JavaScript <code>Date</code> object.</td>
      </tr>
    </tbody>
  </table>


  </div><!-- ./fu-table-responsive -->
  <p>All <code>datepicker()</code> events are fired on the <code>.datepicker</code> classed element.</p>
{% highlight js %}
$('#myDatepicker').on('changed.fu.datepicker', function (evt, date) {
  // do something…
});
{% endhighlight %}

  <p>To listen for changes on the <code>Date()</code> object, you will need to combine two listeners (as shown below). The reason for this is to keep double events firing when a date is clicked (previously when a date was clicked <code>dateClicked</code> and <code>changed</code> would both fire, which was confusing to many people.</p>
{% highlight js %}
$('#myDatepicker').on('changed.fu.datepicker dateClicked.fu.datepicker', function (evt, date) {
  // do something…
});
{% endhighlight %}

  <p>To listen for all changes to the <code>datepicker</code>'s input value, including setting the date to <code>invalid</code> values, you will need to combine two listeners:</p>
{% highlight js %}
$('#myDatepicker').on('change dateClicked.fu.datepicker', function (evt, date) {
  // do something…
});
{% endhighlight %}

  <h2 id="datepicker-examples">Examples</h2>
  <p>Choose a date from a calendar dropdown, with input parsing and formatting. Works with moment.js for extended functionality.</p>

  <p>To support various date formats around the world, <code>datepicker()</code> has an optional dependency on <a href="https://momentjs.com/">moment.js</a>. <a href="https://github.com/moment/moment/tree/master/min">Download moment.js (with locales).</a></p>

  <div class="fu-example section">
    <div id="myDatepickerContainer">
      <form class="form-horizontal" style="width: 600px;">
        <div class="form-group">
          <label for="datepickerIllustration" class="col-sm-4 control-label" for="myDatepickerInput">Choose a date (default)</label>
          <div class="col-sm-8">
            <div class="datepicker" data-initialize="datepicker" id="myDatepicker">
              {% include js/datepicker-example.html %}
            </div>
          </div>
        </div>
      </form>
    </div>
    <h5 id="datepicker-examples-sample-methods">Sample Methods</h5>
    <div class="btn-group">
      <button type="button" class="btn btn-default" id="btnDatepickerEnable">enable</button>
      <button type="button" class="btn btn-default" id="btnDatepickerDisable">disable</button>
      <button type="button" class="btn btn-default" id="btnDatepickerLogFormattedDate">log formatted date</button>
      <button type="button" class="btn btn-default" id="btnDatepickerLogDateObj">log date object</button>
    </div>
    <div class="btn-group">
      <button type="button" class="btn btn-default" id="btnDatepickerSetDate">set date 7 days ahead (will log new value)</button>
      <button type="button" class="btn btn-default" id="btnDatepickerDestroy">destroy and append</button>
    </div>
  </div>


</div>