!> 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/Cookbook/ClipBoard


Goodluck.

jm