smd_pullquote

For more information on usage, bugs, features etc, please visit the forum thread.

Requires smd_lib v0.3 to be installed and activated.

Requires jQuery to be available. From TXP v4.0.5 this is distributed by default.

Contents

• Overview
• Before you begin
• Attributes
  • jquery
  • jq_clashvar
  • search_class
  • wraptag
  • class
  • container
  • insert_method
  • limit
  • random
  • hide_originals
  • chopper
  • omissions
  • start
  • end
  • pos
• Examples
• Styling

Overview

Ever wanted to have those magazine-style pullquotes automatically generated from your article content? This is the plugin for you!

Features:

• Using markup you tell the plugin which bits of your articles are to be displayed and styled separately: no need to handle quotes separately from content
• Words from the full body text can be cut from the quotes to make them shorter; omitted words are replaced with characters of your choice
• Display one or more quotes randomly from a page, optionally removing the originals
• Position the quotes anywhere you like via CSS, or use rudimentary maths to keep the quote near to its position on the page. See pos, container and insert_method
• Key attributes covered by MLP for multi-lingual control over quotes

Before you begin

The plugin relies heavily on javascript and jQuery. From TXP v4.0.5 jQuery is shipped and installed with the base package. You may need to upgrade the version that ships with textpattern to a later version since this plugin was developed with jQuery v1.2.1; the version that ships with TXP is an earlier version. Note that if you use other javascript libraries on the same page (e.g. mootools) you may need to tell the plugin which is which to avoid clashes. See jquery and jq_clashvar for more.

The general idea is that as you write your article, you wrap any killer quotes with some markup; usually a <span> element since they are "invisible" in the content. Give each quote the same class name (by default it's pq but can be changed with the search_class option) and your quotes will be copied from your document into separate elements ready to be positioned/styled.

Absolute positioning works best but you may have success with floats, or even inline depending on your level of ingenuity.

Attributes

jquery

For a default installation you should not need to change this. It specifies the path to the jquery.js library file. Defaults to /textpattern/jquery.js. Give it the full path to the library on your server or, if you have already loaded the library earlier on the page, specify jquery="".

jq_clashvar

You should not need to change this unless you are using another javascript library such as mootools on the same page. To avoid the libraries clashing, jQuery provides a facility to identify itself uniquely to the javascript interpreter. Specify the unique variable you wish jquery to use here.

By default it uses jq. If you have already set up the jquery .noConflict() variable elsewhere on the page, simply specify the variable name you used and it will continue to use it (in this case, it will not redefine the variable). If you specify a different name, or one that is previously undefined, the variable will be created and used for smd_pullquote.

search_class

Once the page is displayed the plugin goes through the document and looks for all occurrences of content wrapped with an HTML element of a particular class. By default it's pq. If you don't like that, change it with this option.

Let's assume your content is:

The lion is a magnificent animal but don't be lulled into a false sense of security by its looks. Beneath the cuddly exterior lie teeth - big teeth - and <span class="pq">if it hasn't eaten for a while you could be next on the menu</span>.

Using the span in that manner tells the plugin that the text "if it hasn't eaten for a while you could be next on the menu" should be 'pulled' (copied) out of the text into its own element so you can style it.

You can specify as many of these as you like, just give each one the same class. And don't nest them.

wraptag

Every quote pulled from the document will be placed into separate elements, each wrapped in this tag. By default it is the <q> tag but you can specify anything you like here: div, span, p, whatever. See start and end for more.

class

Every quote pulled from the document is assigned the same class for easy styling. Specify it here. Default: pQuote (note the capital Q!)

container

All pullquotes are injected into the document after it is rendered to the page. Specify here a DOM element, id or class name where you want them to go. By default it is body.

If you are specifying a raw html element, just give its name: e.g. container="body".

If you wish the quotes to be inserted into an element with a specific id, use container="#myID".

Similarly, if you want the quotes to be inserted into an element with a specific class, use container=".myClass". The insert_method attribute specifies exactly how the element is inserted.

Note that if you choose a class and it exists in more than one place on the page, the quotes will be duplicated. This 'feature' could be used as a special effect but it's unlikely to be of any practical use.

insert_method

Once you have chosen an element to contain your quotes, you can specify how you want them injected into that element. The default is append to add the quotes to the end of whatever is already there.

Options

• append
  the default: inserts the quotes after whatever is already inside the element
• prepend
  inserts the quotes before whatever is already inside the element
• after
  adds the quotes immediately after the chosen element
• before
  puts the quotes immediately in front of the chosen element
• replaceWith
  replaces the given element entirely by the quotes. This may have odd results if you have elected to display more than one quote. See limit

limit

Specify the maximum number of quotes you wish to have rendered to the page. By default it is empty (or "0") which means "all of them".

random

Set this on to randomly pick limit quotes from the page and display them.

Options

• 0
  the default: off, i.e. pick the quotes off the page in the order they appear
• 1
  on: pick random quotes from the page and display them. The number of quotes chosen is governed by the limit option

hide_originals

Set this to remove the original quotes from the source document and only leave the pullquotes themselves. It has a few levels of severity.

Options

• 0
  the default: original quotes are displayed in context
• 1
  original quotes are removed from the document body, leaving just the pullquotes behind, but only for those quotes that are actually used
• 2
  all original quotes are removed from the document body, irrespective of whether the quote was used. Note that in the latter two cases the whole quote is removed, irrespective of any words chopped out.

Using hide_originals="2" might be useful for a simple "quote of the day" where you can load all the quotes onto the page and have the plugin choose one randomly.

chopper

Sometimes quotes are too long to make into pullquotes and abridged versions work better. This options specifies a character sequence to allow words to be omitted from quotes; any words between pairs of character sequences defined by the chopper attribute will be removed from the quote. The default character sequence is ~~ (two tildes).

The missing text is replaced with the character sequence defined by omissions.

For example, specifying the sentence:

I cannot help it~~; reason has nothing to do with it; ~~I love her against reason.

Would render this to the page:

<q class="pQuote">I cannot help it … I love her
     against reason</q>

You can specify as many pairs of characters within a pullquote as you like and the text between each set will be omitted. If you do not like the character sequence or are using that particular sequence within your body text, change it to anything you like with this option. Once each quote has been generated, the character sequence is removed from the document body so it doesn't clutter up your beautiful prose!

omissions

As shown in the example for the chopper option, omitted characters are replaced with whatever character entity or sequence is defined in this attribute. By default it is the ellipsis (&hellip; or '…').

Along with a few of the other attributes, this one is Multi-Lingual Publishing pack (MLP) aware so you can specify a different character sequence per language.

start

The character sequence to add to the start of every quote. By default this is empty because good browsers render the HTML q element with language-specific quote characters automatically. Should you wish to change the wraptag however, start and its corresponding friend end may be useful. Note that browsers that support the CSS2 before and after pseudo-elements can also add characters via the content: property. This option is MLP-aware.

end

Complements start and specifies the character sequence to add to the end of every quote. By default this is empty because good browsers render the HTML q element with language-specific quote characters automatically. This option is MLP-aware.

pos

Although positioning can be done entirely in CSS (and probably should), there are times when it is useful to specify positions from the plugin. One such case is where you want the quote to be pulled out alongside the place that the full quote appears in context. The pos attribute helps you achieve this.

It takes a pair of arguments, separated by a comma. If the option is omitted or malformed, it is disabled and positioning is therefore completely under CSS control. Otherwise, specify x and y co-ordinates of where you wish the pullquotes to appear. This option is best explained by example:

(note: it is assumed that the pQuote element is assigned position:absolute; via CSS. See styling for examples)

pos=	result	remarks
"50, 200"	all quotes appear at 50px from the left edge and 200px from the top edge of the container	without any units specified, 'px' is assumed
"10%, 150"	quotes appear 10% from the left edge and 150px from the top edge	Resizing the horizontal axis of the browser window moves the quotes
"40pt, y"	quotes appear 40pts from the left edge and at the same vertical position as the place the original quote appears	some variation in y position sometimes occurs depending on the containing element
"x-80, y+50"	quotes appear 80px to the left of the original quote and 50px below it	you can use + - * or / to perform simple maths on x and y co-ordinates

You can use any valid CSS unit of length measurement, such as %, px, em, ex, pt, cm and so on.

Examples

Example 1

<txp:smd_pullquote />

Vanilla usage: just puts the javascript on the page, scans for all class definitions labelled 'pq' and creates pullquotes in HTML 'q' tags. Style to taste.

Example 2

<txp:smd_pullquote wraptag="div" start="&laquo;"
     end="&raquo;" class="myQuotes" />

Wraps each quote in a <div> tag, prepends each quote with a left-angle quote and appends each quote with a right-angle quote symbol. Sets the class attribute of the div tags to myQuotes

Example 3

<txp:smd_pullquote wraptag="p" search_class="AQuote"
     chopper="@DLM@" omissions="....." />

Searches the document for elements with a class of AQuote and omits words between pairs of @DLM@. Each omitted set of words is replaced with a series of dots.

<span class="AQuote">I cannot help it@DLM@; reason has nothing to do with it; @DLM@I love her against reason.</span>

generates a pullquote like this:

<p class="pQuote">I cannot help it..... I love her against reason.</p>

Example 4

<txp:smd_pullquote jquery="" jq_clashvar="jQuery"
     container="#quoteHolder" insert_method="prepend" />

Tells the plugin not to load the jquery library (the assumption being that it is already loaded) and to use the noConflict() variable name 'jQuery' (if it has not already been set up it will be assigned). The quotes are then told to attach themselves to the element with an id of #quoteHolder and they are to be placed immediately in front of any content that may already be in the element.

Example 5

<txp:smd_pullquote limit="1" random="1" pos="60, 230" />

Only shows 1 quote on the page (the limit attribute), telling the plugin to choose a random quote from those defined in the source and place it at a position 60px from the left edge and 230px from the top edge of the containing element (the default <body> in this case).

Using limit="2" random="1" instead would pull two random quotes from the text and put them in exactly the same spot on the page. See styling for ways to separate them.

Using limit="2" random="0" (or omitting random) would pull the first two quotes from the text and put them in exactly the same spot on the page.

Styling

To style quotes when using the pos attribute you can use something like this:

.pQuote {
	position:absolute;
	margin:1em;
	padding:.5em;
	font-size:1.1em;
	text-align:right;
	font-style:italic;
	color:#222;
	line-height:1.35;
	width:120px;
}

Add top: and left: definitions if you want to fix the location and only intend having 1 quote per page, or prefer not to use the pos attribute.

For multiple, fixed-position quotes you could use this type of styling:

.pQuote {
	position:absolute;
	top:50px;
	left:100px;
}
.pQuote + .pQuote {
	top:450px;
	right:30px;
}