systemantics

<!-- columnize -->

Lutz Issler
Mauerstr. 10-12
52064 Aachen
GERMANY
T +49 241 94315680
mail@systemantics.net
EN / DE

Column layout for jQuery

jQue­ry Co­lum­ni­ze is a plu­gin for the Ja­vas­cript li­bra­ry jQue­ry which al­lows to crea­te a newspa­per-li­ke co­lumn lay­out. The ori­gi­nal HTML co­de on­ly needs small ad­ap­ti­ons. In most ca­ses, it is not ne­cessa­ry to ad­apt the HTML co­de at all.

Do­cu­men­ta­tion

Throb­ber crea­tes a loa­ding ani­ma­tion for jQue­ry, rea­dy to be used in your AJAX app­li­ca­ti­ons. Of cour­se, the throb­ber is not li­mi­ted to AJAX.

Using the plu­gin is ea­sy:

$("#but­ton").throb­ber("click")

adds a loa­ding ani­ma­tion (›throb­ber‹) to the DOM no­de with the ID ›but­ton‹ which shows up when a click event is trig­ge­red.

The fol­lo­wi­ng is a list of all func­ti­ons pro­vi­ded by the plu­gin:

  • $().throb­ber()
    $().throb­ber(event)
    $().throb­ber(op­ti­ons)
    $().throb­ber(event, op­ti­ons)
    event is a string spe­cify­ing the event to which the throb­ber should bind. The default he­re is ›click‹. op­ti­ons is a set of op­ti­ons (see be­low). Bo­th pa­ra­me­ters can be omit­ted
  • $.throb­berS­how(op­ti­ons)
    Im­me­dia­te­ly shows a throb­ber as spe­ci­fied. If no pa­rent ele­ment is spe­ci­fied with op­ti­ons.pa­rent, the throb­ber will be ap­pen­ded to the ele­ment.
  • $.throb­ber­Hi­de()
    Hi­de all throb­bers.

Op­ti­ons

The plu­gin re­co­gni­zes se­ver­al op­ti­ons which are de­no­ted in cur­ly brackets.

  • ajax: ›true‹ if the throb­bers should lis­ten to AJAX events. In this ca­se, the throb­bers are au­to­ma­ti­cal­ly hid­den if all AJAX re­quests are com­ple­ted. ›fal­se‹ if you use AJAX, but want to hi­de the throb­bers ma­nu­al­ly. Default: ›true‹
  • de­lay: The ti­meout (in mil­li­se­conds) un­til the throb­ber should ap­pear. Default: ›0‹
  • ima­ge: The fi­len­a­me of the throb­ber ima­ge. Default: ›throb­ber.gif‹
  • pa­rent: A jQue­ry se­lec­tor spe­cify­ing the pa­rent ele­ment to which the throb­ber should be ap­pen­ded. All other child ele­ments are au­to­ma­ti­cal­ly hid­den when the throb­ber is ap­pen­ded. If this is left blank, the throb­ber re­pla­ces the ele­ment to which it was at­ta­ched. Default: ›‹
  • wrap: The HTML co­de that should wrap the throb­ber. Default: ›‹

Tips

If you don't use AJAX, you don't ha­ve to ex­pli­cit­ly set the ›ajax‹ pa­ra­me­ter to ›fal­se‹. The ›ajax‹ is me­re­ly the­re to pre­vent that

The throb­ber ele­ment uses this HTML co­de:

<img src="throb­ber.gif" class="throb­ber" />

You can set wrap­ping co­de using the ›wrap‹ op­tion.

You can crea­te throb­ber ima­ges using http://www.ajax­load.in­fo/.

Examp­les

  • $("#but­ton").throb­ber()
    Show a throb­ber when the but­ton is clicked, re­pla­cing the but­ton and stop­ping when all AJAX re­quests are com­ple­ted.
  • $("#div").throb­ber("dblclick", {ima­ge: "throb­ber_2.gif"})
    Show a throb­ber when #div is double-clicked, using a cu­stom throb­ber ima­ge.

Using the plu­gin is ea­sy:

$("#text").co­lum­ni­ze()

sets the con­tents of the DOM no­de with the ID ›text‹ in a two-co­lumn lay­out with ba­lan­ced co­lumn lengt­hs.

The plu­gin re­co­gni­zes dif­fe­rent op­ti­ons which are de­no­ted in cur­ly brackets.

Op­ti­ons

  • ba­lan­ce: ›true‹ if the co­lumn lengt­hs should be ba­lan­ced. ›fal­se‹ if the co­lumns should grow to the height of the con­tai­ning ele­ment. Default: ›true‹
  • co­lumn: The CSS class which should be app­lied to co­lumns. Default: ›co­lumn‹
  • co­lumns: The de­si­red num­ber of co­lumns if ba­lan­ce mo­de is on. Default: ›2‹
  • con­ti­nued: The CSS class which should be app­lied to DOM no­des which are con­ti­nued in the next co­lumn. Default: ›con­ti­nued‹

Tips

If ba­lan­ce mo­de is off, the ele­ment to which the co­lumn lay­out should be app­lied has to de­fi­ne a ma­xi­mum height via the CSS pro­per­ty ›max-height‹. The co­lumns will then grow to at most this height.

If ba­lan­ce mo­de is on, the ma­xi­mum height is ta­ken in­to ac­count, too. If ba­lan­cing the co­lumn lengt­hs would ex­ceed the ma­xi­mum height the plu­gin au­to­ma­ti­cal­ly di­sables ba­lan­ce mo­de. In this ca­se, the plu­gin crea­tes mo­re co­lumns than spe­ci­fied in the co­lumns op­tion.

The co­lumn wid­th is de­ri­ved from the CSS pro­per­ties of the co­lumns. You can con­trol the wid­th using the CSS class spe­ci­fied in the co­lumns op­tion.. Ty­pi­cal pro­per­ties for a co­lumn are the fol­lo­wi­ng:

float: left
wid­th: 200px
mar­gin-right: 1em

For a be­au­ti­ful lay­out it is re­com­men­ded to use the CSS pro­per­ty ›li­ne-height‹. By set­ting the li­ne height ex­pli­cit­ly and cal­cu­la­te all ver­ti­cal di­stan­ces as mul­tip­les of the li­ne height you en­su­re that all ba­se­li­nes are ali­gned to the sa­me grid.

Examp­les

  • $("#text").co­lum­ni­ze({co­lumns: 3})
    Three co­lumns with ba­lan­ced co­lumn lengt­hs.
  • $("#text").co­lum­ni­ze({co­lumns: 3, ba­lan­ced: fal­se})
    Three co­lumns with ba­lan­ced co­lumn lengt­hs if the co­lumn lengt­hs do not ex­ceed the ma­xi­mum height of the con­tai­ning ele­ment. In this ca­se, the plu­gin aban­d­ons the li­mi­ta­tion to three co­lumns and crea­tes as ma­ny co­lumns as nee­ded for the text.
  • $("#text").co­lum­ni­ze({ba­lan­ced: fal­se})
    Co­lumns grow un­til the ma­xi­mum height of the con­tai­ning ele­ment. The num­ber of co­lumns is de­ter­mi­ned by the amount of text.

Li­cen­se

jQue­ry Co­lum­ni­ze is a con­tri­bu­tion to the jQue­ry com­mu­ni­ty and is the­re­fo­re dis­tri­bu­ted as open sour­ce soft­wa­re. The plu­gin is li­cen­sed un­der the GNU Les­ser Ge­ne­ral Pu­blic Li­cen­se.

Dow­n­load

Plea­se go to the pro­ject web­si­te in the jQue­ry plu­gin re­po­si­to­ry to dow­n­load the la­test re­lea­se.

--> website