FieldtypeRuntimeMarkup by kongondo

Allows rendering of custom markup within page editor and frontend via custom PHP snippet set in the field.

FieldtypeRuntimeMarkup

This module allows for custom markup to be dynamically (PHP) generated and output within a page's edit screen (in Admin). Optionally, JavaScript and CSS files can be added to target the output markup (or any other markup on the page).

The value for the Fieldtype is generated at runtime. No data is saved in the database. The accompanying InputfieldRuntimeMarkup is only used to render/display the markup in the page edit screen.

The field's value is accessible from the ProcessWire API in the frontend like any other field, i.e. it has access to $page and $pages.

Screenshots


Backend

screenshot1.png

screenshot2.png

Frontend

screenshot3.png

Install


  1. Copy the files for this module to /site/modules/FieldtypeRuntimeMarkup/ OR if running later versions of ProcessWire, install directly from the Modules screen.
  2. In admin: Modules > Check for new modules. Install Fieldtype > RuntimeMarkup.
  3. Create a new field of type RuntimeMarkup, and name it whatever you want. In our examples, we named it "runtime_markup".
  4. Head over to your field's Details tab.
  5. Complete the how to specify your PHP code option. It is recommended to use the Render PHP files option. Otherwise, enter your custom PHP code in the PHP code textarea.
  6. If rendering PHP files, fill in the settings for rendering PHP files. It is possible to render only 1 PHP file if it has an identical name to your field. If you wish to render more than one PHP file and/or your file has a different name to your field, select that option and enter comma-separated names/paths of those PHP files. Do the same for the JavaScript and CSS files sections if you wish to add scripts and style files. Please note that these JavaScript and CSS files can also specified if you are using the paste PHP code option.
  7. You will also need to specify your files' root path. Only /site/templates/ and /site/modules/ are allowed. Your specified files will need to descend from the specified root. It is OK for them to be in sub-folders. If that is the case, enter the relative path, for example includes/my-file, my-file.inc, etc.
  8. Please note that .php, .js and .css extensions are assumed for respective file types, so do not need to be entered.
  9. If you chose to paste custom PHP code, this must be valid PHP code and must ONLY return a string or integer. Anything else (e.g. object or array) will result in an error.

When done, add the field to a template at a desired location. For instance, if you want your markup to be rendered before all other fields when editing a page using that template, you would make sure your RuntimeMarkup field was at the very top of the list of fields in your template. Edit a page using that template to see the returned value. If errors are found, these will be displayed.

API + Usage


Backend (Admin-side)

Render PHP File(s)

This is the recommended way to use this Fieldtype. Using this option, you will be able to easily edit your PHP file(s) in the comfort of your favourite code editor. The PHP file will be rendered using ProcessWire's wireRenderFile() method. The Fieldtype will pass $page and $pages variables to the rendered file, hence you will be able to use those as normal in the PHP file being rendered.

A $page example.

echo $page->title;// will echo the title of the page being edited

A $pages->find() example.

$articles = $pages->find('template=articles, limit=5');

$out = '<ol class="articles">';
foreach ($articles as $article) $out .= '<li>' . $article->title . '</li>';
$out .= '</ol>';

echo $out;

Of course, you will want to do something more meaningful. For instance, find pages which have a certain field empty. Loop through the pages create modal links to them. You will then be able to edit those pages in a modal window. In addition, you can target the unordered list using its CSS class in your JavaScript and/or CSS.

This is only one example. You can be as complex or imaginative as you want with this Fieldtype!

Paste PHP Code Option

If using the paste PHP code option, enter your custom PHP snippet in the Details tab of your field. Your code can be as simple or as complicated as you want as long as in the end you return a value that is not an array or an object or anything other than a string/integer.

FieldtypeRuntimeMarkup has access to $page (the current page being edited/viewed) and $pages.

A very simple example.

return 'Hello';

Simple example.

return $page->title;

Simple example with markup.

return '<h2>' . $page->title . '</h2>';

Another simple example with markup.

$out = '<h1>hello ';
$out .= $page->title;
$out .= '</h1>';
return $out;

A more advanced example.

$p = $pages->get('/about-us/')->child('sort=random');
return '<p>' . $p->title . '</p>';

An even more complex example.

$str ='';
if($page->name == 'about-us') {
  $p = $page->children->last();
  $str = "<h2><a href='{$p->url}'>{$p->title}</a></h2>";
}

else {
  $str = "<h2><a href='{$page->url}'>{$page->title}</a></h2>";
}

return $str;

JavaScript and CSS


You can optionally use JavaScript and CSS files by specifying these in the field's settings. If you wish, you can also use the included but blank InputfieldRuntimeMarkup.css and InputfieldRuntimeMarkup.js files to add styles and scripts respectively to customise your rendered markup in the page edit in the admin, i.e. the rendered InputfieldRuntimeMarkup. This is not recommended though as those files will be overwritten when you update the module.

How to access the value of RuntimeMarkup in the frontend

Please note that this is only available when you use the paste PHP code option.

Access the field on this page like any other field.

echo $page->runtime_markup;

Access the field on another page like any other field.

echo $pages->get('/about-us/')->runtime_markup;

Warnings and Considerations


  • Although access to ProcessWire's Fields' admin pages is only available to Superusers, if you use the paste PHP option, this Fieldtype will evaluate and run the custom PHP code entered and saved in the field's settings (Details tab). Utmost care should therefore be taken in making sure your code does not perform any CRUD operations (unless of course that's intentional). The same is true if using the render PHP file option.
  • The value for this Fieldtype is generated at runtime and thus no data is stored in the database. This means that you cannot directly query a RuntimeMarkup field from $pages->find().

Changelog


Version 0.0.6

Code refactoring for better methods sharing.

Version 0.0.5

  1. Removed module's CSS and JS files. They are empty and not required.
  2. Switched to $files->render() instead of wireRenderFile().
  3. Added option to check for an optionally use InputfieldAceExtended for code highlighting in PHP custom code textarea.
  4. Added option to specify number of rows for PHP custom code textarea.
  5. Refactored code to prevent any unnecessary re-rendering of output, thanks @adrianbj.
  6. Removed option to search for files to render in this modules folder.
  7. Changed module license to MIT.

Version 0.0.4

Enhancements to support for rendering PHP, CSS and JavaScript files.

Version 0.0.3

Added support for rendering PHP, CSS and JavaScript files.

Version 0.0.2

Added markupValue() method for correctly rendering markup output in listers.

Version 0.0.1

Initial Release.

Resources


Support Forum

License


GPL(2)

Credits


This module was sponsored by Andrey Valiev

Install and use modules at your own risk. Always have a site and database backup before installing new modules.

Twitter updates

  • ProcessWire 3.0.187: This week we have some very useful new additions to both the core Repeater Fieldtype and the ProFields Repeater Matrix Fieldtype. This post covers all the details along with a couple of brief demonstration videos— More
    22 October 2021
  • ProcessWire 3.0.185 (dev) core updates, plus new Session Allow module— More
    17 September 2021
  • Three new ProcessWire Textformatter modules: Find/Replace, Markdown in Markup, and Emoji— More
    3 September 2021

Newest forum posts

Latest news

  • ProcessWire Weekly #389
    The 389th issue of ProcessWire Weekly we'll check out the latest core updates, introduce the Session Viewer module, and more. Read on!
    Weekly.pw / 23 October 2021
  • New Repeater and Repeater Matrix features
    This week we have some very useful new additions to both the core Repeater Fieldtype and the ProFields Repeater Matrix Fieldtype. This post covers all the details along with a couple of brief demonstration videos. 
    Blog / 22 October 2021
  • Subscribe to weekly ProcessWire news

“ProcessWire is like a breath of fresh air. So powerful yet simple to build with and customise, and web editors love it too.” —Margaret Chatwin, Web developer