%audience% authors (basic)
!! Wikistyle basics

[[WikiStyles]] 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%@] or [@%bgcolor=blue%@].

The most basic use of wikistyles 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:) [=
The basket contains %red% apples, %blue% blueberries, %purple% eggplant, %green% limes, %% and more.
=]

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:) [=
I'd like to have some %color=#ff7f00% tangerines%%,  too!
=]

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

(:markup:) [=
This sentence contains %bgcolor=green yellow% yellow text on a green background. =]

See [[PmWiki:WikiStyleColors]] for more color help.

!! 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.  Including a scope changes the specification to apply to the whole paragraph ([@%p ...%@]), an entire list ([@%list ...%@]), an item within a list ([@%item ...%@]), or any block ([@%block ...%@]).  Those scopes are predefined shortcuts for the "apply=" attribute, which is discussed  [[#apply_to_blocks|below]].

(: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.
=]

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:) [=
>>blue font-style=italic bgcolor=#ffffcc<<
Everything after the above line is styled with blue italic text,

This includes
    preformatted text
* lists
-> indented items
>><<
=]

!! 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://www.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.


!! Applying wikistyles to blocks [[#apply_to_blocks]]

Normally a wikistyle applies to a span of (inline) text, but
the apply= attribute allows a style to be applied to something
else.  The predefined apply= values are:

||border=1 cellpadding=3 cellspacing=0
||apply=img ||apply the style to any image that follows|| ||
||apply=p ||apply the style to the current paragraph||* ||
||apply=pre ||apply the style to the current preformatted text|| ||
||apply=list ||apply the style to the current list||* ||
||apply=item ||apply the style to the current list item||* ||
||apply=div ||apply the style to the current div|| ||
||apply=block ||apply the style to the current block,\\
whether it's a paragraph, list, list item,\\
heading, or division.||* ||

The starred items also have wikistyle shortcuts already defined,
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 wikistyle shortcuts also make use of apply, thus [@%right%@]
is a shortcut for [@%text-align=right apply=block%@].

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:) [=
here is some text in
a paragraph and if
we try to %apply=p color=blue% change
the color of the paragraph in the middle
it won't work because the style comes
after the paragraph has already been started.=]

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

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


!! Enabling Styles
Styles not listed above can be enabled by a PMWiki Adminstrator 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.

!! 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:) [=
%define=box block bgcolor=#ddddff border="2px dotted blue"%

%box% [@
$ echo "Hello world"
Hello World
$ exit
@]

%box font-weight=bold color=green% [@
$ echo "I said, HELLO"
@]=]

'''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 [[CustomWikiStyles]]).

'''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, white, red, yellow, blue, gray, silver, maroon, green, navy, 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

[[WikiStyleExamples]] contains a number of examples of ways to use wikistyles in pages.

!! Known Issues
* Percents in style definitions (like: [@%block width=50% %@]) require the use of "pct" instead of "%".

!!See Also
[[PmWiki/Custom Wiki Styles]]

%trail% <<|[[Documentation Index]]|>>

>>faq<< [[#faq]]

Q:  Some of my colors aren't working!  For example, [@%color=#AAAAAA%@] works, but [@%color=#AA3333%@] doesn't work.  What's wrong?

A:  Be sure to use lowercase letters for rgb hex colors, otherwise PmWiki may mistake the color value for a [[WikiWord]].