<commit_before>###*
Modal dialogs
=============

Instead of [linking to a page fragment](/up.link), you can choose
to show a fragment in a modal dialog. The existing page will remain
open in the background and reappear once the modal is closed.

To open a modal, add an [`up-modal` attribute](/a-up-modal) to a link,
or call the Javascript functions [`up.modal.follow`](/up.modal.follow)
and [`up.modal.visit`](/up.modal.visit).
  
For smaller popup overlays ("dropdowns") see [up.popup](/up.popup) instead.


\#\#\#\# Customizing the dialog design

Loading the Unpoly stylesheet will give you a minimal dialog design:

- Dialog contents are displayed in a white box that is centered vertically and horizontally.
- There is a a subtle box shadow around the dialog
- The box will grow to fit the dialog contents, but never grow larger than the screen
- The box is placed over a semi-transparent background to dim the rest of the page
- There is a button to close the dialog in the top-right corner

The easiest way to change how the dialog looks is by overriding the [default CSS styles](https://github.com/unpoly/unpoly/blob/master/lib/assets/stylesheets/up/modal.css.sass).

By default the dialog uses the following DOM structure:

    <div class="up-modal">
      <div class="up-modal-backdrop">
      <div class="up-modal-viewport">
        <div class="up-modal-dialog">
          <div class="up-modal-content">
            ...
          </div>
          <div class="up-modal-close" up-close>X</div>
        </div>
      </div>
    </div>

If you want to change the design beyond CSS, you can
configure Unpoly to [use a different HTML structure](/up.modal.config).


\#\#\#\# Closing behavior

By default the dialog automatically closes
*whenever a page fragment behind the dialog is updated*.
This is useful to have the dialog interact with the page that
opened it, e.g. by updating parts of a larger form or by signing in a user
and revealing additional information.

To disable this behavior, give the opening link an `up-sticky` attribute:

    <a href="/settings" up-modal=".options" up-sticky>Settings</a>


@class up.modal 
###
up.modal = (($) ->

  u = up.util

  ###*
  Sets default options for future modals.

  @property up.modal.config
  @param {String} [config.history=true]
    Whether opening a modal will add a browser history entry.
  @param {Number} [config.width]
    The width of the dialog as a CSS value like `'400px'` or `50%`.

    Defaults to `undefined`, meaning that the dialog will grow to fit its contents
    until it reaches `config.maxWidth`. Leaving this as `undefined` will
    also allow you to control the width using CSS on `.up-modal-dialog´.
  @param {Number} [config.maxWidth]
    The width of the dialog as a CSS value like `'400px'` or `50%`.
    You can set this to `undefined` to make the dialog fit its contents.
    Be aware however, that e.g. Bootstrap stretches input elements
    to `width: 100%`, meaning the dialog will also stretch to the full
    width of the screen.
  @param {Number} [config.height='auto']
    The height of the dialog in pixels.
    Defaults to `undefined`, meaning that the dialog will grow to fit its contents.
  @param {String|Function(config)} [config.template]
    A string containing the HTML structure of the modal.
    You can supply an alternative template string, but make sure that it
    defines tag with the classes `up-modal`, `up-modal-dialog` and  `up-modal-content`.
yy
    You can also supply a function that returns a HTML string.
    The function will be called with the modal options (merged from these defaults
    and any per-open overrides) whenever a modal opens.
  @param {String} [config.closeLabel='X']
    The label of the button that closes the dialog.
  @param {String} [config.openAnimation='fade-in']
    The animation used to open the viewport around the dialog.
  @param {String} [config.closeAnimation='fade-out']
    The animation used to close the viewport the dialog.
  @param {String} [config.backdropOpenAnimation='fade-in']
    The animation used to open the backdrop that dims the page below the dialog.
  @param {String} [config.backdropCloseAnimation='fade-out']
    The animation used to close the backdrop that dims the page below the dialog.
  @param {String} [config.openDuration]
    The duration of the open animation (in milliseconds).
  @param {String} [config.closeDuration]
    The duration of the close animation (in milliseconds).
  @param {String} [config.openEasing]
    The timing function controlling the acceleration of the opening animation.<commit_msg>fix docs<commit_after>###*
Modal dialogs
=============

Instead of [linking to a page fragment](/up.link), you can choose
to show a fragment in a modal dialog. The existing page will remain
open in the background and reappear once the modal is closed.

To open a modal, add an [`up-modal` attribute](/a-up-modal) to a link,
or call the Javascript functions [`up.modal.follow`](/up.modal.follow)
and [`up.modal.visit`](/up.modal.visit).
  
For smaller popup overlays ("dropdowns") see [up.popup](/up.popup) instead.


\#\#\#\# Customizing the dialog design

Loading the Unpoly stylesheet will give you a minimal dialog design:

- Dialog contents are displayed in a white box that is centered vertically and horizontally.
- There is a a subtle box shadow around the dialog
- The box will grow to fit the dialog contents, but never grow larger than the screen
- The box is placed over a semi-transparent background to dim the rest of the page
- There is a button to close the dialog in the top-right corner

The easiest way to change how the dialog looks is by overriding the [default CSS styles](https://github.com/unpoly/unpoly/blob/master/lib/assets/stylesheets/up/modal.css.sass).

By default the dialog uses the following DOM structure:

    <div class="up-modal">
      <div class="up-modal-backdrop">
      <div class="up-modal-viewport">
        <div class="up-modal-dialog">
          <div class="up-modal-content">
            ...
          </div>
          <div class="up-modal-close" up-close>X</div>
        </div>
      </div>
    </div>

If you want to change the design beyond CSS, you can
configure Unpoly to [use a different HTML structure](/up.modal.config).


\#\#\#\# Closing behavior

By default the dialog automatically closes
*whenever a page fragment behind the dialog is updated*.
This is useful to have the dialog interact with the page that
opened it, e.g. by updating parts of a larger form or by signing in a user
and revealing additional information.

To disable this behavior, give the opening link an `up-sticky` attribute:

    <a href="/settings" up-modal=".options" up-sticky>Settings</a>


@class up.modal 
###
up.modal = (($) ->

  u = up.util

  ###*
  Sets default options for future modals.

  @property up.modal.config
  @param {String} [config.history=true]
    Whether opening a modal will add a browser history entry.
  @param {Number} [config.width]
    The width of the dialog as a CSS value like `'400px'` or `50%`.

    Defaults to `undefined`, meaning that the dialog will grow to fit its contents
    until it reaches `config.maxWidth`. Leaving this as `undefined` will
    also allow you to control the width using CSS on `.up-modal-dialog´.
  @param {Number} [config.maxWidth]
    The width of the dialog as a CSS value like `'400px'` or `50%`.
    You can set this to `undefined` to make the dialog fit its contents.
    Be aware however, that e.g. Bootstrap stretches input elements
    to `width: 100%`, meaning the dialog will also stretch to the full
    width of the screen.
  @param {Number} [config.height='auto']
    The height of the dialog in pixels.
    Defaults to `undefined`, meaning that the dialog will grow to fit its contents.
  @param {String|Function(config)} [config.template]
    A string containing the HTML structure of the modal.
    You can supply an alternative template string, but make sure that it
    defines tag with the classes `up-modal`, `up-modal-dialog` and  `up-modal-content`.

    You can also supply a function that returns a HTML string.
    The function will be called with the modal options (merged from these defaults
    and any per-open overrides) whenever a modal opens.
  @param {String} [config.closeLabel='X']
    The label of the button that closes the dialog.
  @param {String} [config.openAnimation='fade-in']
    The animation used to open the viewport around the dialog.
  @param {String} [config.closeAnimation='fade-out']
    The animation used to close the viewport the dialog.
  @param {String} [config.backdropOpenAnimation='fade-in']
    The animation used to open the backdrop that dims the page below the dialog.
  @param {String} [config.backdropCloseAnimation='fade-out']
    The animation used to close the backdrop that dims the page below the dialog.
  @param {String} [config.openDuration]
    The duration of the open animation (in milliseconds).
  @param {String} [config.closeDuration]
    The duration of the close animation (in milliseconds).
  @param {String} [config.openEasing]
    The timing function controlling the acceleration of the opening animation.
{'fraction_non_alphanumeric': 0.09305873379099924, 'fraction_numerical': 0.002833169881224801, 'mean_word_length': 3.557100297914598, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 31, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1681735', 'n_tokens_mistral': 2595, 'n_tokens_neox': 2480, 'n_words': 1189}