ClassTags

Summary: Markup for Edit-Mode to give a block of content a named class, for use with CSS, JS, or to add content-folding, and lots more!
Version: 2020.09.26
Prerequisites: None, but for Content-Folding requires: UnToggle
Status: Stable
Maintainer: Kirk Siqveland
License: (Apache 2.0|BSD-3-clause|BSD-2-clause|GPL|LGPL|MIT|MPL-2.0|CDDL-1.0|EPL-1.0) - OpenSourceLicenses Cookbook:Cookbook Licenses
Categories: Layout, Links, CSS, Markup
Users: (view? / edit)
Discussion: ClassTags-Talk

Questions answered by this recipe:

It has been pointed out that this code is not necessary, as these features are already build into PMWiki:

- See WikiStyles#blocks. For standard (:div ..:) markup see also BlockMarkup - It was an interesting learning exercise for me all the same to write this, so I leave it here in case anyone can use it for other purposes.


  • How do I apply styles and java-script to a block of text in my page, from Edit-Mode?
  • How can I make page content fold-able (hide or un-hide with a mouse-click) while in Edit-Mode?
  • How can I use Markup to insert images with the "toggle" class, -
    specifically for use with UnToggle to make a toggle-button?

This is a Swiss Army Knife for CSS, HTML and JS:

  • Wiki-editors can use simple Markup to put selected text into a div with a user defined class.
  • That means if you have CSS or javascript you want available at Edit time you can!
  • Use this to Make the UnToggle recipe work on-the-fly for text-folding, code-folding etc.
  • In fact, you can put any block of text or other content, inside of a div with a User Named Class: say, for custom styling using css
  • Likewise, having defined a div with a specific name, you can interact with it using JS.
  • Also, See the notes below on updating the UnToggle recipe to work from Markup,
  • including adding a clickable Toggle Image.

All sections are optional, you can remove those that do not apply to your recipe, and add new ones.

Description

Adds Markup to allow a selected block of content to be given a user-defined class name from Edit Mode.
Usefull with UnToggle to create folded-content!
More specifically, the selected block is placed inside a <div>, which optionally, can be given any name you like!

Thus, if you have css or javascript code that references a class name , from edit-mode in your Wiki, you can create a <div>
with that class name, so it will now be governed by the css or script. Such as the toggle mode, or to create a block with a
special background or font, or maybe one that stays in one place on the screen, use your imagination!

The nice thing here is the Editor can only use code you have already built-in, they cannot add any dangerous code.

Installation

If you just want to add the ClassTag Markup you need the following PHP:
You have several options -
1. Copy and Paste the ClassTag PHP Code below into your Skin.php file.
2. Or: Make a text file named "classtags.php" in your cookbook directory, and add a line to your config.php file

e.g. create "https://www.mywikisite.org/pmwiki/cookbook/classtags.php"
Copy and Paste the ClassTag PHP Code below into that file, and then
add the following line to your /pmwiki/local/config.php file :
include_once("$FarmD/cookbook/classtags.php");

(Here you can download the full file classtags.phpΔ )



## Uncomment the next line if used in classtags.php
#<?php if (!defined('PmWiki')) exit(); 

##----------------->>  ClassTags for PmWiki  <<--------------------------- 
  # Written for PmWiki in 2020 by Kirk Siqveland - www.CyberTamer.com
  # The following text is into the Public domain.
  # This code will add Markup to your normal Edit interface
#
  # This can stand alone, or be used with the UnToggle Recipe
  # To create folding Text and Content


## Re-class-ify PHP code:
## This will enclose Marked-Up Content in a <div> named 'class-tag' by adding markup at the beginning 
## and end of the selection just like we use for bold or italics, but instead of quote marks we 
## Open with  {|  and then close with  |}
## From your PMWiki edit mode you would enter something something like this:
##    {|Click Me!|}

Markup( 'classtag',
    'directives',
    '/\\{\\|(.*?)\\|\\}/',
    "<div class='class-tag'>$1</div>"); 
## Then if you inspect the page in View mode for its html it would look something like this: 
##
##    <div class='class-tag'>Click Me!</div>


## For a custom class name, which allows direct application of CSS or JS, we use the same code but with a twist:
## To make it work, we add a segment to the Markup declaring the Custom Class-Name:
## We start with  {|  but add a name - with no spaces, followed by two pipes || after that it is the same as ClassTag.
##
##    {|MyNewClass||Click Me!|}

## By running this second Markup routine, we replace the newly inserted "class-tag" class name with the user declared name.
Markup( 'classmod',
    'directives',
    "/'class-tag'>(.*?)\\|\\|/",
    '"$1">');
## Now the html for the page would end up like this: 
##
##    <div class='MyNewClass'>Click Me!</div>


## Finally if you are using UnToggle for Folding Text / Content we bracket the Content we want to fold with  {:|  and  |:}
## Note this must be IMMEDIATELY after the Click Me! (or whatever toggle-text you use for the toggle)
## Again, from the Edit Mode, we place the text/Content inside the markup block:
## {:|Lorem ipsum ... est laborum.|:}
Markup( 'toggleclass',
    'directives',
    '/\\{:\\|(.*?)\\|:\\}/',
    "<div class='toggle'>$1</div>");

## If we put it all together it would look like this in the Edit Mode:

##      {|toggle||Click Me!|}{:|First-Click: you see me... Next-Click: You don't!|:}
## Notice you can not add a line break in Edit mode or it won't work, but we will add one for you in View mode.


## Finally we can Toggle with an Image: - the address I use here points to what I call a foldmark
##  foldmark1.png is black for light backgrounds, if you change it to foldmark2.png you get a yellow mark for dark backgrounds.
##  I intend to also have foldmark3.png in cyan, and foldmark4.png in pale green, foldmark5.png in white and foldmark6.png in red.
Markup('foldmark1', 'directives',
  '/\\(:foldmark1:\\)/',
  Keep("<img src='https://www.cybertamer.com/vbapex/media/foldmark1.png' alt='text pleat marker' style='display: inline-block;' class='toggle'>") );


... and you are done!

Configuration

None needed, but if you want the default class name to be something other than 'class-tag' just change the php code.

Usage

On any page, in Edit mode, use the markup "{|" to start a block and "|}" to end a block. e.g.:

{|Here is the text I want placed in a <div> and given the class name 'class-tag'|}

Now if you want a custom name for a similar block of text use the same End Markup, and the same Start Markup but
followed immediately by the new class name to use ending with "||" e.g.:

{|foldingtext||Here is the text I want placed in a <div> and given the class name 'foldingtext'|}

And Finally if you are using UnToggle to make your folding content:

  • Start by using the markup "{:|" and "|:}" to surround the content you want folded.
  • Then immediately before that content add either,
    • Toggle Text by typing the following: {|toggle||The Visible Text to Click|:}
    • Or: Add a toggle icon with, using following: (:foldmark1:)
    Actually, you still need one more tweak to get that last bit to work, see Notes:

Notes

I wrote this code to be able to add content folding from an icon to my Wiki.
Since the UnToggle recipe already existed,

I just need to make this ClassTags Markup for hyper-text creation from the Edit Mode!

But, to add an image button, you need one more line in the javascript from UnToggle:
Add this to the bottom of the untoggle.js file, which you already added to your /pub directory.

toggleNextByTagAndClassName("img",'toggle');

NB! You will notice I hard coded the address of the image in the code above, you are welcome to use my images,
but it would be nice if you copy them to your own server.

I have made several of the foldmark 'icons', really images to use with the "toggle" class.\\ They have transparent backgrounds to blend with your page better.
* Foldmark1 is grayscale for use on a light background.

  • I'm making more to use on dark backgrounds, and with different colors.

They are available in my [(approve links) edit diff] directory
The images in that directory are now public domain.

To do / some day / maybe

If you have future plans or wishes for this recipe.

Change log / Release notes

Submitted to PmWiki 2020-09-26

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

UnToggle

Contributors

Comments

See discussion at ClassTags-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.