Controlling Nittro behaviour - nittro/nittro GitHub Wiki

Nittro tries very hard to be low maintenance. That means that hopefully most of the time the default behaviour of the various components will be exactly what you need. It is however good to know what you can change and how.

Most of the Nittro components come with a DI Container Builder extension which gets compiled in and registered automatically if you use the Nittro builder, be it the online tool on the Nittro download page or the Gulp or Grunt plugins. These extensions take care of registering the services and / or factories their components provide in the DI Container. Therefore if you want to change some of the default options for a Nittro service you need to set the options of the appropriate extension. This is done via the params section of the bootstrap option of the Nittro builder.

The examples on this page will show the available options using NEON, which is what you'd use in the online builder; but the same options can be specified using a plain JavaScript object with the same structure if you're using the Gulp or Grunt plugin.

params:
    ajax:
        allowOrigins: null

• allowOrigins: An Array or a comma-separated string listing additional origins (protocol://host[:port]) to enable AJAX for. Note that for this to work the responses from these origins must include the appropriate Access-Control-Allow-Origin headers.

params:
    page:
        whitelistHistory: false
        whitelistLinks: false
        whitelistRedirects: false
        csp: null
        transitions:
            defaultSelector: '.nittro-transition-auto'
        i18n:
            connectionError: '...'
            unknownError: '...'
        scroll:
            target: null
            margin: 30
            scrollDown: false
            duration: 500

• whitelistHistory: If set to true the Page service will only create new history entries when the link or form that was clicked or submitted has the data-history="true" attribute set. Similarly when false you can prevent a link or form from creating a history entry by providing the data-history="false" attribute.
• whitelistLinks: These control whether links and forms are loaded / submitted using AJAX by default. A value of true will result in Nittro loading only elements with data-ajax="true", and conversely, a value of false will tell Nittro to process all elements except those with data-ajax="false".
• whitelistRedirects: You've got the gist by now, hopefully - this option controls how redirects received in the payload from the server are handled. The default value of false will attempt to follow all local redirects using AJAX, while true will force a full page reload. Unlike the previous options this one can be overridden by the allowAjax parameter in the response payload. The PresenterUtils Trait from the nittro/nette-bridges Composer package provides the shortcut methods $presenter->allowAjax() and $presenter->disallowAjax() for your convenience.
• csp: Whether or not to enable automatic Content Security Policy handling for inline scripts. Note that this will only work if the first <script> tag in the document has the nonce attribute set (in fact the default behaviour is to detect whether or not to enable CSP handling based on the presence of the nonce attribute on the first <script> tag in the document).
• transitions.defaultSelector: This option tells Nittro which element(s) to apply transitions to during an AJAX request if the originating link or form didn't specify something else using the data-transition attribute.
• i18n: Allows you to specify different messages to display to the user in the event of an AJAX error.
• scroll.target: Controls automatic scrolling to updated content upon page navigation. The default (null) means to look for the topmost updated snippet. You can also specify a selector to always scroll to a fixed element, or an integer to always scroll to a fixed offset, or false to disable automatic scrolling altogether.
• scroll.margin: Controls how far should Nittro scroll above the target element.
• scroll.scrollDown: Scroll to the target element even if it means scrolling down (by default Nittro only scrolls down when the user moves back / forward through browsing history).
• scroll.duration: Controls how long an automatic scroll should take, in milliseconds.

params:
    forms:
        whitelistForms: false
        autoResetForms: true

• whitelistForms: This is the same thing as the Page component's whitelistLinks setting, except for forms.
• autoResetForms: Whether to reset forms after they have been successfully submitted. This can be overridden for specific forms using the data-reset attribute.

params:
    flashes:
        layer: null
        classes: null
        positioner:
            defaultOrder: 'above,rightOf,below,leftOf'
            margin: 20

• layer: The HTML ID of a DOM element all flash messages are appended to. The default element is document.body.
• classes: A string of classes separated by spaces to add to flash messages. The %type% placeholder will be replaced with the message type.
• positioner.defaultOrder and positioner.margin: Allows you to change the order in which floating flash message placement is attempted and the minimal margin from viewport edges; this probably sounds a bit cryptic, but know that this will be discussed at greater length once I get around to writing a dedicated page about flashes.

params:
    dialogs:
        baseZ: 1000
        whitelistHistory: true
        disableDefaultTransitions: true

• baseZ: The base Z-index for the dialog manager. The first open dialog will have a Z-index of baseZ, if another is open on top of it, it will have baseZ + 1 and so on.
• whitelistHistory: When set to true, opening a dialog using the data-dialog attribute (usually through the n:dialog macro) will not add the dialog's URL to the browsing history unless explicitly overridden using data-history="true" or the context.history option of Page.open(). This has the same effect as if every link or form with the data-dialog attribute also had data-history="false", which is usually what you want with dialogs.
• disableDefaultTransitions: When set to true, no default transitions will take place when a dialog is opened using data-dialog unless explicitly overridden using the data-transition="#selector" attribute. This has the same effect as if every link with the data-dialog attribute also had data-transition="false", which is usually what you want with dialogs.

params:
    confirm:
        prompt: "Are you sure?"
        confirm: "Yes"
        cancel: "No"

• I believe these are pretty self-explanatory.