[pmwiki-users] Properties

Patrick R. Michaud pmichaud at pobox.com
Mon Dec 12 11:10:53 CST 2005


I'm thinking of adding something like Cookbook.Properties into the
core distribution, but want to get feedback (especially Dominique's)
on the markup, since what I'm thinking of using differs somewhat from
the recipe version.

At this stage this is just a proposal and not a commitment.  

* All pages can have properties, which are essentially "variables"
   that an author can set and use later in a page.  

* The basic form for setting a property is (:property name=value:).

* Multiple properties can be given in a single directive, thus
  (:property name1=value1 name2=value2:).

* To remove a property, one uses (:property -name:).  
  
* The markup {$property name} becomes the current value of the
  named property (if the property is not set, then nothing is displayed).
  We may end up with a shorter markup for this -- maybe {$$name},
  which would also work in skin templates and $...Fmt strings.

* The conditional  (:if property name 'has value':) is true if the named
  property exactly matches the given value.

* The conditional  (:if property name:) is true if the named property
  evaluates to a true value.

* The site administrator (or cookbook recipes) can designate that certain 
  named properties are saved directly into page files via a $SaveProperties 
  array.

* Three properties are predefined by PmWiki as saved properties:  title, 
  keywords, and description.  Thus the (:title:), (:keywords:), and 
  (:description:) directives become shortcut markups for doing the 
  equivalent of (:property title="...":), (:property keywords="...":), 
  and (:property description="...":).

* Saved properties can be used as ordering criteria in pagelists,
  thus  (:pagelist order=myprop:) would order the list according to
  the "myprop" saved property setting.

* We may also be able to use saved properties as filters, thus
  (:pagelist myprop=something:) would return only those pages
  that have a "myprop" value with "something" in it.

With the above in mind, we would get the following:

* DaveG's issue of displaying an author-specified WikiTrail in
  the header can be done with properties and no special markup
  rules.  By placing the following in the page template

      <!--markup:(:if property titletrail:)<<|[[{$$titletrail}]]|>>(:if:)-->

  the markup (:property titletrail "DIY":) would result in
  displaying the DIY trail in the page header.

* The "custom variables" in Cookbook.PageListTemplates could become 
  "properties" of the current page in the list, thus

      {$$prevname}       - previous page in list
      {$$nextname}       - next page in list
      {$$pagecount}      - current page count
      {$$grouppagecount} - count of pages in current group
      {$$groupcount}     - number of groups

* If we define a markup rule that treats markup lines of the form

      name: value

  as setting a property value (i.e., the same as (:property name="value":), 
  then capabilities such as PITS become almost trivial to implement, 
  including the ability to sort and filter based on properties in the 
  page markup.  Example property lines that could be of great benefit
  (we'll assume that properties are case-insensitive here, although that's
  not decided):

      Summary: this is the page's summary    # (allows {$$summary} )
      Created: 2005-08-26                    # (allows order=-created)
      Status: Closed                         # (allows summary=closed)
      Votes:  53024                          # (allows order=-votes)

* We could potentially define custom edit form input boxes that
  allow properties to be set and manipulated outside of the markup
  text (similar to what is done for Cookbook.EditTitle, but
  expanded to a larger set of allowed properties).

Comments, suggestions?

Pm




More information about the pmwiki-users mailing list