[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