[pmwiki-users] PmWiki Clipboard extension
J. Meijer
commentgg at hotmail.com
Fri Dec 2 12:55:37 CST 2005
!> PmWiki Clipboard extension
Some time ago I posted the Clipboard extension to the Cookbook. Pm recently
commented it asking how it differs from the (:include:). In the mean time
I've upgraded the script a bit and I think the ideas are really worth
presenting.
! Basic functionality
The clipboard defines the capability to cut, copy and paste 'clips'. A
source page needs to define a clip, using (:cut:) or (:copy:) and the
destination page can (:paste:) it.
A clip is any text, and it is interpreted as a number of lines, f.e. this
defines clip 'pagemenu':
(:cut pagemenu:)
* PageMenu item1
* PageMenu item2
(:cutend:)
It defines 2 entries that need to go into the SideBar when this page is
displayed. The sidebar is expected to have this directive:
(:paste pagemenu:)
A similar (but less flexible) result could have been achieved by writing:
(:include {$Group}.{$Page} lines=2:)
The main difference of course being that the include would fix the source
page while (:paste:) doesn't do such an assumption, the clip can come from
any source. Using clips a default pagemenu-clip can be defined by a
groupheader. As long as the page displayed doesn't define a clip, that clip
would be displayed.
! Advanced options
Cutting and pasting are distinctly different operations, so each has its own
set of options.
<! Defining clips
The cut-syntax allows one to extract (include) clips from any page, or the
entire pagetext itself. The result is processed just like in the include
directive, so one can extract specific lines from within a clip.
Note: Clips can also be defined in an XLPage, providing a site-wide
'gallery' of clips. Additionally, simple clips can be passed through the
URL, allowing f.e. forms to post data directly into a clip.
<! Pasting clips
The paste directive/command/statement defines additional capabilities not
found in the include directive:
(:paste person id=Name:)
Search clip 'person' for a section named 'Name'.
Sections recognized are headers, lines of the format
Name: Patrick Michaud
or lines in simples tables with the left columns
being 'Name'.
(:paste RecentChanges extract=regular-expression:)
Transforms content of RecentChanges, retaining all text matched by
regular-expression, then pastes result.
(:paste RecentChanges sort:)
Gets RecentChanges, sorts it, then pastes it. Note:
markup confuses sorting, so be sure to use the
[[text -> link]] format for links.
(:paste pagemenu reverse:)
Reverses order of lines in clip 'pagemenu' and
pastes result. Use in combination with sort.
(:paste RecentChanges columns=2:)
Gets RecentChanges, format it into a table with
2 columns and pastes it.
(:paste RecentChanges list=enumerated:)
Gets RecentChanges, pastes it as an #enumerated list.
(:paste RecentChanges list=bullet:)
Gets RecentChanges, pastes it as a *bullet list.
Options can be combined at will, so many powerful effects can be achieved.
This is the basic functionality. It is modular, small, powerful and provides
processing capabilities I think many desire. It also reduces demand on the
(:if:) statement.
I think these properties make it a candidate for inclusion into the core.
Boldly stated the include-statement should be deprecated and replaced by a
(:paste:).
The code defines some additional options, but they may be considered
experimental, so I won't discuss them.
I also won't dicuss the (:for:) statement which allows 'mail-merging' a clip
into another, so for example photo-galleries (with a user-defined layout)
can be specified with a true minimum of code. This is an interesting but
advanced feature, so I'll leave it for a second take.
! Controlling CSS
A recent simplistic extension brings a happy capability: paste clips
directly into CSS and skin your pages on the fly. For example:
(:css:)
body { background-color:black; }
(:cssend:)
makes the page-container background black. The better way is to defines a
'Skin' group and have pages define a clip. F.e. page Skin.Black can contain
this:
body { background-color:black; }
Now the following statement does the same as the previous (:css:) statement:
(:skin Black:)
All such skins must be located in the $SkinCssGroup, by default set to
'Skin'. When $SkinCssGroup is set to fe 'ColorScheme', the syntax also
changes. Now you need to write:
(:colorscheme Black:)
So don't change the groupname ;-)
! Wrapping up
I'm happy with the capabilities, they really complement the current PmWiki.
A rich set of ideas comes together and provides the basis for extended
clip-manipulation. The result is experimental but proved stable at the same
time. When integrated into the core the code would also enhance its API with
centralized capabilities to format lines into list-types and tables.
Seek enlightenment at:
http://www.pmwiki.org/wiki/Cookbook/ClipBoard
Goodluck.
jm
Attached: clipboard.php
-------------- next part --------------
A non-text attachment was scrubbed...
Name: clipboard.php
Type: application/octet-stream
Size: 9830 bytes
Desc: not available
Url : /pipermail/pmwiki-users/attachments/20051202/3d85f911/attachment.obj
More information about the pmwiki-users
mailing list