Description

Injection makes it trivial to load content from a server and display it on a web page with a rich, modern web experience without any page reloads. Pat-inject works on existing infra structures, is designed with respect for accessibility and follows the principles of progressive enhancement.

Documentation

Concept

Injection is an enhancement on regular HTML links that point from one HTML page to another. Without JavaScript and injection, you would keep this standard behaviour. With JavaScript and pat-inject, a richer experience is created for modern graphical browsers.

Pat-inject intercepts the page refresh, invisibly collects the remote page, extracts parts out of it that you're interested in and replaces the content somewhere on the currently visible page without refreshing the browser window.

The principle is illustrated in the following graphic.

This typical example illustrates how in this case the content of the main content region is replaced by the content of the same region of another page. One could for instance create a series of links styled as tabs this way, which would each refresh the content area of the page, without refreshing the browser window.

A slightly more complex case is illustrated below. You see how multiple regions are extracted out of one page and injected into similar areas on another page. It doesn't matter if the regions on the remote page are differently named or styled.

It's also possible to inject content from another page into a modal panel:

The possibilities don't stop here. Other applications of injection include injection in tooltips (pat-tooltip) and injection in 'self healing messages' (Similar to Mac OS banners or Growl) (pat-notification). Those ways of working with injection are explained in the respective documentation sections of the components pat-tooltip and pat-notification.

Code examples

The most simple form of injection is a link which loads content when clicked:

Demo the frobber

When a user clicks this link demos/frobber.html will be fetched via AJAX, the element with id demo-content is extracted and used to replace the content of #demo-content on the current page.

In another situation you may not want to replace content but add new content. You can easily do that by using a modifier:

Tell me more

In this example clicking on the Tell me more link will load the latest news content and inject it before the content of #news.

Perhaps inserting a single block of content is not enough for your needs? Don't worry! Let's give you another example:

When you submit this form two things happen: #demo-content from the response is used to replace #section's content of the page, replacing the current form with a new form or a feedback message. In addition a #notice element is extracted from the response and added at the bottom of #notices.

Where and what to inject

The most simple injection fetches a source via AJAX, extracts its body's content and replaces the current body's content with it:

Display news content in body content

Admittedly, this is a rare use case. However, it is ideal for understanding the defaults:

Default selector and source and target selector

The default selector is body and will be used as target and source selector, unless one or both of them are overridden.

By default we work with/on content

For target and source by default the content is selected and worked on.

In the next section you learn how to use element ids as source and target selectors, which covers most use cases. These can be combined with modifiers and finally the full injection power is unleashed with arbitrary jQuery selectors.

XXX: add references to the sections.

Select individual elements via #id

The simple injections replace the content of an element in target with the content of an element in source. There is a one-to-one relation between elements in source and target:

Multi-injection with a one-to-one mapping.

In case one source element is to be used for both targets, it can be specified as part of the href (or action in case of forms):

One source element for two targets.

One source element for two targets, source specified via href.

The source id specified as part of href/action is the default source selector and can be overriden for one or more injections:

One injection overrides the default source element.

Sometimes it is useful to use the triggering element itself as a target.

This can be done by using the special self target:

Replace me with sources.html.

Modifiers

So far you can replace the target element's content with the source element's content. In order to work on the actual elements, or to place things relative to theselected elements, we have three modifiers:

::element Select the element, instead of the content.

Can be used for source and target, and in case of the latter be combined with ::before/::after.

::before Like in CSS, the pseudo-element (a position) right before the content of the target element. The so far non-existing, but soon-to-be first child of the target element.

Can be used for target and combined with ::element.

::after Like in CSS, the pseudo-element (a position) right before the content of the selected element. It can be used for the target and combined with ::element.

Let's see these in action and combination:

Still working on content

Replace target content with source content (default, just a reminder):

Put source content before target content:

Put source content after target content:

Elements instead of content

Replace target element with source element:

Put source element before target element:

Put source element after target element:

Mixing element and content

Replace target element with source content:

Replace target content with source element:

Source content before target element:

Source content after target element:

Source element before target content:

Source element after target content:

Using full-blown jQuery selectors

For both selectors every conceivable jQuery selector is allowed. If multiple elements match, all will be replaced.

...

Non-existing targets

In case the target selector returns no elements, we will attempt to create a matching element for you.

So far we are able to handle 'target' selectors that consist of only an id: A div with that id will be created and injected as the last child of body:

…