text:
---
layout: js-documentation
title: Javascript-powered UI Components
description: Create interactive pages, no javascript required!
site_root:  ../../
---

{% capture IframeHead %}

    <meta charset="utf-8">

    <link rel="stylesheet" href="https://ink.freetls.fastly.net/{{ site.version }}/css/ink-flex.css">

{% endcapture %}

Ink's vast array of UI components can be used in combination to create rich, interactive pages. They are many, and are very flexible. Javascript is not required for a lot of cases, but if you want to do more advanced stuff, you have to write some of it.

To get started, include the following JS files in the *bottom* of your HTML:

{% highlight html %}

{% endhighlight %}

## Autoload

Although this is a page for Javascript-powered components, You will only find pure HTML examples on this page. That is because, thanks to Autoload (the `autoload.js` file you loaded above) you don't need to write any Javascript to do most things.

`autoload.js` is a small Javascript file that avoids a lot of boilerplate javascript to create the UI components on this page. It does so by initializing these elements automatically (`new Component(componentElement, options)`) based on their CSS class, so you don't have to.

All Ink UI components are registered to be loaded in Autoload, with a class similar to their name. For example, to create a Modal, you add the `.ink-modal` class to an element. To create a Toggle, you add a `.ink-toggle` class to an element, and so on.

If you want, you can disable this behaviour. Just add `data-autoload="false"` to elements without autoload, or don't include `autoload.js` at all to disable it completely.

## A note on option names (`data-option-name` vs `optionName`)

All configuration options, except callback functions, are available as data-attributes but are prefixed with `data-` and are written in lowercase and hyphen separated: `someOption` (as passed in javascript) is the same as `data-some-option` (as passed in HTML).

## Using these components with Javascript instead of autoload

In this page, you see a lot of javascript-powered components created only with HTML, but sometimes you need the extra edge -- The power to create and destroy components any time you like, or to pass callbacks and arbitrary objects.

{% highlight javascript %}
// This is a simple example for Toggle.
// For other components, you can replace "Toggle" below with the component name.
Ink.requireModules(['Ink.UI.Toggle_1'], function (Toggle) {
    // Every component is a plain old Javascript class. Its constructor takes two arguments:
    // an element on the page and a set of options.
    new Toggle('#my-toggle', {
        target: '#toggled-element'  // This is the same as data-target="#toggled-element"
    });
});
{% endhighlight %}

    Carousel

A responsive carousel with one or more slides per page. Cycle back and forth between slides with any content you can put in. You can also swipe back and forth with your finger if your device supports touch.

Most of the time, you will use this in conjunction with [Pagination](#InkUIPagination_1), because you want some sort of way to change pages!

### Carousel Examples

#### Basic example:

This example shows you how to create a basic Carousel, use it together with a basic [Pagination](#InkUIPagination_1). It's touch-enabled (touch support is on by default) and responsive (because it uses Ink's [CSS grid classes](/ui-elements/grid/#multiple-screen-sizes)). As you switch to smaller devices, you'll see that you get less slides per page to better use the viewport space.

{% capture Carousel %}

Title

Description paragraph

Title

Description paragraph

Hello world!

Here is a form inside a Carousel:

            <form class="ink-form">
                <input type="text" placeholder="just because!" />
                <button class="ink-button">Go!</button>
            </form>

Title

Description paragraph

{% endcapture %}

Demo

{{ Carousel }}

Code

{% highlight html %}
{{ Carousel }}
{% endhighlight %}

#### Carousel with chevrons example

This is how you create a Carousel with chevron pagination.

To use a chevron [Pagination](#InkUIPagination_1) with it, embed the `.ink-pagination` element inside the `.ink-carousel` element and add the `chevron` class to its `ul`.

{% capture Carousel %}

This is slide 1

This is slide 2

This is slide 3

{% endcapture %}

Demo

{{ Carousel }}

Code

{% highlight html %}
{{ Carousel }}
{% endhighlight %}

### Carousel options

Add the following attributes to your `.ink-carousel` element to configure your Carousel.

 * `data-pagination="<selector>"`: [Pagination](#InkUIPagination_1) element to use with this Carousel. *Don't forget this!*
 * `data-initial-page="<page>"`: Carousel starts in `page`. First page is 0.
 * `data-space-after-last-slide="false"`: Don't leave blank space after the last slide.
 * `data-swipe="false"`: Disable touch support.
 * `data-auto-advance="<time>"`: Auto-advance pages every `time` milliseconds.

You can read the list of options to create the Carousel with JS [here](/javascript/Ink.UI.Carousel/).

### Advanced Carousel stuff:

You can visit [the Carousel API docs](/javascript/Ink.UI.Carousel/) to find out about Javascript-only options, javascript methods, and how to create Carousels using Javascript

-------------

    Close

Dismiss things.

Add the `ink-close` or `ink-dismiss` to elements. Those elements, when clicked, will be removed. Plays well with the [Alert UI Element](/ui-elements/alerts/).

### Close Example

Here's an example. Click the × sign to close the alert. When you do, the element will be removed from the page.

{% capture Close %}

    <button class="ink-dismiss">×</button>

Click the X to close this!

{% endcapture %}

Demo

{{ Close }}

Code

{% highlight html %}
{{ Close }}
{% endhighlight %}

### Close options

(Close has no options)

### Advanced Close stuff:

There's not much to know about Close, but here are [the Close JS API docs](/javascript/Ink.UI.Close/).

-------------

    DatePicker

DatePicker is a component for picking dates. You use it together with an input box, and it gets filled with the date in a certain format. The user may change the date by navigating the calendar or by typing in the input box using the correct format.

The date's format is given in the `data-format` option, where you pass a date format string in the syntax of [PHP's `date()` function](https://php.net/manual/en/function.date.php#refsect1-function.date-parameters).

### DatePicker Examples

#### Basic example

This is a simple DatePicker, mostly using the default options. It writes the dates in DD-MM-YYYY format.

{% capture DatePicker %}

            <input type="text" class="ink-datepicker" data-format="d-m-Y" />

{% endcapture %}

Demo

{{ DatePicker }}

Code

{% highlight html %}
{{ DatePicker }}
{% endhighlight %}

#### Ranged example

A DatePicker which only accepts dates between the birth of [Aníbal Cavaco Silva](https://en.wikipedia.org/wiki/An%C3%ADbal_Cavaco_Silva) and today.

{% capture DatePicker %}

Pick a day in the life of Aníbal Cavaco Silva:

            <input
                type="text"
                class="ink-datepicker"
                data-format="d-m-Y"
                data-date-range="1939-07-15:NOW" />

{% endcapture %}

Demo

{{ DatePicker }}

Code

{% highlight html %}
{{ DatePicker }}
{% endhighlight %}

#### Always-open example

This is a DatePicker that never closes. To do this, we set it to not be "shy" (that is, don't close automatically), and we told it to open automatically.

We also need to hide the "close" button so it doesn't close on us, and add some CSS so that it doesn't have `position: absolute`.

{% capture DatePicker %}

            <input
                type="text"
                class="ink-datepicker"
                data-css-class="ink-calendar my-never-closing-datepicker"
                data-format="d-m-Y"
                data-shy="false"
                data-auto-open="true"
                data-show-clean="false"
                data-show-close="false" />

{% endcapture %}

Demo

{{ DatePicker }}

Code

{% highlight html %}
{{ DatePicker }}
{% endhighlight %}

### DatePicker options

Add the following attributes to your `.ink-datepicker` input element to configure your DatePicker.

#### Date options

 * `data-start-date="<yyyy>-<mm>-<dd>"`: Start with a certain date. Defaults to today.
 * `data-date-range="<start>:<end>"`: Only allow dates between `start` and `end`. Don't forget the `:` :).
 * `data-format="d-m-Y"`: Date format string. Uses the same syntax as [PHP's `date()` function](https://php.net/manual/en/function.date.php#refsect1-function.date-parameters). Let's see how they format the date "15th July of 1939":
   * `data-format="d-m-Y"` - "15-07-1939"
   * `data-format="Y/d/m"` - "1939/15/07"
   * `data-format="Y-m-d"` - "1939-07-15"

#### Text and formatting options:

 * `data-clean-text="<word>"`: Text for the "Clear" button.
 * `data-close-text="<word>"`: Text for the "Close" button.
 * `data-of-text="<of>"`: Text to show between month and year. Defaults to ' of '.
 * `data-next-link-text="<text>"`: Text for the next button. Defaults to '»'.
 * `data-prev-link-text="<text>"`: Text for the previous button. Defaults to '«'.
 * `data-start-week-day="<day>"`: First day of the week. Sunday is zero. Defaults to 1 (Monday).

#### Misc options

 * `data-show-clean="false"`: Hide the "Clear" button.
 * `data-show-close="false"`: Hide the "Close" button.
 * `data-auto-open="true"`: The DatePicker will be initially opened
 * `data-shy="false"`: Stop the DatePicker from closing itself automatically.
 * `data-css-class="ink-calendar <my classes>"`: Add classes to the DatePicker.
 * `data-on-focus="false"`: Add this if you don't want the DatePicker to open itself when you click the input.
 * `data-picker-field="<selector>"`: (if not using in an input[type="text"]) Element which displays the DatePicker when clicked. Defaults to an "open" link.
 * `data-position="right"`: Float the DatePicker to the right.

#### Options for using `<select>` elements instead of an `<input>` element.

Options to use DatePicker with `<select>` elements. They require `data-display-in-select="true"`.

 * `data-display-in-select="true"`: Enable this first.
 * `data-day-field="<selector>"`: `<select>` field with the days.
 * `data-month-field="<selector>"`: `<select>` field with the months.
 * `data-year-field="<selector>"`: `<select>` field with the years.

You can read the list of options to create the DatePicker with JS [here](/javascript/Ink.UI.DatePicker/).

### Advanced DatePicker stuff:

You can visit [the DatePicker API docs](/javascript/Ink.UI.DatePicker/) to find out about Javascript-only options, javascript methods, and how to create DatePickers using Javascript

-------------

    Draggable

Draggable is a component which works with [Droppable](#InkUIDroppable_1).

### Draggable Examples

#### Basic example

Drag some draggables around!

{% capture Draggable %}
Draggable 1
Draggable 2
Draggable 3
{% endcapture %}

Demo

{{ Draggable }}

Code

{% highlight html %}
{{ Draggable }}
{% endhighlight %}

#### Constraints

These Draggables can't move freely, they're constrained inside certain boundaries.

{% capture Draggable %}

        Drag me inside the box

{% endcapture %}

Demo

{{ Draggable }}

Code

{% highlight html %}
{{ Draggable }}
{% endhighlight %}

### Draggable options

 * `data-constraint="<vertical, horizontal or both>"` - Constrain Draggable movement in an axis. None by default. Can be `vertical`, `horizontal`, or `both`. By default movement is not constrained.
 * `data-constraint-elm="#my-div"` - Only drag inside `#my-div`. Make sure that element has a `min-height` to avoid weird behaviour.
 * `data-handle=".drag-here"` - The element with the `.drag-here` class will be used as a handle for dragging.
 * `data-revert="true"` - Revert the draggable to its original position when dropped.
 * `data-cursor="pointer"` - Set the mouse to `pointer` while hovering this Draggable, instead of `move`. Valid options here are the values of the [CSS `cursor` property](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor?redirectlocale=en-US&redirectslug=CSS%2Fcursor#Values).
 * `data-z-index="100"` - Set the z-index to 100 while dragging.
 * `data-fps="12"` - Move things at most 12 times per second. Use this to limit the CPU resources needed to perfrom a drag action.
 * `data-mouse-anchor="<anchor>"` - Anchor for the drag. Can be one of: `"left"`, `"center"`, `"right"`, `"top"`, `"center"`, `"bottom"`.
 * `data-drag-class="im-dragging"` - Add the `.im-dragging` class when this draggable is being dragged.
 * `data-skip-children="false"` - Dragging children of this element doesn't count.

#### Movement constraints

If you set a `data-constraint` or `data-constraint-elm` option (see above), these can be used to determine how far from the constraint areas the Draggable can move. Try them out:

 * `data-top="10"` - Always stay 10px away from the top.
 * `data-right="10"` - Always stay 10px away from the right.
 * `data-bottom="10"` - Always stay 10px away from the bottom.
 * `data-left="10"` - Always stay 10px away from the left.

### Advanced Draggable stuff:

You can visit [the Draggable API docs](/javascript/Ink.UI.Draggable/) to find out about Javascript-only options, javascript methods, and how to create Draggables using Javascript

-------------

    Drawer

Drawer is a component showing off-canvas menus which slide in when their toggle is clicked or touched. It's useful for saving precious screen real estate on devices with small screens.

It slides in from one of the sides, either pushing or going over (this is configurable) the page's content.

You need to place your entire page's content inside an element with the class `content-drawer`, so that it may be pushed aside.

### Drawer Examples

#### Basic example

This is a simple Drawer coming in from the left.

{% capture DrawerLeft %}

        Left drawer content...

        Open drawer

My page

            Content of my page...

{% endcapture %}

Demo

    {{ IframeHead }}
    {{ DrawerLeft }}

Code

{% highlight html %}
{{ DrawerLeft }}
{% endhighlight %}

#### Two drawers example

This is an example of two drawers, one coming from the right and one from the left.

{% capture DrawerBoth %}

        Left drawer content...

        Right drawer content...

        Open left drawer
        Open right drawer

My page

            Content of my page...

{% endcapture %}

Demo

    {{ IframeHead }}
    {{ DrawerBoth }}

Code

{% highlight html %}
{{ DrawerBoth }}
{% endhighlight %}

#### `'over'` mode

This drawer goes over the page content, instead of pushing it.

{% capture DrawerOver %}

Left drawer content...

I am over the main page content!

        Open drawer

My page

            Content of my page...

{% endcapture %}

Demo

    {{ IframeHead }}
    {{ DrawerOver }}

Code

{% highlight html %}
{{ DrawerOver }}
{% endhighlight %}

### Drawer options

 * `data-mode="over"` - Make the drawer go over the body instead of pushing it.
 * `data-sides="<side>"` - Make a drawer that comes in from this `side`. Can be 'left', 'right', or 'both'.
 * `data-content-drawer="#my-content-div"` - Your main page container.
 * `data-left-drawer=".my-left-drawer"` - Left drawer (the element that is placed offcanvas). This should be a sibling of your `data-content-drawer` element.
 * `data-left-trigger=".my-left-trigger"` - Left drawer trigger(s). When you click this trigger, the `leftDrawer` is shown.
 * `data-right-drawer=".my-right-drawer"` - Right drawer (the element that is placed offcanvas). This should be a sibling of your `data-content-drawer` element.
 * `data-right-trigger=".my-right-trigger"` - Right drawer trigger(s). When you click this trigger, the `rightDrawer` is shown.

### Advanced Drawer stuff:

You can visit [the Drawer API docs](/javascript/Ink.UI.Drawer/) to find out about Javascript-only options, javascript methods, and how to create Drawers using Javascript

-------------

    Dropdown

Dropdown is designed to add dropdown menus. They are a simplified version of Toggle, which is much more complex, and they work better with nested menus without a lot of the hassle which goes into creating them using Toggle.

It also includes some mouse-away logic, so as to avoid the dropdown being open forever if your mouse moves away from the dropdown. This is activated using `data-dismiss-after="<s>"` where `s` is your time in seconds which it is supposed to stay open.

### Dropdown Examples

#### Basic example

This is a simple Dropdown menu.

{% capture Dropdown %}

    <button class="ink-button">Dropdown</button>

I am a heading

Option

Option

Disabled option

{% endcapture %}

Demo

{{ Dropdown }}

Code

{% highlight html %}
{{ Dropdown }}
{% endhighlight %}

#### Dismiss automatically when mouse moves away.

By adding the `data-dismiss-after="<s>"` option, the Dropdown will go away automatically after `s` seconds pass.

Here we hide it after 2 seconds.

{% capture Dropdown %}

    <button class="ink-button">Dropdown</button>

Disabled option

{% endcapture %}

Demo

{{ Dropdown }}

Code

{% highlight html %}
{{ Dropdown }}
{% endhighlight %}

### Dropdown options

 * `data-target="#my-menu"` - Make `#my-menu` the `ul` which this Dropdown opens.
 * `data-hover-open="<seconds>"` - The number of seconds you need to hover with the mouse before the dropdown opens.
 * `data-dismiss-after="<seconds>"` - When the mouse moves away from the dropdown, wait for `seconds` seconds and then dismiss.
 * `data-dismiss-on-inside-click="true"` - Dismiss the dropdown when there's a click inside.
 * `data-dismiss-on-outside-click="false"` - Do not dismiss the dropdown when there's a click outside.

### Advanced Dropdown stuff:

You can visit [the Dropdown API docs](/javascript/Ink.UI.Dropdown/) to find out about Javascript-only options, javascript methods, and how to create Dropdowns using Javascript

-------------

    Droppable

The Droppable is a dropping area for [Draggable](#InkUIDraggable_1)s. It's useful to create shopping carts, playlists, and other things which rely on dragging and dropping action.

### Droppable Examples

#### Simple Droppables

Let's drag a couple of Draggables into a droppable!

{% capture Droppable %}

A droppable

A couple of draggables

Draggable 1

Draggable 2

Draggable 3

{% endcapture %}

Demo

{{ Droppable }}

Code

{% highlight html %}
{{ Droppable }}
{% endhighlight %}

#### Acceptance

You can choose what Draggables get dropped in your droppable! Here we see only green Draggables accepted in a Droppable.

{% capture Droppable %}

Drop only green things here:

A couple of draggables

Draggable 1

Draggable 2

Draggable 3

{% endcapture %}

Demo

{{ Droppable }}

Code

{% highlight html %}
{{ Droppable }}
{% endhighlight %}

### Droppable options

 * `data-hover-class="hoverin"` - Add the `.hoverin` class when a Draggable and hovering this droppable.
 * `data-accept=".only-these-draggables"` - Accept only elements with the class `.only-these-draggables`.

#### Drop behaviour options

These options can be further customized using javascript. Without javascript, though, there are already a few pre-made actions.

These actions are `"move"` and `"copy"`, which move or copy the draggable element into this draggable, or `"revert"`, which puts the draggable right back where it came from..

 * `data-on-drop="<move copy or revert>"` - When an element is dropped, move or copy it here, or revert it to where it came from.
 * `data-on-hover="<move copy or revert>"` - When an element is hovering the droppable, move or copy it here, or revert it to where it came from.
 * `data-on-drop-out="<move copy or revert>"` - When a Draggable is dropped outside of this droppable, move or copy it here, or revert it to where it came from.

### Advanced Droppable stuff:

You can visit [the Droppable API docs](/javascript/Ink.UI.Droppable/) to find out about Javascript-only options, javascript methods, and how to create Droppables using Javascript

-------------

    FormValidator_2

FormValidator is a component which validates forms interactively on the client side before any data is sent to the server. By doing this, it provides a less waiting time, and a better experience to the user.

To use FormValidator, add the `.ink-formvalidator` class to a `<form>` element. Ink won't let the user submit until the data is valid.

You will probably need to read the [Forms UI Element](https://ink.sapo.pt/ui-elements/forms/) documentation to get to grips with the classes used. TL;DR: `.ink-form` goes outside, `.control-group` is nestable and groups similar controls, and `.control` wraps the inputs.

### FormValidator_2 Examples

#### Basic example

Here is a simple example of a user registration field:

{% capture FormValidator_2 %}
<form class="ink-form ink-formvalidator" method="post" action="#">

        Name:

            <input type="text" data-rules="required|text[true,false]" name="name" id="name" />

        Email:

            <input type="text" name="e-mail" id="e-mail" data-rules="required|email" />

        Password:

            <input type="password" name="password" id="pass" data-rules="required|min_length[8]" />

        Confirm Password:

            <input type="password" name="confpass" id="confpass" data-rules="matches[password]" data-label="password confirmation" />

    <input type="submit" name="sub" value="Submit" class="ink-button success" />
</form>
{% endcapture %}

Demo

{{ FormValidator_2 }}

**Note: The `required` class is related to the [Form UI Element](https://ink.sapo.pt/ui-elements/forms/). it doesn't affect the FormValidator's behaviour.**

Code

{% highlight html %}
{{ FormValidator_2 }}
{% endhighlight %}

#### Required radio buttons and checkboxes

Here's how FormValidator deals with `<input type="radio">` and `<input type="checkbox">` inputs.

{% capture FormValidator_2 %}
<form class="ink-form ink-formvalidator column-group" method="post" action="#">

An offer you cannot refuse.

                    <input type="radio" name="accept-offer" id="accept-offer-id" value="1" data-rules="required" data-label="Accept Offer" />
                    Okay!

                    <input type="radio" name="accept-offer" id="refuse-offer-id" value="2" />
                    No, thanks.

Here's a box you must absolutely check.

                    <input type="checkbox" name="accept-tos" id="accept-tos-id" value="1" data-rules="required" data-label="Accept the TOS" />
                    I accept the Terms of Service of this website.

    <input type="submit" name="sub" value="Submit" class="ink-button success" />
</form>
{% endcapture %}

Demo

{{ FormValidator_2 }}

**Note: The `required` class is related to the [Form UI Element](https://ink.sapo.pt/ui-elements/forms/). it doesn't affect the FormValidator's behaviour.**

Code

{% highlight html %}
{{ FormValidator_2 }}
{% endhighlight %}

#### Custom error message strings

To issue a custom error message for that input, add a data-error attribute to the element

{% capture FormValidator_2 %}
<form class="ink-form ink-formvalidator column-group" method="post" action="#">

An offer you cannot refuse.

                    <input type="radio" name="accept-offer" id="accept-offer-2-id" value="1" data-rules="required" data-label="Accept Offer" data-error="You messing with me?" />
                    Okay!

                    <input type="radio" name="accept-offer" id="refuse-offer-2-id" value="2" />
                    No, thanks.

    <input type="submit" name="sub" value="Submit" class="ink-button success" />
</form>
{% endcapture %}

Demo

{{ FormValidator_2 }}

**Note: The `required` class is related to the [Form UI Element](https://ink.sapo.pt/ui-elements/forms/). it doesn't affect the FormValidator's behaviour.**

Code

{% highlight html %}
{{ FormValidator_2 }}
{% endhighlight %}

### FormValidator_2 options for the form

Put this in your `<form>` if you want to translate the form. Options to define the validation of each input are below.

 * `data-lang="pt_PT"` - Write error messages in portuguese. Languages available are `pt_PT` and `en_US` but others can be added through javascript.

### FormValidator_2 options for each input

After adding the `.ink-formvalidator` class to your FormValidator, add these data-attributes to your form inputs (input, select, textarea...) to configure how they are validated.

Each field (`<input>`, `<select>`, `<textarea>`, etc.) which you want to validate in your form needs to have "rules". These rules define what can go and what can't go on this element. Read more on them in "Validation rules", below.

 * `data-rules="Field name in human-readable form"` - Rules for this field. Read more in the "Validation rules" section, below.
 * `data-label="Field name text"` - The name of this field. It is used to show in error messages. By default the label is the `name` attribute of your field.

### Validation rules

This is what you put in `data-rules` for each element. Here are a few examples of what you can do:

 * `data-rules="required"` - Must be filled in.
 * `data-rules="alpha"` - Just alphabetic characters (A to Z), lower case or upper case.
 * `data-rules="alpha_numeric"` - Like `alpha` but accepts numbers too!
 * `data-rules="credit_card"` - A credit card number.
 * `data-rules="email"` - A valid e-mail.
 * `data-rules="range[0,10]"` - Numbers (not exactly integers) between 0 and 10.
 * `data-rules="numeric[.]"` - A numeric field, using the `.` as a decimal separator. (Ex: "1.5")
 * `data-rules="numeric[.,2]"` - A numeric field with at most 2 decimal places. ("1.23" is okay but "1.234" is not)
 * `data-rules="numeric[.,2,4]"` - A numeric field with at most 2 decimal places and at most 4 digits on the left. ("1234.56" is okay but "12345.6" and "1234.567" are not)
 * `data-rules="integer"` - Only whole numbers.

You can combine these rules, like this:

 * `data-rules="required|number"` - A required number.
 * `data-rules="required|email"` - A required email.
 * `data-rules="integer|range[0,10]"` - A whole number between 0 and 10.

Some assorted rules which are useful in combination with other rules:

 * `data-rules="min_length[4]"` - Must have at least 4 characters.
 * `data-rules="max_length[4]"` - Can't have more than 4 characters.
 * `data-rules="exact_length[4]"` - Must have exactly 4 characters.

Random rules you might need:

 * `data-rules="color"` - A color in `#hex`, `rgb()`, `rgba()`, `hsl()`, `hsla()` format.
 * `data-rules="date[<format>]"` - A date. `format` is a date format string in the syntax of [PHP's `date()` function](https://php.net/manual/en/function.date.php#refsect1-function.date-parameters)
 * `data-rules="decimal[...]"` - Exactly like `numeric` but only decimal numbers are allowed.
 * `data-rules="ip[ipv6]"` - An IP address.
 * `data-rules="ip[ipv4]"` - A legacy IP address.
 * `data-rules="phone[PT]"` - A Portuguese phone number.
 * `data-rules="phone[CV]"` - A Cape Verde phone number.
 * `data-rules="phone[AO]"` - An Angolan phone number.
 * `data-rules="phone[MZ]"` - A Mozambique phone number.
 * `data-rules="phone[TL]"` - A Timor phone number.
 * `data-rules="phone"` - Any of the above types of phone number.
 * `data-rules="url"` - A URL. (Ex: `"/foo/bar"`, `"https://example.com/foo/bar"`, etc.)
 * `data-rules="url[true]"` - Just like `url` but only if it contains the "https://" part.
 * `data-rules="ean"` - A barcode in [EAN-13 format](https://en.wikipedia.org/wiki/International_Article_Number_%28EAN%29).

You can see more validation rules, as well as a more in-depth description of each one of them, in [the JS documentation for `FormValidator.validationFunctions`](/javascript/Ink.UI.FormValidator.2/#Ink_UI_FormValidator_2-FormValidator_validationFunctions)

### Advanced FormValidator_2 stuff:

You can visit [the FormValidator_2 API docs](/javascript/Ink.UI.FormValidator.2/) to find out about Javascript-only options, javascript methods, and how to use FormValidator using Javascript.

-------------

    LazyLoad

LazyLoad delays the downloading of images, showing them only when they get to the viewport. This is useful in optimizing image-heavy websites.

You can use the more advanced [Javascript API](/javascript/Ink.UI.LazyLoad) to load things other than images, such as widgets, videos, active content, etc.

While the images are loading or offscreen, their appearance will be a simple, more lightweight, placeholder. You can define what this placeholder using the `data-placeholder` option of the LazyLoad, about which you can learn about below, in "LazyLoad options for the container".

A LazyLoad is comprised of a *container* element, which can be the `<body>` if you like, with the class `.ink-lazyload`, and *LazyLoad items*, with the class `.lazyload-item`, and with a `data-src` attribute instead of a `src` attribute.

It is recommended that you make sure, using CSS, that the images will take as much space after they loaded as before loading. In other words, reserve space for your images! This avoids weird scrolling issues.

### LazyLoad Examples

#### Load a few images

The images below will only load when you scroll

{% capture LazyLoad %}

{% endcapture %}

Demo

{{ LazyLoad }}

Code

{% highlight html %}
{{ LazyLoad }}
{% endhighlight %}

#### Add a CSS class to loaded images

When images are loaded, they will get a new CSS class and have a pretty fade-in!

{% capture LazyLoad %}

{% endcapture %}

Demo

{{ LazyLoad }}

Code

{% highlight html %}
{{ LazyLoad }}
{% endhighlight %}

### LazyLoad options for each lazily loaded item

 * `data-src="/my/image.png"` - The real source of the image, only loaded when the image is on screen.

### LazyLoad options for the container

 * `data-placeholder="/my-loading-spinner.gif"` - Placeholder value for items which are not 'visible', in case they don't already have a value set.
 * `data-loaded-class="loaded"` - Add the "loaded" class to the images when they're loaded.
 * `data-delta="100"` - Start loading the images 100px before they are on the screen.
 * `data-delta="-100"` - Start loading the images 100px *after* they are on the screen.
 * `data-delay="1000"` - Wait 1000 milliseconds (1 second) before showing the image.
 * `data-item=".my-crazy-selector"` - Find images by `.my-crazy-selector` instead of finding images with the `.lazyload-item` class.

### Advanced LazyLoad stuff:

You can visit [the LazyLoad API docs](/javascript/Ink.UI.LazyLoad/) to find out about Javascript-only options, javascript methods, and how to use LazyLoaders with Javascript. There's more advanced stuff that isn't covered here, like loading non-image elements with callbacks.

-------------

    Modal

The Modal component allows you to overlay something on the entire page, possibly an error message that refers to the whole page, or a follow-up form or dialog to a submission process.

It works by putting a shade element with `position:fixed` covering the entire viewport and avoiding accidental interaction with the rest of the page, and placing a modal element on the center of the screen using javascript.

It plays well with the `.ink-dismiss` class (the [Close](#Close) element). An element with the `ink-dismiss` class dismisses the modal that contains it.

### Modal Examples

#### Open a simple modal

Click the button to open a modal

{% capture Modal %}

This is the modal content

Open example modal
{% endcapture %}

Demo

{{ Modal }}

Code

{% highlight html %}
{{ Modal }}
{% endhighlight %}

#### A modal with a dismiss button, header, footer

Besides the content, this modal has a dismiss button, a header and a footer, besides the content.

{% capture Modal %}

            <button class="modal-close ink-dismiss"></button>

This is the modal header

This is the modal content

                <button class="ink-button caution ink-dismiss">Close</button>

Open example modal
{% endcapture %}

Demo

{{ Modal }}

Code

{% highlight html %}
{{ Modal }}
{% endhighlight %}

#### An automatically opened modal

To automatically open the modal, just omit the trigger!

{% capture Modal %}

This is the modal content

{% endcapture %}

Demo

    {{ IframeHead }}

        {{ Modal }}

Code

{% highlight html %}
{{ Modal }}
{% endhighlight %}

### Modal options

 * `data-trigger="#my-button"` - The modal will open when `#my-button` is clicked.
 * `data-width="600px"` - Make the modal 600px wide.
 * `data-height="400px"` - Make the modal 400px tall.
 * `data-width="40%"` - Make the modal width be 40% of the screen width.
 * `data-height="20%"` - Make the modal's height be 20% of the screen height.
 * `data-auto-display="true"` - Displays the Modal automatically when constructed.
 * `data-close-on-click="false"` - Don't close when the user clicks outside the modal.
 * `data-close-on-escape="false"` - Don't close the modal when ESC is pressed.
 * `data-responsive="false"` - Don't resize the modal when the screen is resized.

### Advanced Modal stuff:

You can visit [the Modal API docs](/javascript/Ink.UI.Modal/) to find out about Javascript-only options, javascript methods, and how to use Modals with Javascript and subscribe to their events.

-------------

    Pagination

You can use Pagination when you need interactive paginators. It does not
paginate anything by itself and must be connected to some other piece of
javascript to do anything useful. [Above](#InkUICarousel_1) you see it used
together with Carousel to change its pages.

It uses the CSS you see in the [Pagination UI Element (CSS)](/ui-elements/navigation/#pagination).
If you want a static pagination, just use that. If you really want a dynamic
pagination, read on.

### Pagination Examples

#### Simple pagination

Here we use the `data-size` option to tell Pagination how many pages it is paginating.

{% capture Pagination %}

{% endcapture %}

Demo

{{ Pagination }}

Code

{% highlight html %}
{{ Pagination }}
{% endhighlight %}

#### Lots of pages!

This example shows you how to deal with showing 100 pages without having all the numbers `1, 2, 3, 4... 100` written down.

This is effectively the Pagination paginating itself :)

{% capture Pagination %}

{% endcapture %}

Demo

{{ Pagination }}

Code

{% highlight html %}
{{ Pagination }}
{% endhighlight %}

### Pagination options

#### Page count

You can define the page count in two ways. One of them is just saying how many
pages you have. The other is by telling it how many items you have, and how many
items per page you need. Pagination will do the math for you in this case and
calculate the page count by itself.

Here is how you define the page count directly:

 * `data-size="<size>"` - Define the page count to be `size`, directly.

Here's how you tell Pagination to do the math for you:

 * `data-total-item-count="<item_count>"` - Tell Pagination you have `item_count` items (don't forget the below option too!).
 * `data-items-per-page="<per_page>"` - Tell Pagination you plan to display `per_page` items per page.

#### Options for dealing with large amounts of pages

 * `data-max-size="<max>"` - Show at most `max` numbers. This enables the "Next N", "Previous N" buttons.
 * `data-previous-page-class="<class>"` - Add `class` to the "previous N" button.
 * `data-next-page-class="<class>"` - Add `class` to the "next N" button.

#### Presentation options:

 * `data-first-label="<text>"` - Write `text` on the first page button instead of 'First'.
 * `data-last-label="<text>"` - Write `text` on the last page button instead of 'Last'.
 * `data-previous-label="<text>"` - Write `text` on the previous button instead of 'Previous'-
 * `data-next-label="<text>"` - Write `text` on the next button instead of 'Next'
 * `data-previous-page-label="<text>"` - Write `text` on the previous page button instead of 'Previous {Items per page}'.
 * `data-next-page-label="<text>"` - Write `text` on the next page button instead of 'Next {Items per page}'.
 * `data-pagination-class="<class>` - Class for the pagination element
 * `data-active-class="<class>` - Class that marks page as active (current page number)
 * `data-disabled-class="<class>` - Class that marks a page as disabled
 * `data-previous-class="<class>` - Class for the "previous" element
 * `data-next-class="<class>` - Class for the "next" elemnt
 * `data-hide-class="<class>` - Class which hides elements

#### Misc options:

 * `data-start="3"` - Start in page 3 instead of page 1.
 * `data-side-buttons="false"` - Hide the first, last, previous, next, "previous N" and "next N" buttons. Do not use together with `data-max-size`.
 * `data-auto-wrap="true"` - Navigate to first page when clicking "next" in the last page and vice-versa.
 * `data-parent-tag` - HTML Tag used as the parent node.
 * `data-child-tag` - HTML Tag used as the child nodes.

### Advanced Pagination stuff:

You can visit [the Pagination API docs](/javascript/Ink.UI.Pagination/) to find out about Javascript-only options, javascript methods, and how to use Paginations with Javascript and subscribe to their events.

-------------

    ProgressBar

A ProgressBar can be used to indicate progress in a certain process.

### ProgressBar Example

This is a progress bar. The process is well under way, it seems, at 70%.

{% capture ProgressBar %}

    I am a grey progress bar

{% endcapture %}

Demo

{{ ProgressBar }}

Code

{% highlight html %}
{{ ProgressBar }}
{% endhighlight %}

### ProgressBar options

Use this vast array of options to customize your ProgressBar:

 * `data-start-value="20"` - Start at 20% instead of 0%.

You can also use some color classes (instead of `grey`) to color your progress bar.

### Advanced ProgressBar stuff:

You can visit [the ProgressBar API docs](/javascript/Ink.UI.ProgressBar/) to learn how to create ProgressBars with javascript and manipulate them in real time.

-------------

    SmoothScroller

SmoothScroller is a component for

### SmoothScroller Examples

#### Basic usage

This shows you how to set a couple of anchor links which, when clicked, scroll smoothly up to their destination. Here are two links and sections:

{% capture SmoothScroller %}

    Scroll to "Part 1"
    Scroll to "Part 2"

[lots and lots of content...]

...

Part 1

Part 1 content

Part 2

Part 2 content

{% endcapture %}

Demo

{{ SmoothScroller }}

Code

{% highlight html %}
{{ SmoothScroller }}
{% endhighlight %}

#### Leaving a margin

This example shows the use of `data-margin` to scroll up to 200px above the target.

The `data-margin` option is very useful if you have a `position:fixed` menu or top bar on the top of your page. Using it avoids hiding important content behind that bar.

{% capture SmoothScroller %}

    Scroll to 200px above "something"!

[lots and lots of content...]

...

I am something!

{% endcapture %}

Demo

{{ SmoothScroller }}

Code

{% highlight html %}
{{ SmoothScroller }}
{% endhighlight %}

#### Scrolling really fast

Here is how you use `data-speed` to scroll really fast. It defaults to `"10"`. Smaller is faster, larger is slower.

{% capture SmoothScroller %}

        Scroll really fast to "Thing 1"

        Scroll really fast to "Thing 2"

[lots and lots of content...]

...

Thing 1

Thing 1 fast!

Thing 2

Thing 2 fast!

{% endcapture %}

Demo

{{ SmoothScroller }}

Code

{% highlight html %}
{{ SmoothScroller }}
{% endhighlight %}

### SmoothScroller options

When a link is clicked, it is checked for several things:

 * `href="#my-item-id"` - Scroll up to the element with ID `my-item-id`. Only works with IDs, just like regular anchor links.
 * `data-margin="42"` - When scrolling, leave a 42px margin above the target. Useful if you have a 42px-tall `position:fixed` top bar.
 * `data-speed="5"` - Scroll faster.
 * `data-speed="20"` - Scroll slower.
 * `data-change-hash="false"` - Don't change the URL hash (`#hash`), just scroll there.

### Advanced SmoothScroller stuff:

You can visit [the SmoothScroller API docs](/javascript/Ink.UI.SmoothScroller/) to find out about Javascript-only options, javascript methods, and how to use SmoothScrollers with Javascript and subscribe to their events.

-------------

    SortableList

SortableList turns a list into a list which can be sorted by the user using the
mouse. It does not currently work with touch events.

A handle can be selected, in which case the user will only be able to drag the
list items by that handle (something like a "drag here" icon). SortableList can also be used to sort non-list
elements.

### SortableList Examples

#### Simple sorting

Let's sort a few items:

{% capture SortableList %}

First

Second

Third

{% endcapture %}

Demo

{{ SortableList }}

Code

{% highlight html %}
{{ SortableList }}
{% endhighlight %}

#### Styling the dragged item

While you're dragging, the dragged item gets the "placeholder" CSS class,
enabling you to style it as you like.

{% capture SortableList %}

First

Second

Third

{% endcapture %}

Demo

{{ SortableList }}

Code

{% highlight html %}
{{ SortableList }}
{% endhighlight %}

#### Styling something else

SortableList will also add the `drag` class to the `<html>` element while
you sort things. You can change it to another class using `data-dragging-class`.

{% capture SortableList %}

First

Second

Third

     Hey! I see you're dragging things! Welcome to Ink!

{% endcapture %}

Demo

{{ SortableList }}

Code

{% highlight html %}
{{ SortableList }}
{% endhighlight %}

#### Sorting by a handle

In this example, you can only drag by the "bars" icon to the left of each word.

{% capture SortableList %}

 First

 Second

 Third

{% endcapture %}

Demo

{{ SortableList }}

Code

{% highlight html %}
{{ SortableList }}
{% endhighlight %}

#### Sorting non-list elements

Here's a sortable table. Notice that we use `data-drag-selector="tbody tr"`, to
tell SortableList what is being sorted is the rows inside the `<tbody>` element.

{% capture SortableList %}

            Name
            Number

First	1

Second	2

Third	3

{% endcapture %}

Demo

{{ SortableList }}

Code

{% highlight html %}
{{ SortableList }}
{% endhighlight %}

#### Sorting a grid of things instead of a list of things

Below you can see two sortable grids, just to show off two ways of sorting items.

When "swap mode" is active, the sorting makes more sense in grids, although it changes the list around a lot.

{% capture SortableList %}

List mode:

First

Second

Third

Fourth

Swap mode:

First

Second

Third

Fourth

{% endcapture %}

Demo

{{ SortableList }}

Code

{% highlight html %}
{{ SortableList }}
{% endhighlight %}

### SortableList options

These options help you configure SortableList. Most of them have a working example above.

 * `data-placeholder-class="my-placeholder"` - Add the `my-placeholder` class to the dragged placeholder. By default the `placeholder` class is added.
 * `data-dragging-class="html-element-with-things-being-dragged"` - Add this class to the `<html>` element when something is dragged. By default, the `dragging` class is added.
 * `data-drag-selector=".my-dragged-items"` - Sort `.my-dragged-items` instead of `li` elements. You see this in use above in "Sorting non-list elements".
 * `data-handle-selector=".handle"` - Drag nodes by a handle, marked by the `.handle` class. This handle must be inside the dragged node.
 * `data-swap="true"` - Instead of reordering items, swap them. Makes a lot of sense when sorting grids, but does nothing in simple lists.
 * `data-cancel-mouse-out="true"` - Stop dragging if the mouse leaves the container.

### Advanced SortableList stuff:

You can visit [the SortableList API docs](/javascript/Ink.UI.SortableList/) to find out about Javascript-only options, javascript methods, and how to use SortableLists with Javascript.

-------------

    Spy

Spy is a simple way to help the user keep track of where they are when scrolling
your page.

As a user scrolls down the page and changes to new sections (they may be actual
`<section>` elements or whatever you like), Spy will highlight the corresponding
link on your menu. This is useful when your menu has `position:fixed` and has a
bunch of anchor links to several parts of the page.

Your menu must have all links inside `li` tags. These will get the `.active`
class. You then style the `.active` class as you like.

### Spy Examples

#### Basic example

A bunch of sections

{% capture Spy %}

Water

Bones

Pilot

Water

            You think water moves fast? You should see ice. It moves like it has a mind. Like it knows it killed the world once and got a taste for murder. After the avalanche, it took us a week to climb out. Now, I don't know exactly when we turned on each other, but I know that seven of us survived the slide... and only five made it out.

Now we took an oath, that I'm breaking now. We said we'd say it was the snow that killed the other two, but it wasn't. Nature is lethal but it doesn't hold a candle to man.

Bones

            Your bones don't break, mine do. That's clear. Your cells react to bacteria and viruses differently than mine. You don't get sick, I do. That's also clear. But for some reason, you and I react the exact same way to water. We swallow it too fast, we choke. We get some in our lungs, we drown. However unreal it may seem, we are connected, you and I. We're on the same curve, just on opposite ends.

Pilot

            Well, the way they make shows is, they make one show. That show's called a pilot. Then they show that show to the people who make shows, and on the strength of that one show they decide if they're going to make more shows. Some pilots get picked and become television programs. Some don't, become nothing. She starred in one of the ones that became nothing.

...

...

{% endcapture %}

Demo

    {{ IframeHead }}

        {{ Spy }}

Code

{% highlight html %}
{{ Spy }}
{% endhighlight %}

### Spy options

There's only one option to Spy.

 * `data-target="#the-target"` - Make `#the-target` the spy target.

### Advanced Spy stuff:

You can visit [the Spy API docs](/javascript/Ink.UI.Spy/) to find out about Javascript-only options, javascript methods, and how to create Spies using Javascript

-------------

    Stacker

Stacker will reorganize N columns when the screen is not wide enough to show them all. It will mash together the contents of the 3 columns

It does so to avoid the problem of the elements' unknown height

### Stacker Examples

#### 3 feeds example

This example re-stacks 3 feeds of data in the large viewport into a single column in the small viewport. Resize your viewport and watch the items get mashed together.

{% capture Stacker %}

A - 1

A - 2

A - 3

B - 1

B - 2

B - 3

C - 1

C - 2

C - 3

{% endcapture %}

Demo

{{ Stacker }}

Code

{% highlight html %}
{{ Stacker }}
{% endhighlight %}

#### Items with multiple heights

This example shows off Stacker's capacity to deal with multiple height items even as the screen width forces it to reduce the amount of columns.  This defaults to `.stacker-item`.
 * `data-column=".my-stacker-columns"` - If for some reason you don't want to use the `stacker-column` class to identify your stacker columns, you can use this option to change it.
 * `data-is-ordered="false"` - Don't reorder the stacks when resizing.

### Advanced Stacker stuff:

You can visit [the Stacker API docs](/javascript/Ink.UI.Stacker/) to find out about Javascript-only options, javascript methods, and how to create Stackers using Javascript

-------------

    Sticky

### Sticky Examples

#### Simple sticky

Here is sticky's default behavior. No options, sticking an alert to the top of the screen.

{% capture Sticky %}

Welcome to my website

Hey I stick to the top when you scroll!

Content goes here...

Content goes here...

Content goes here...

Content goes here...

Content goes here...

Content goes here...

{% endcapture %}

Demo

    {{ IframeHead }}
    {{ Sticky }}

Code

{% highlight html %}
{{ Sticky }}
{% endhighlight %}

#### Styling the sticky different when it's "stuck"

When a sticky is stuck to the top of the screen, it gets the `.ink-sticky-stuck` class. You can use that to style your sticky differently when it's stuck!

{% capture Sticky %}

Welcome to my website

Hey I turn red when you scroll!

Content goes here...

Content goes here...

Content goes here...

Content goes here...

Content goes here...

Content goes here...

{% endcapture %}

Demo

    {{ IframeHead }}
    {{ Sticky }}

Code

{% highlight html %}
{{ Sticky }}
{% endhighlight %}

#### data-bottom-element tells Sticky to avoid going below a certain element

This option is very useful for large footers, which don't play well with sticky elements hovering on top of them.

It also works well when the Sticky only refers to a section and you wouldn't want it flying off of it because that would be confusing.

Just add `data-bottom-element="#bottom-element` and Sticky will avoid going below that element.

{% capture Sticky %}

Hey I can stick to the top!

Content goes here...

Content goes here...

Sticky stops here

Content goes here...

Content goes here...

Content goes here...

{% endcapture %}

Demo

    {{ IframeHead }}
    {{ Sticky }}

Code

{% highlight html %}
{{ Sticky }}
{% endhighlight %}

### Sticky options

 * `data-top-element="#top-element"` - Don't let the sticky go above or run into this element.
 * `data-bottom-element="#bottom-element"` -  Don't let the sticky go below or run into this element.
 * `data-offset-top="20px"` - Instead of sticking right to the top of the screen, keep a margin of 20px. This is very, very useful, if you already have a `position:fixed` top bar on your page.
 * `data-offset-bottom="10px"` - Like `data-offset-top`, but for the bottom. Avoids the sticky sticking right to the bottom of the screen.
 * `data-inline-dimensions="false"` - Tell sticky to not mess with your element's `style` to set dimensions. You may want to do this because you want to set the dimensions yourself in your CSS for `.ink-sticky` or `.ink-sticky-stuck`.
 * `data-inline-position="false"` - Tell sticky to not mess with your element's `style` to set position. You may want to do this because you want to set the position yourself in your CSS for `.ink-sticky` or `.ink-sticky-stuck`.
 * `data-wrapper-class="my-wrapper"` - Add this class to the sticky wrapper (the DIV that stands in place for the element when it is put in `position:fixed`).
 * `data-sticky-class="i-am-stuck"` - Add this class to the sticky when it's stuck (`position:fixed`) on the top or bottom of the screen.

### Advanced Sticky stuff:

You can visit [the Sticky API docs](/javascript/Ink.UI.Sticky/) to find out about Javascript-only options, javascript methods, and how to create Stickies using Javascript

-------------

    Tabs

The Tabs Component offers a simple way to build a tab-separated layout, allowing you to offer multiple content panes in the same space with intuitive navigation. This component requires your markup to have:

 * A container element with everything below:
     * An element with the `.tabs-nav` class, containing links with the `[href]` attribute set to the ID of the section they point at. Like regular in-document anchor links.
     * Your section elements with the corresponding id attributes and the `.tabs-content` class.

### Tabs examples

#### Simple Tabs

A simple Tabs component, with tabs on top and two sections.

{% capture Tabs %}

Home

News

Home

            A home is a dwelling-place used as a permanent or semi-permanent residence for an individual, family, household or several families in a tribe. It is often a house, apartment, or other building, or alternatively a mobile home, houseboat, yurt or any other portable shelter. Larger groups may live in a nursing home, children's home, convent or any similar institution. A homestead also includes agricultural land and facilities for domesticated animals. Where more secure dwellings are not available, people may live in the informal and sometimes illegal shacks found in slums and shanty towns. More generally, "home" may be considered to be a geographic area, such as a town, village, suburb, city, or country

News

            News is the communication of selected[1] information on current events. It is shared in various ways: among individuals and small groups (such as by word of mouth or newsletters); with wider audiences (such as by publishing, either in print or online, or broadcasting, such as on television or radio); or in ways that blend those traits (such as when social media sharing starts among individuals but goes viral).

{% endcapture %}

Demo

{{ Tabs }}

Code

{% highlight html %}
{{ Tabs }}
{% endhighlight %}

#### Tabs on the left

This example shows you how to change the position of the tabs to have them hanging from the left by adding the `.left` class to the `.ink-tabs` element. You can also use `"top"` (shown above), `"bottom"`, or `"right"`.

{% capture Tabs %}

Home

News

Home2

            A home2 is a dwelling-place used as a permanent or semi-permanent residence for an individual, family, household or several families in a tribe. It is often a house, apartment, or other building, or alternatively a mobile home2, houseboat, yurt or any other portable shelter. Larger groups may live in a nursing home2, children's home2, convent or any similar institution. A home2stead also includes agricultural land and facilities for domesticated animals. Where more secure dwellings are not available, people may live in the informal and sometimes illegal shacks found in slums and shanty towns. More generally, "home2" may be considered to be a geographic area, such as a town, village, suburb, city, or country

News2

            News is the communication of selected[1] information on current events. It is shared in various ways: among individuals and small groups (such as by word of mouth or news2letters); with wider audiences (such as by publishing, either in print or online, or broadcasting, such as on television or radio); or in ways that blend those traits (such as when social media sharing starts among individuals but goes viral).

{% endcapture %}

Demo

{{ Tabs }}

Code

{% highlight html %}
{{ Tabs }}
{% endhighlight %}

#### Style the active tab differently

The `li` containing the tab gets the `.active` class when it is active. You can use that as a CSS hook to style the active tab differently. `.tabs-content` also gets the `.active` class when it's active.

{% capture Tabs %}

Home

News

Home2

            A home3 is a dwelling-place used as a permanent or semi-permanent residence for an individual, family, household or several families in a tribe. It is often a house, apartment, or other building, or alternatively a mobile home3, houseboat, yurt or any other portable shelter. Larger groups may live in a nursing home3, children's home3, convent or any similar institution. A home3stead also includes agricultural land and facilities for domesticated animals. Where more secure dwellings are not available, people may live in the informal and sometimes illegal shacks found in slums and shanty towns. More generally, "home3" may be considered to be a geographic area, such as a town, village, suburb, city, or country

News2

            News is the communication of selected[1] information on current events. It is shared in various ways: among individuals and small groups (such as by word of mouth or news2letters); with wider audiences (such as by publishing, either in print or online, or broadcasting, such as on television or radio); or in ways that blend those traits (such as when social media sharing starts among individuals but goes viral).

{% endcapture %}

Demo

{{ Tabs }}

Code

{% highlight html %}
{{ Tabs }}
{% endhighlight %}

### Tabs options

 * `data-prevent-url-change="true"` - Don't change the URL `#hash` when a tab is clicked.
 * `data-active="my-tab"` - Activate the tab with `id="my-tab"` by default. Otherwise, it will be whatever is on the URL `#hash`, or the first tab in the `ul`.
 * `data-menu-selector=".my-tabs-nav"` - Your tab links. Use this if you don't want to use the `.tabs-nav` class.
 * `data-content-selector=".my-tabs-content"` - Your tab content panes. Use this if you don't want to use the `.tabs-content` class.

### Advanced Tabs stuff:

You can visit [the Tabs API docs](/javascript/Ink.UI.Tabs/) to find out about Javascript-only options, javascript methods, and how to create Tabs using Javascript

-------------

    Toggle

Toggle is a component for showing and hiding things. It can be made to do far more.

Since "showing" and "hiding" is just adding and removing classes, by changing the added and removed classes, you can achieve a lot with styling hooks.

A Toggle can also coordinate with other sibling toggles and create an accordion using `data-is-accordion="true"`.

### Toggle examples

#### Simple Toggle

{% capture Toggle %}
<button class="ink-toggle ink-button" data-target="#myAlert">See more</button>

This is a details section

Insert awesome text here

{% endcapture %}

Demo

{{ Toggle }}

Code

{% highlight html %}
{{ Toggle }}
{% endhighlight %}

#### Styling hooks for the toggle target

By using the `data-class-name-on` and `data-class-name-off` options you can customize what classes get added and removed from your toggle targets. Here's how you choose between two classes on an element.

{% capture Toggle %}
<button class="ink-toggle ink-button" data-target="#myAlert2"
    data-class-name-on="info"
    data-class-name-off="error">Info or error?</button>

This is a details section

Insert awesome text here

{% endcapture %}

Demo

{{ Toggle }}

Code

{% highlight html %}
{{ Toggle }}
{% endhighlight %}

#### Styling hooks for the toggle itself

We can also style our button according to toggle state. Toggle will add the `.active` class to the toggle element, in this case the `button`.

{% capture Toggle %}
<button class="ink-toggle ink-button style-button-example" data-target="#myAlert3">Toggle something</button>

This is a details section

Insert awesome text here

{% endcapture %}

Demo

{{ Toggle }}

Code

{% highlight html %}
{{ Toggle }}
{% endhighlight %}

#### Multiple targets

Toggle is capable of toggling many targets. It will toggle everything you select in `data-target`.

{% capture Toggle %}
<button class="ink-toggle ink-button" data-target=".multitarget-example">Toggle something</button>

This is a details section

Insert awesome text here

This is a details section

Insert awesome text here

This is a details section

Insert awesome text here

This is a details section

Insert awesome text here

{% endcapture %}

Demo

{{ Toggle }}

Code

{% highlight html %}
{{ Toggle }}
{% endhighlight %}

#### Accordion

You can use Toggle to achieve an accordion! Just add the `data-is-accordion="true"` option to all accordion parts, and make sure they're direct children of a div with the class `.accordion`.

{% capture Toggle %}

        See more 1

Section 1

        See more 2

Section 2

        See more 3

Section 3

        See more 4

Section 4

{% endcapture %}

Demo

{{ Toggle }}

Code

{% highlight html %}
{{ Toggle }}
{% endhighlight %}

#### An Accordion inside an Accordion

Here's how you put an accordion inside an accordion.

Just make sure to add the div with the class `.accordion` and place the inner accordion inside that. It should work well :)

{% capture Toggle %}

        See more 1

Section 1

        See more 2

Section 2

        See more 3

Section 3

                See more 4

Section 4

                See more 5

Section 5

{% endcapture %}

Demo

{{ Toggle }}

Code

{% highlight html %}
{{ Toggle }}
{% endhighlight %}

### Toggle options

 * `data-is-accordion="true"`            - This toggle is a part of an accordion. Make sure it is the direct child of an element with the class `.accordion`. Otherwise, Ink will warn you about this on the console.
 * `data-class-name-on="my-on-class"`    - Add the `.my-on-class` class when the toggle is ON. Use this for styling hooks.
 * `data-class-name-off="my-off-class"`   - Add the `.my-off-class` class when the toggle is OFF. Use this for styling hooks.
 * `data-close-on-click="false"`         - Don't toggle OFF when clicking outside.
 * `data-can-toggle-an-ancestor="true"`  - Use this if you wish to toggle nodes which are ancestors of this node (for instance `<div class="ancestor"><yourtoggleelement/></div>`.
 * `data-close-on-inside-click=".some-class"`   - Toggle off when a child element with the class `.some-class` is clicked. By default toggle will toggle itself off when a link is clicked.
 * `data-initial-state="true"`          - Toggle is ON initially.
 * `data-initial-state="false"`         - Toggle is OFF initially.

### Advanced Toggle stuff:

You can visit [the Toggle API docs](/javascript/Ink.UI.Toggle/) to find out about Javascript-only options, javascript methods, and how to create Toggles using Javascript

-------------

    Tooltip

### Tooltip examples

#### Simple Tooltip

Hover these labels:

{% capture Tooltip %}

    New

    Quit

    Save

{% endcapture %}

Demo

{{ Tooltip }}

Code

{% highlight html %}
{{ Tooltip }}
{% endhighlight %}

#### Tooltip with arbitrary HTML inside.

You can set the tooltip's inner HTML by using `data-tip-html="(my html)"`.

{% capture Tooltip %}

    Hover me

{% endcapture %}

Demo

{{ Tooltip }}

Code

{% highlight html %}
{{ Tooltip }}
{% endhighlight %}

# Change the default Tooltip template

You can replace the tooltip structure (the rounded rectangle with the triangle arrow) entirely by using `data-tip-template="#my-template-id"` and `data-tip-templatefield=".write-tip-text-here"`.

{% capture Tooltip %}

    hover me

A random tooltip template

< tooltip text goes here :) >

{% endcapture %}

Demo

{{ Tooltip }}

Code

{% highlight html %}
{{ Tooltip }}
{% endhighlight %}

#### Tooltip sides

Hover these labels:

{% capture Tooltip %}

    Using data-tip-where="up" (default)

    Using data-tip-where="down"

    Using data-tip-where="left"

    Using data-tip-where="right"

    Using data-tip-where="mousemove"

    Using data-tip-where="mousefix"

{% endcapture %}

Demo

{{ Tooltip }}

Code

{% highlight html %}
{{ Tooltip }}
{% endhighlight %}

### Tooltip options

 * `data-tip-text="<tooltip text!>"` - Text content for the tooltip.
 * `data-tip-html="<tooltip inner HTML>"` - HTML for the tooltip. Use this instead of `data-tip-text` when you need to add arbitrary HTML instead of just text.
 * `data-tip-where="down"` - Make the tooltip appear below the element instead of above. You can also use `'left'` or `'right'`. See below to find out how to place the tooltip relative to the mouse.
 * `data-tip-color="red"` - Make the tooltip be red! The tooltip can be colored `red`, `orange`, `blue`, `green` and `black`. Default is `white`.
 * `data-tip-fade="0.5"` - Take 0.5s to fade in and out.
 * `data-tip-forever="true"` - Make the tooltip not disappear even if the mouse goes away. If FOREVER is too long to wait use `data-tip-timeout` to set a time to live.
 * `data-tip-timeout="10"` - The tooltip will stay open for 10 seconds. Useful with `data-tip-forever="true"`, and it won't
 * `data-tip-delay="1.1"` - Wait 1.1s before showing the tooltip. Useful to avoid getting the attention of the user unnecessarily.
 * `data-tip-template="#my-template"` - An element to use as the tooltip template instead of the default rectangle and arrow. See above for an example.
 * `data-tip-templatefield=".write-text-here"` - When using `data-tip-template`, tell Tooltip to write the text in the `.write-text-here` element.

#### Positioning the tooltip relative to the mouse

Positioning relative to the mouse is easy and requires only one of these options:

 * `data-tip-where="mousemove"` - Tooltip follows the mouse.
 * `data-tip-where="mousefix"` - Tooltip stays in place where the mouse first touched the element.

When the tooltip is positioned relative to the mouse, these two allow you to tweak how far from the mouse they are.

 * `data-tip-left="20"` - place the tooltip 20px to the right of the mouse.
 * `data-tip-top="20"` - place the tooltip 20px below the mouse.

### Advanced Tooltip stuff:

You can visit [the Tooltip API docs](/javascript/Ink.UI.Tooltip/) to find out about Javascript-only options, javascript methods, and how to create Tooltips using Javascript

-------------

    TreeView

Shows elements in a tree view whose nodes can be expanded and contracted.

A TreeView consists of "nodes" and "children", which are elements which have child nodes.

### TreeView examples

#### Simple TreeView

{% capture TreeView %}

        root

child 1

                child 2

grandchild 2a

                        grandchild 2b

grandgrandchild 1bA

grandgrandchild 1bB

child 3

{% endcapture %}

Demo

{{ TreeView }}

Code

{% highlight html %}
{{ TreeView }}
{% endhighlight %}

### TreeView options

 * `data-node=".node"` - Make tree nodes be elements with the `.node` class instead of any `li` element.
 * `data-children=".cont"` - Make the children containers be elements with the `.cont` class.
 * `data-parent-class="i-am-parent"` - Add the `.i-am-parent` class to nodes which have children.
 * `data-open-class="fa fa-check-circle"` - Add the `.fa-check-circle`, `.fa` classes to the icon when nodes are open. Use this to override the default icons.
 * `data-closed-class="fa-circle"` - Add the `.fa-circle`, `.fa` classes to the icon when nodes are closed. Use this to override the default icons.
 * `data-hide-class="invisible"` - Add the `.invisible` class to "children" elements to when they are hidden. Defaults to `hide-all`.
 * `data-icon-tag="span"` - Use a `span` instead of an `i` for the icon.

### Advanced TreeView stuff:

You can visit [the TreeView API docs](/javascript/Ink.UI.TreeView/) to find out about Javascript-only options, javascript methods, and how to create TreeViews using Javascript

repository: sapo/Ink-doc

branch_name: refs/heads/gh-pages

repo_name: sapo/Ink-doc


text:
## Ruler :straight_ruler: :school:

# Project 2 Team: Rika, Maggie Jo, Dan, Bohdan

### Application Usage
Application designed for teachers and parents to keep track of the daily activities of their students/kids. Teachers can make custom comments about the students so that the parent can view later. Parent will be able to track comments, view activities, check calendar for events, and download required forms like permission slips.

### Technologies Used
- Node.js
- Bcrypt
- Handlebars
- FullCalendar
- Sequelize
- Semantic UI(to assist with FullCalendar, not using full features)
- Materialize
- MySQL

## How It Works

First page you will see is the log in page. If you already have an account please enter your information. After you log in, the system will know to consider you either a parent or a teacher and display the appropriate dashboard.

If you do not have an account, please set up an account as a teacher. After logging in as a teacher, you can then add a parent to the system once you add a student to your class.

![alt text](public/images/regularlogin.png "Main Login Image")

![alt text](public/images/teachersetup.png "Teacher Setup Account")

![alt text](public/images/parentsetup.png "Parent Setup Account")

After adding a student and a parent, the parent will then be able to update their information with their email address and a password in order to log in to view their dashboard for their kids.

#Add a Student and Parent
A teacher will add a student and a parent from this page. An existing parent can also be selected from the drop down if a new account set up is not needed.

![alt text](public/images/addstudent.png "Add Student and Parent")

Teacher will leave comments for students from this screen.
![alt text](public/images/commentstudent.png "Leave Student Comment")

## Dashboard :clipboard:
A teacher can view all of the posts from their dashboard. The teacher will also find the buttons to add a student or leave a comment on the same page.

![alt text](public/images/teacherdashboard.png "Leave Student Comment")

A parent can view posts on their dashboard as well. A parent will only see posts assigned to them and their kids.

![alt text](public/images/parentdashboard.png "Leave Student Comment")

## Calendar :calendar:
A teacher and parent can view the calendar of events and activities added for the summer. They can view it as a monthly calendar, weekly, or daily. Some events can open directly to a webpage for more information. Events can also be dragged and dropped to different dates if needed to update.

![alt text](public/images/calendar.png "View of Calendar")

### The Future
## Teacher
- Can create custom events to post to be Calendar
- Will be able to send permission slips to parents
- Add report card information
- Update activities page and add school bulletins
- Give ratings of :blush: and :star: based on comments
- Post videos and photos of class activities

## Parent
- Respond to a post by a teacher or send general message
- View updates on the school bulletin
- Download school statements and permission slips

### :tada: Thank you ENJOY!! :school_satchel: :school:

license: MIT

branch_name: refs/heads/master

extension: md

gha_language: JavaScript

license_type: permissive


text:
# SSCR-Julia
This is the Julia language implementation of the EMNLP'20 paper SSCR: Iterative Language-Based Image Editing via Self-Supervised Counterfactual Reasoning

```
@inproceedings{fu2020sscr,
  author = {Tsu-Jui Fu and Xin Eric Wang and Scott Grafton and Miguel Eckstein and William Yang Wang},
  title = {SSCR: Iterative Language-Based Image Editing via Self-Supervised Counterfactual Reasoning},
  booktitle = {Conference on Empirical Methods in Natural Language Processing (EMNLP)},
  year = {2020}
}
```

branch_name: refs/heads/main

gha_license_id: MIT


text:
# similar
compare the similarity of two string

Example:
```javascript
var str1 = 'Continuous Integration Your Hexo Blog With Travis CI';
var str2 = 'Continuous Integration Your Hexo Blog With Travis';
var similar = require('./index.js');
similar(str1, str2); // return 77.77, range 0-100(exactly the same)
```

repository: ruanyl/similar

repo_name: ruanyl/similar


text:
Phan is a static analyzer for PHP that prefers to minimize false-positives. Phan attempts to prove incorrectness rather than correctness.

Phan looks for common issues and will verify type compatibility on various operations when type
information is available or can be deduced. Phan has a good (but not comprehensive) understanding of flow control
and does not attempt to track values.

[![Maintainability](https://api.codeclimate.com/v1/badges/3940135c0dfbd5387c94/maintainability)](https://codeclimate.com/github/phan/phan/maintainability) [![Build Status](https://travis-ci.org/phan/phan.svg?branch=master)](https://travis-ci.org/phan/phan) [![Build Status (Windows)](https://ci.appveyor.com/api/projects/status/github/phan/phan?branch=master&svg=true)](https://ci.appveyor.com/project/TysonAndre/phan/branch/master)
[![Gitter](https://badges.gitter.im/phan/phan.svg)](https://gitter.im/phan/phan?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
[![Latest Stable Version](https://img.shields.io/packagist/v/phan/phan.svg)](https://packagist.org/packages/phan/phan)
[![License](https://img.shields.io/packagist/l/phan/phan.svg)](https://github.com/phan/phan/blob/master/LICENSE)

# Getting Started

The easiest way to use Phan is via Composer.

```
composer require phan/phan
```

With Phan installed, you'll want to [create a `.phan/config.php` file](https://github.com/phan/phan/wiki/Getting-Started#creating-a-config-file) in
your project to tell Phan how to analyze your source code. Once configured, you can run it via `./vendor/bin/phan`.

This version (branch) of Phan depends on PHP 7.x with the [php-ast](https://github.com/nikic/php-ast) extension (0.1.5 or newer, uses AST version 50) and supports PHP version 7.0-7.2 syntax.
The master branch is the basis for the 1.x.y releases.
Installation instructions for php-ast can be found [here](https://github.com/nikic/php-ast#installation).
Having PHP's `pcntl` extension installed is strongly recommended (not available on Windows), in order to support using parallel processes for analysis
(`pcntl` is recommended for daemon mode and LSP to work efficiently, but both should work without that extension).

* **Alternative Installation Methods**

  See [Getting Started](https://github.com/phan/phan/wiki/Getting-Started) for alternative methods of using
Phan and details on how to configure Phan for your project.

* **Incrementally Strengthening Analysis**

  Take a look at [Incrementally Strengthening Analysis](https://github.com/phan/phan/wiki/Incrementally-Strengthening-Analysis) for some tips on how to slowly ramp up the strictness of the analysis as your code becomes better equipped to be analyzed.

* **Installing Dependencies**

  Take a look at [Installing Phan Dependencies](https://github.com/phan/phan/wiki/Getting-Started#installing-phan-dependencies) for help getting Phan's dependencies installed on your system.

# Features

Phan is able to perform the following kinds of analysis.

* Check that all methods, functions, classes, traits, interfaces, constants, properties and variables are defined and accessible.
* Check for type safety and arity issues on method/function/closure calls.
* Check for PHP7/PHP5 backward compatibility.
* Check for features that weren't supported in older PHP 7.x minor releases (E.g. `object`, `void`, `iterable`, `?T`, `[$x] = ...;`, negative string offsets, multiple exception catches, etc.)
* Check for sanity with array accesses.
* Check for type safety on binary operations.
* Check for valid and type safe return values on methods, functions, and closures.
* Check for No-Ops on arrays, closures, constants, properties, variables, unary operators, and binary operators.
* Check for unused/dead/[unreachable](https://github.com/phan/phan/tree/master/.phan/plugins#unreachablecodepluginphp) code. (Pass in `--dead-code-detection`)
* Check for unused variables and parameters. (Pass in `--unused-variable-detection`)
* Check for unused `use` statements.
* Check for classes, functions and methods being redefined.
* Check for sanity with class inheritance (e.g. checks method signature compatibility).
  Phan also checks for final classes/methods being overridden, that abstract methods are implemented, and that the implemented interface is really an interface (and so on).
* Supports namespaces, traits and variadics.
* Supports [Union Types](https://github.com/phan/phan/wiki/About-Union-Types).
* Supports generic arrays such as `int[]`, `UserObject[]`, `array<int,UserObject>`, etc..
* Supports array shapes such as `array{key:string,otherKey:?stdClass}`, etc. (internally and in PHPDoc tags)
  This also supports indicating that fields of an array shape are optional
  via `array{requiredKey:string,optionalKey?:string}` (useful for `@param`)
* Supports phpdoc [type annotations](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code).
* Supports inheriting phpdoc type annotations.
* Supports checking that phpdoc type annotations are a narrowed form (E.g. subclasses/subtypes) of the real type signatures
* Supports inferring types from [assert() statements](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code) and conditionals in if elements/loops.
* Supports [`@deprecated` annotation](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#deprecated) for deprecating classes, methods and functions
* Supports [`@internal` annotation](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#internal) for elements (such as a constant, function, class, class constant, property or method) as internal to the package in which it's defined.
* Supports `@suppress <ISSUE_TYPE>` annotations for [suppressing issues](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#suppress).
* Supports [magic @property annotations](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#property) (partial) (`@property <union_type> <variable_name>`)
* Supports [magic @method annotations](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#method) (`@method <union_type> <method_name>(<union_type> <param1_name>)`)
* Supports [`class_alias` annotations (experimental, off by default)](https://github.com/phan/phan/pull/586)
* Supports indicating the class to which a closure will be bound, via `@phan-closure-scope` ([example](tests/files/src/0264_closure_override_context.php))
* Supports analysis of closures and return types passed to `array_map`, `array_filter`, and other internal array functions.
* Offers extensive configuration for weakening the analysis to make it useful on large sloppy code bases
* Can be run on many cores. (requires `pcntl`)
* [Can run in the background (daemon mode)](https://github.com/phan/phan/wiki/Using-Phan-Daemon-Mode), to then quickly respond to requests to analyze the latest version of a file.
  This can also act as a linter in the [Language Server Protocol](https://github.com/Microsoft/language-server-protocol).
  Parts of the language server implementation are based on [felixfbecker/php-language-server](https://github.com/felixfbecker/php-language-server).
  While running in the background, Phan can be used from [various editors](https://github.com/phan/phan/wiki/Editor-Support).
* Output is emitted in text, checkstyle, json, pylint, csv, or codeclimate formats.
* Can run [user plugins on source for checks specific to your code](https://github.com/phan/phan/wiki/Writing-Plugins-for-Phan).
  [Phan includes various plugins you may wish to enable for your project](https://github.com/phan/phan/tree/master/.phan/plugins#2-general-use-plugins).

See [Phan Issue Types](https://github.com/phan/phan/wiki/Issue-Types-Caught-by-Phan) for descriptions
and examples of all issues that can be detected by Phan. Take a look at the
[\Phan\Issue](https://github.com/phan/phan/blob/master/src/Phan/Issue.php) to see the
definition of each error type.

Take a look at the [Tutorial for Analyzing a Large Sloppy Code Base](https://github.com/phan/phan/wiki/Tutorial-for-Analyzing-a-Large-Sloppy-Code-Base) to get a sense of what the process of doing ongoing analysis might look like for you.

See the [tests](https://github.com/phan/phan/blob/master/tests/files) directory for some examples of the various checks.

Phan is imperfect and shouldn't be used to prove that your PHP-based rocket guidance system is free of defects.

## Features provided by plugins

Additional analysis features have been provided by [plugins](https://github.com/phan/phan/tree/master/.phan/plugins#plugins).

- [Checking for syntactically unreachable statements](https://github.com/phan/phan/tree/master/.phan/plugins#unreachablecodepluginphp) (E.g. `{ throw new Exception("Message"); return $value; }`)
- [Checking `*printf()` format strings against the provided arguments](https://github.com/phan/phan/tree/master/.phan/plugins#printfcheckerplugin) (as well as checking for common errors)
- [Checking that PCRE regexes passed to `preg_*()` are valid](https://github.com/phan/phan/tree/master/.phan/plugins#pregregexcheckerplugin)
- [Checking for `@suppress` annotations that are no longer needed.](https://github.com/phan/phan/tree/master/.phan/plugins#unusedsuppressionpluginphp)
- [Checking for duplicate or missing array keys.](https://github.com/phan/phan/tree/master/.phan/plugins#duplicatearraykeypluginphp)
- [Checking coding style conventions](https://github.com/phan/phan/tree/master/.phan/plugins#3-plugins-specific-to-code-styles)
- [Others](https://github.com/phan/phan/tree/master/.phan/plugins#plugins)

Example: [Phan's plugins for self-analysis.](https://github.com/phan/phan/blob/1.0.0/.phan/config.php#L542-L563)

# Usage

Phan needs to be configured with details on where to find code to analyze and how to analyze it. The
easiest way to tell Phan where to find source code is to [create a `.phan/config.php` file](https://github.com/phan/phan/wiki/Getting-Started#creating-a-config-file).
A simple `.phan/config.php` file might look something like the following.

```php
<?php

/**
 * This configuration will be read and overlaid on top of the
 * default configuration. Command line arguments will be applied
 * after this file is read.
 */
return [

    // Supported values: '7.0', '7.1', '7.2', '7.3', null.
    // If this is set to null,
    // then Phan assumes the PHP version which is closest to the minor version
    // of the php executable used to execute phan.
    "target_php_version" => null,

    // A list of directories that should be parsed for class and
    // method information. After excluding the directories
    // defined in exclude_analysis_directory_list, the remaining
    // files will be statically analyzed for errors.
    //
    // Thus, both first-party and third-party code being used by
    // your application should be included in this list.
    'directory_list' => [
        'src',
        'vendor/symfony/console',
    ],

    // A directory list that defines files that will be excluded
    // from static analysis, but whose class and method
    // information should be included.
    //
    // Generally, you'll want to include the directories for
    // third-party code (such as "vendor/") in this list.
    //
    // n.b.: If you'd like to parse but not analyze 3rd
    //       party code, directories containing that code
    //       should be added to the `directory_list` as
    //       to `exclude_analysis_directory_list`.
    "exclude_analysis_directory_list" => [
        'vendor/'
    ],

    // A list of plugin files to execute.
    // See https://github.com/phan/phan/tree/master/.phan/plugins for even more.
    // (Pass these in as relative paths.
    // Base names without extensions such as 'AlwaysReturnPlugin'
    // can be used to refer to a plugin that is bundled with Phan)
    'plugins' => [
        // checks if a function, closure or method unconditionally returns.

        // can also be written as 'vendor/phan/phan/.phan/plugins/AlwaysReturnPlugin.php'
        'AlwaysReturnPlugin',
        // Checks for syntactically unreachable statements in
        // the global scope or function bodies.
        'UnreachableCodePlugin',
        'DollarDollarPlugin',
        'DuplicateArrayKeyPlugin',
        'PregRegexCheckerPlugin',
        'PrintfCheckerPlugin',
    ],
];
```

Take a look at [Creating a Config File](https://github.com/phan/phan/wiki/Getting-Started#creating-a-config-file) and
[Incrementally Strengthening Analysis](https://github.com/phan/phan/wiki/Incrementally-Strengthening-Analysis) for
more details.

Running `phan --help` will show usage information and command-line options.

```
Usage: ./phan [options] [files...]
 -f, --file-list <filename>
  A file containing a list of PHP files to be analyzed

 -l, --directory <directory>
  A directory that should be parsed for class and
  method information. After excluding the directories
  defined in --exclude-directory-list, the remaining
  files will be statically analyzed for errors.

  Thus, both first-party and third-party code being used by
  your application should be included in this list.

  You may include multiple `--directory DIR` options.

 --exclude-file <file>
  A file that should not be parsed or analyzed (or read
  at all). This is useful for excluding hopelessly
  unanalyzable files.

 -3, --exclude-directory-list <dir_list>
  A comma-separated list of directories that defines files
  that will be excluded from static analysis, but whose
  class and method information should be included.

  Generally, you'll want to include the directories for
  third-party code (such as "vendor/") in this list.

 --include-analysis-file-list <file_list>
  A comma-separated list of files that will be included in
  static analysis. All others won't be analyzed.

  This is primarily intended for performing standalone
  incremental analysis.

 -d, --project-root-directory </path/to/project>
  Hunt for a directory named `.phan` in the provided directory
  and read configuration file `.phan/config.php` from that path.

 -r, --file-list-only
  A file containing a list of PHP files to be analyzed to the
  exclusion of any other directories or files passed in. This
  is unlikely to be useful.

 -k, --config-file
  A path to a config file to load (instead of the default of
  `.phan/config.php`).

 -m <mode>, --output-mode
  Output mode from 'text', 'json', 'csv', 'codeclimate', 'checkstyle', or 'pylint'

 -o, --output <filename>
  Output filename

 --init
   [--init-level=3]
   [--init-analyze-dir=path/to/src]
   [--init-analyze-file=path/to/file.php]
   [--init-no-composer]

  Generates a `.phan/config.php` in the current directory
  based on the project's composer.json.
  The logic used to generate the config file is currently very simple.
  Some third party classes (e.g. in vendor/)
  will need to be manually added to 'directory_list' or excluded,
  and you may end up with a large number of issues to be manually suppressed.
  See https://github.com/phan/phan/wiki/Tutorial-for-Analyzing-a-Large-Sloppy-Code-Base

  [--init-level] affects the generated settings in `.phan/config.php`
    (e.g. null_casts_as_array).
    `--init-level` can be set to 1 (strictest) to 5 (least strict)
  [--init-analyze-dir] can be used as a relative path alongside directories
    that Phan infers from composer.json's "autoload" settings
  [--init-analyze-file] can be used as a relative path alongside files
    that Phan infers from composer.json's "bin" settings
  [--init-no-composer] can be used to tell Phan that the project
    is not a composer project.
    Phan will not check for composer.json or vendor/,
    and will not include those paths in the generated config.
  [--init-overwrite] will allow 'phan --init' to overwrite .phan/config.php.

 -C, --color
  Add colors to the outputted issues. Tested in Unix.
  This is recommended for only the default --output-mode ('text')

 -p, --progress-bar
  Show progress bar

 -q, --quick
  Quick mode - doesn't recurse into all function calls

 -b, --backward-compatibility-checks
  Check for potential PHP 5 -> PHP 7 BC issues

 --target-php-version {7.0,7.1,7.2,7.3,native}
  The PHP version that the codebase will be checked for compatibility against.
  For best results, the PHP binary used to run Phan should have the same PHP version.
  (Phan relies on Reflection for some param counts
   and checks for undefined classes/methods/functions)

 -i, --ignore-undeclared
  Ignore undeclared functions and classes

 -y, --minimum-severity <level in {0,5,10}>
  Minimum severity level (low=0, normal=5, critical=10) to report.
  Defaults to 0.

 -c, --parent-constructor-required
  Comma-separated list of classes that require
  parent::__construct() to be called

 -x, --dead-code-detection
  Emit issues for classes, methods, functions, constants and
  properties that are probably never referenced and can
  be removed. This implies `--unused-variable-detection`.

 --unused-variable-detection
  Emit issues for variables, parameters and closure use variables
  that are probably never referenced.
  This has a few known false positives, e.g. for loops or branches.

 -j, --processes <int>
  The number of parallel processes to run during the analysis
  phase. Defaults to 1.

 -z, --signature-compatibility
  Analyze signatures for methods that are overrides to ensure
  compatibility with what they're overriding.

 --disable-plugins
  Don't run any plugins. Slightly faster.

 -P, --plugin <pluginName|path/to/Plugin.php>
  Add a plugin to run. This flag can be repeated.
  (Either pass the name of the plugin or a relative/absolute path to the plugin)

 --strict-method-checking
  Warn if any type in a method invocation's object is definitely not an object,
  or any type in an invoked expression is not a callable.
  (Enables the config option `strict_method_checking`)

 --strict-param-checking
  Warn if any type in an argument's union type cannot be cast to
  the parameter's expected union type.
  (Enables the config option `strict_param_checking`)

 --strict-property-checking
  Warn if any type in a property assignment's union type
  cannot be cast to a type in the property's declared union type.
  (Enables the config option `strict_property_checking`)

 --strict-return-checking
  Warn if any type in a returned value's union type
  cannot be cast to the declared return type.
  (Enables the config option `strict_return_checking`)

 -S, --strict-type-checking
  Equivalent to
  `--strict-method-checking --strict-param-checking --strict-property-checking --strict-return-checking`.

 --use-fallback-parser
  If a file to be analyzed is syntactically invalid
  (i.e. "php --syntax-check path/to/file" would emit a syntax error),
  then retry, using a different, slower error tolerant parser to parse it.
  (And phan will then analyze what could be parsed).
  This flag is experimental and may result in unexpected exceptions or errors.
  This flag does not affect excluded files and directories.

 --allow-polyfill-parser
  If the `php-ast` extension isn't available or is an outdated version,
  then use a slower parser (based on tolerant-php-parser) instead.
  Note that https://github.com/Microsoft/tolerant-php-parser
  has some known bugs which may result in false positive parse errors.

 --force-polyfill-parser
  Use a slower parser (based on tolerant-php-parser) instead of the native parser,
  even if the native parser is available.
  Useful mainly for debugging.

 -s, --daemonize-socket </path/to/file.sock>
  Unix socket for Phan to listen for requests on, in daemon mode.

 --daemonize-tcp-host
  TCP hostname for Phan to listen for JSON requests on, in daemon mode.
  (e.g. 'default', which is an alias for host <IP_ADDRESS>, or `<IP_ADDRESS>` for
  usage with Docker). `phan_client` can be used to communicate with the Phan Daemon.

 --daemonize-tcp-port <default|1024-65535>
  TCP port for Phan to listen for JSON requests on, in daemon mode.
  (e.g. 'default', which is an alias for port 4846.)
  `phan_client` can be used to communicate with the Phan Daemon.

 -v, --version
  Print Phan's version number

 -h, --help
  This help information

 --extended-help
  This help information, plus less commonly used flags
  (E.g. for daemon mode)
```

## Annotating Your Source Code

Phan reads and understands most [PHPDoc](http://www.phpdoc.org/docs/latest/guides/types.html)
type annotations including [Union Types](https://github.com/phan/phan/wiki/About-Union-Types)
(like `int|MyClass|string|null`) and generic array types (like `int[]` or `string[]|MyClass[]` or `array<int,MyClass>`).

Take a look at [Annotating Your Source Code](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code)
and [About Union Types](https://github.com/phan/phan/wiki/About-Union-Types) for some help
getting started with defining types in your code.

Phan supports `(int|string)[]` style annotations, and represents them internally as `int[]|string[]`
(Both annotations are treated like array which may have integers and/or strings).
When you have arrays of mixed types, just use `array`.

The following code shows off the various annotations that are supported.

```php
/**
 * @return void
 */
function f() {}

/** @deprecated */
class C {
    /** @var int */
    const C = 42;

    /** @var string[]|null */
    public $p = null;

    /**
     * @param int|null $p
     * @return string[]|null
     */
    public static function f($p) {
        if (is_null($p)) {
            return null;
        }

        return array_map(
            /** @param int $i */
            function($i) {
                return "thing $i";
            },
            range(0, $p)
        );
    }
}
```

Just like in PHP, any type can be nulled in the function declaration which also
means a null is allowed to be passed in for that parameter.

Phan checks the type of every single element of arrays (Including keys and values).
In practical terms, this means that `[$int1=>$int2,$int3=>$int4,$int5=>$str6]` is seen as `array<int,int|string>`,
which Phan represents as `array<int,int>|array<int,string>`.
`[$strKey => new MyClass(), $strKey2 => $unknown]` will be represented as
`array<string,MyClass>|array<string,mixed>`.

- Literals such as `[12,'myString']` will be represented internally as array shapes such as `array{0:12,1:'myString'}`

# Generating a file list

This static analyzer does not track includes or try to figure out autoloader magic. It treats
all the files you throw at it as one big application. For code encapsulated in classes this
works well. For code running in the global scope it gets a bit tricky because order
matters. If you have an `index.php` including a file that sets a bunch of global variables and
you then try to access those after the `include(...)` in `index.php` the static analyzer won't
know anything about these.

In practical terms this simply means that you should put your entry points and any files
setting things in the global scope at the top of your file list. If you have a `config.php`
that sets global variables that everything else needs, then you should put that first in the list followed by your
various entry points, then all your library files containing your classes.

# Development

Take a look at [Developer's Guide to Phan](https://github.com/phan/phan/wiki/Developer's-Guide-To-Phan) for help getting started hacking on Phan.

When you find an issue, please take the time to create a tiny reproducing code snippet that illustrates
the bug. And once you have done that, fix it. Then turn your code snippet into a test and add it to
[tests](tests) then `./test` and send a PR with your fix and test. Alternatively, you can open an Issue with
details.

To run Phan's unit tests, just run `./test`.

To run all of Phan's unit tests and integration tests, run `./tests/run_all_tests.sh`

# Code of Conduct

We are committed to fostering a welcoming community. Any participant and
contributor is required to adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md).

repository: curevuln/curevuln-exercise

detected_licenses: BSD-3-Clause MIT ISC

gha_language: PHP

repo_name: curevuln/curevuln-exercise