(:Summary: Modifying the style of page contents:)
(:div class='rfloat frame' style='clear:right; font-size:small;':)
'''Contents'''
*[[#Basics|Basics]]
*[[#Scopes|Scopes]]
*[[#Attributes|Attributes]]
*[[#Styles|Enabling Styles]]
*[[#Shortcuts|Custom style shortcuts]]
*[[#predefined|Predefined Style Shortcuts]]
*[[#Examples|Examples]]
*[[#KnownIssues|Known Issues]]
*[[#SeeAlso|See Also]]
(:divend:)
(:Audience: authors (basic) :)

[[#Basics]]
!! Wiki style basics

[[Wiki styles]] allow authors to modify the color and other styling attributes of a page's contents.  
A wikistyle is written using percent-signs, as in %red%[@%red%@]%% or %bgcolor=lightblue%[@%bgcolor=lightblue%@]%%.

!!! Text color and font
The most basic use of wiki styles is to change text attributes such as color, background color, and font.  
PmWiki defines several wikistyles for changing the text color to [=%black%, %white%, %red%, %yellow%, %blue%, %gray%, %silver%, %maroon%, %green%, %navy%, and %purple%=].

(:markup class=horiz:)
The basket contains %red% apples, %blue% blueberries, %purple% eggplant, %green% limes, %% and more.
(:markupend:)

For colors other than the predefined colors, use the [@%color=...%@] wikistyle.  (Note: RGB colors (#rrggbb) should always be specified with lowercase letters to avoid [[WikiWord]] conflicts.)

(:markup class=horiz:)
I'd like to have some %color=#ff7f00% tangerines%%,  too!
(:markupend:)

To change the background color, use [@%bgcolor=...%@] as a wikistyle:


(:markup class=horiz:)
This sentence contains %bgcolor=green yellow% yellow text on a green background.
(:markupend:)

See [[(PmWiki:)Wiki Style Colors]] for more color help.

!!!Text justification
Styles are used to control the text justification

(:markup class=horiz:)
%center% This text is centered. 

%right% Right justified.
(:markupend:)

and to create floating text:

(:markup class=horiz:)
%rfloat% This text floats to the right

%rframe% floats to the right with a frame

Lorem ipsum dolor sit amet, consectetuer sadipscing elitr
(:markupend:)


[[#Scopes]]
!! Scopes

Wikistyles can also specify a ''scope''; with no scope, the style is applied to any text that follows up to the next wikistyle specification or the end of the paragraph, whichever comes first. The '''apply=''' attribute and its shortcuts allow to change the scope as follows:

||border=1 cellpadding=3 cellspacing=0
||apply attribute ||shortcut ||style applies to... ||
||[@%apply=img ...%@] ||- ||any image that ''follows''||
||[@%apply=p ...%@] ||[@%p ...%@] ||the current paragraph||
||[@%apply=pre ...%@] ||- ||the current preformatted text||
||[@%apply=list ...%@] ||[@%list ...%@] ||the current list||
||[@%apply=item ...%@] ||[@%item ...%@] ||the current list item||
||[@%apply=div ...%@] ||- ||the current div||
||[@%apply=block ...%@] ||[@%block ...%@] ||to the current block, whether it's a paragraph, list, list item, heading, or division.||

thus '''[@%p color=blue%@]''' is the same as '''[@%apply=p color=blue%@]''', and '''[@%list ROMAN%@]''' is the same as '''[@%apply=list list-style=upper-roman%@]'''.

Some [[#predefined|predefined style shortcuts]] also make use of apply, thus '''[@%right%@]''' is a shortcut for '''[@%text-align=right apply=block%@]'''.

Example: Apply a style to a paragraph:
(:markup:)
%p bgcolor=#ffeeee% The wikistyle specification at the beginning of this line applies to the entire paragraph, even if there are %blue% other wikistyle specifications %% in the middle of the paragraph.
(:markupend:)

Wiki styles can also be applied to [[PmWiki/tables]] and [[PmWiki/table directives]]:
(:markup class=horiz:)
||class="green" style="font-style:italic; border:1px solid blue; background-color:#ffffcc"
||Everything after the above line is styled with green italic text, ||
|| ||
||This includes ||
||    preformatted text ||
||* lists ||
||-> indented items ||
(:markupend:)

(:markup class=horiz:)
(:table class="green" style="font-style:italic; border:1px solid blue; background-color:#ffffcc":)
(:cellnr:)
Everything after the above line is styled with green italic text,

This includes
    preformatted text
* lists
-> indented items
(:tableend:)
(:markupend:)


The '''[@>>style<<@]''' block can be used to apply a wikistyle to a large block of items.  
The style is applied until the next [@>><<@] is encountered.

(:markup class=horiz:)
>>blue font-style:italic bgcolor=#ffffcc<<
Everything after the above line is styled with blue italic text,

This includes
    preformatted text
* lists
-> indented items
>><<
(:markupend:)

The '''[@(:div style:)@]''' works in ''almost'' the same way as [@>>style<<@],
but the style information is encapsulated in a @@style=""@@ attribute and nested div blocks are possible.
(:markup class=horiz:)
(:div class="green" style="font-style:italic; border:1px solid blue; background-color:#ffffcc":)
Everything after the above line is styled with green italic text,

This includes
    preformatted text
* lists
-> indented items
(:divend:)
(:markupend:)

(:markup class=horiz:)
(:div1 style="font-style:italic; background-color:#ffffcc":)
outer style
(:div2 style="color:red; background-color:lightblue":)
nested style
(:div2end:)
again outer style
(:div1end:)
(:markupend:)


'''Caveat''': An applied wikistyle will only take effect if it's on the
line that starts the thing it's supposed to modify.  In other
words, a wikistyle in the third markup line of a paragraph
can't change the attributes of the paragraph:

(:markup class=horiz:) 
after the first line of the paragraph,
we try to %apply=p color=blue% change color.
This does't work because the style comes
(:markupend:)

(:markup class=horiz:)
However, this %p color=red% paragraph
''will'' be in red because its block style does
occur in the first line of its text.
(:markupend:)

(:markup class=horiz:) 
* Here's a list item
* %list red% Oops, too late to affect the list!
(:markupend:)


[[#Attributes]]
!! Wikistyle attributes

The style attributes recognized within a wikistyle specification are:

    ------------ CSS -------------          --HTML--
    color               bgcolor             class 
    background-color    margin              id
    text-align          padding             hspace
    text-decoration     border              vspace
    font-size           float               target
    font-family         list-style          rel
    font-weight         width*              accesskey
    font-style          height*             value
    display

    Special: define, apply

The attributes in the first two columns correspond to the ''[[cascading style sheet -> http://blooberry.com/indexdot/css/propindex/all.htm]]'' (CSS) properties of the same name.  The attributes in the last column apply only to specific items:

* '''[@class=@]''' and '''[@id=@]''' assign a CSS class or identifier to an HTML element
* '''[@target=name@]''' opens links that follow in a browser window called "name"
* '''[@rel=name@]''' in a link identifies the relationship of a target page
* '''[@accesskey=x@]''' uses 'x' as a shortcut key for the link that follows
* '''[@value=9@]''' sets the number of the current ordered list item

[=*=] The width and height attributes have asterisks because they are handled specially for <img .../> tags.  If used by themselves (i.e., without anything providing an "apply=" parameter to the wikistyle), then they set the 'width=' and 'height=' attributes of any <img ... /> tags that follow. Otherwise, they set the 'width:' and 'height:' properties of the element being styled.

[[#Styles]]
!! Enabling Styles
Styles not listed above can be enabled by a PmWiki Administrator by modifying the local/config.php file.  
For instance to enable the "line-height" style attribute add the line 

->$WikiStyleCSS[] = 'line-height';

to the local/config.php file.

[[#Shortcuts]]
!! Custom style shortcuts

The '''[@define=@]''' attribute can be used to assign a shorthand name to any wikistyle specification.\\  
This shorthand name can then be reused in later wikistyle specifications.

(:markup class=horiz:)
%define=box block bgcolor=#ddddff border="2px dotted blue"%

%box% [@some sort of text@]

%box font-weight=bold color=green% [@some sort of text@]
(:markupend:)

-< '''Tip:'''  It's often a good idea to put common style definitions into [[Group Header(s)]] pages so that they can be shared among multiple pages in a group.  Or, the [[wiki administrator]] can predefine styles site-wide as a [[local customization(s)]] (see [[Custom Wiki Styles]]).

-< '''Tip:''' Use custom style definitions to associate meanings with text instead of just colors.  For example, if warnings are to be displayed as green text, set [@%define=warn green%@] and then use [@%warn%@] instead of [@%green%@] in the document.  Then, if you later decide that warnings should be styled differently, it's much easier to change the (one) definition than many occurrences of [@%green%@] in the text.

-< '''Tip:''' Any undefined WikiStyle is automatically treated as a request for a class, thus [@%pre%@] is the same as saying [@%class=pre%@].

!![[#predefined]] Predefined style shortcuts

PmWiki defines a number of style shortcuts.

* Text colors: %black%black%%, %white bgcolor=black%white%%, %red%red%%, %yellow%yellow%%, %blue%blue%%, %gray%gray%%, %silver%silver%%, %maroon%maroon%%, %green%green%%, %navy%navy%%, %purple%purple%%  (shortcut for [@%color=...%@])
* Justification: [@%center%@] and [@%right%@]
* Images and boxes
** Floating left or right: [@%rfloat%@] and [@%lfloat%@]
** Framed items: [@%frame%@], [@%rframe%@], and [@%lframe%@]
** Thumbnail sizing: [@%thumb%@]
* Open link in new window: [@%newwin%@]  (shortcut for [@%target=_blank%@])
* Comments: [@%comment%@] (shortcut for [@%display=none%@])
* Ordered lists: [@%decimal%@], [@%roman%@], [@%ROMAN%@], [@%alpha%@], [@%ALPHA%@] (see also Cookbook:OutlineLists)

[[#Examples]]
!! Examples

[[Wiki Style Examples]] contains a number of examples of ways to use wikistyles in pages.

[[#KnownIssues]]
!! Known Issues
* Percents in style definitions (like: [@%block width=50% %@]) require the use of "pct" instead of "%".
* If you specify multiple values for an attribute, like @@border="2px solid blue"@@ make sure you place the values in quotes.
* Be sure to use lowercase letters for red-green-blue hex colors, [@%color=#aa3333%@] will work, [@%color=#AA3333%@] may not.

[[#SeeAlso]]
!!See Also
* [[PmWiki/Custom Wiki Styles]] {PmWiki/CustomWikiStyles$:Summary}
* [[PmWiki:List Styles]]        {PmWiki/ListStyles$:Summary}

>>faq<< [[#faq]]
Q: 
A: