ryan

Hanna Code

328 posts in this topic

Easily insert any complex HTML, Javascript or PHP output in your ProcessWire content by creating your own Hanna code tags.
This module is based loosely on the WordPress Hana Code Insert plugin.
 
post-2-0-11674600-1370199246_thumb.png
 
post-2-0-50116800-1370199239_thumb.png
 
A Hanna code tag looks like [[hello_world]]. A Hanna code tag with attributes looks like [[hello_world foo=bar" bar="foo]] using HTML style attributes or [[hello_world foo=bar, bar=foo]] using ProcessWire selector style attributes. After installing the module, you define your Hanna codes in Setup > Hanna Code.
 
These Hanna codes that you define can then be entered within your body copy (or other text where you allow) and they will be replaced with the values defined or generated by your Hanna code. A common use case is to embed scripts or other bits of HTML or codes that would usually be stripped out by an editor like TinyMCE. However, Hanna codes can be more than just static snippets--they can be dynamic PHP or Javascript that outputs different things according to the request. PHP-based Hanna codes have access to the entire ProcessWire API.
 
Hanna code accepts named attributes in the tag that can be passed as variables to PHP and Javascript Hanna codes. These attributes can be specified either in HTML attribute format or ProcessWire selector format. In either case, quotes should be used around the attribute value when the value contains whitespace or a comma.
 
How to install
  • Place the module files in /site/modules/TextformatterHannaCode/
  • In your admin, click Modules > Check for new modules
  • Click install for TextformatterHannaCode
  • Now to go Setup > Fields and locate the Textarea field(s) that you want to use Hanna codes with ("body" for instance). 
  • When editing the field, click the details tab, and select "Hanna Code" as the Textformatter. Save.
  • Now go to Setup > Hanna Code and start defining your Hanna Codes! You may want to use one of the examples from this document to get started.
Tag format
 
Below is a Hanna code tag named hello_world with no attributes. If you pasted this into your body copy, you would get whatever the replacement value is that you defined.
[[hello_world]]
Below is a Hanna code tag named hello_world being passed attributes of foo, bar and foobar. If this were a PHP-based Hanna code, it would receive the variables $foo, $bar and $foobar:
[[hello_world foo="bar" bar="foo" foobar="foo bar"]]
Below is the same Hanna code tag as above, but with attributes more like ProcessWire selectors. You can use whatever format you prefer. Just note that unlike regular ProcessWire selectors, quotes (single or double) are required around any value that has whitespace.
[[hello_world, foo=bar, bar=foo, foobar="foo bar"]] 
How to use
 
Please make sure that you have completed the How to install section first. Then in your admin, go to Setup > Hanna Codes.
 
Each Hanna code that you add has a type of either: Text/HTML, Javascript or PHP. The Text/HTML type is literally self explanatory in that your [[custom-tag]] is replaced with exactly the text you paste in. Anywhere that you type your [[custom-tag]] in your body copy will be replaced with exactly the static text you defined.
 
More power opens up with the Javascript and/or PHP types of codes. These codes execute at runtime and thus can contain specific logic to produce different results. In fact, PHP Hanna codes have access to the entire ProcessWire API and are executed in the same manner as template files. Your PHP-based Hanna code should simply "echo" or "print" the replacement value.
 
PHP example
  • Create a new Hanna code with the name "children".
  • Select "PHP" as the type.
  • Paste in the following for the code:
foreach($page->children as $child) {
  echo "<p><a href='$child->url'>$child->title</a>";
}
  • Now go and edit a page that has children. In the body copy, enter [[children]] in the place where you want the output to appear.
  • View the page, and you should see the rendered list of links to children.
PHP example, part 2
 
Now lets take the above example further...
  • Go back and edit your "children" Hanna code, as we are going to modify it to respond to a "parent" attribute. Change the code to this:
if(isset($parent)) {
  // If $parent is an ID or path, lets convert it to a Page
  $parent = $pages->get($parent);
} else {
  // otherwise lets assume the current page is the parent
  $parent = $page; 
}

foreach($parent->children as $child) {
  echo "<p><a href='$child->url'>$child->title</a>";
}
  • Go back and edit the page where you previously inserted the [[children]] tag, and change it to: [[children, parent=1]] (specifying the homepage) or [[children, parent=/path/to/some/parent/]] if you want to try something else.
  • View the page and you should now see it showing the children of the homepage (or of another parent you specified).
Please see the Javascript and PHP usage notes on the Hanna code entry screen.
 
Security
 
There are major security implications with a tool that will let you enter unfiltered text and code from your web browser. As a result, Hanna codes are meant for definition only by superusers and we recommend keeping it that way.
 
Download
 
Download the Hanna Code module from the ProcessWire modules page or from GitHub
33 people like this

Share this post


Link to post
Share on other sites

Just a note to all MODx'ers - I think this is a nice way to transfer some snippets/chunks to ProcessWire as well if people want to go down that route and have some they used to use in body text. Obviously it's not quite the same thing (potentially more powerful depending on your needs), but anything that helps make a transition easier is good in my book :)

Very useful, powerful module ryan!

3 people like this

Share this post


Link to post
Share on other sites

Wow! Great module, Ryan.

Gonna create a bunch of snippets for quick prototyping and trying things. Expect a new wave of MODx'ers on the forum. These folks love using code snippents the way Hanna Code allows it!

Edit: Pete, we had almost the same thought!

1 person likes this

Share this post


Link to post
Share on other sites

Wow! Nice one; you've been busy!

Yes, there have been two or three questions from MODx'ers in the forums about something like this - the ability to randomly, directly call snippets, chunks and TVs within the body field/area in TinyMCE. Previously they've been pointed to shortcodes and tag parser. Hanna is certainly more powerful and would solve this issue easily.

I can't wait to see the creative ways people use this :rolleyes: .

Thx for the module!

2 people like this

Share this post


Link to post
Share on other sites

Ryan,

This is great — thank you!

Quite a lot happening around here for a Sunday.

:)

2 people like this

Share this post


Link to post
Share on other sites

Nice addition to the growing collection of very useful modules!

1 person likes this

Share this post


Link to post
Share on other sites

Looks like a very useful module, thanks for sharing it Ryan.

I just tried to install it using ModulesManager, and I can't install it right after downloading as it requires Textformatter module to be installed.

TemplateFile: Module ProcessHannaCode requires: TextformatterHannaCode

#0 [internal function]: Modules->___install('ProcessHannaCod...')...

Couldn't it be installed when installing the process module?

Edit: When I create a new hanna code and not enter a tag name and save I get an error and can't see the form.

1 person likes this

Share this post


Link to post
Share on other sites

This looks brilliant Ryan, thank you! There are parallels with a nice aspect of Textpattern here also, TXP 'Forms' (snippets). Brill! ^_^

1 person likes this

Share this post


Link to post
Share on other sites

Looks like a very useful module, thanks for sharing it Ryan.

I just tried to install it using ModulesManager, and I can't install it right after downloading as it requires Textformatter module to be installed.

TemplateFile: Module ProcessHannaCode requires: TextformatterHannaCode

#0 [internal function]: Modules->___install('ProcessHannaCod...')...

Couldn't it be installed when installing the process module?

Edit: When I create a new hanna code and not enter a tag name and save I get an error and can't see the form.

Works fine if you use default Module manager (PW's). You can only install via TextformatterHannaCode actually. Summary says this "Also Installs - ProcessHannaCode". The install button for  ProcessHannaCode is greyed out with the message "Requires - TextformatterHannaCode". ProcessHannaCode auto installs. Maybe something with ModulesManager?

@Ryan: The TextformatterHannaCode and ProcessHannaCode have the same name - "Hanna Code" in PW module manager. This can be confusing :) (but not a big deal).

post-894-0-28482800-1370266185_thumb.png

Share this post


Link to post
Share on other sites

@kongodo, but I don't use Modules page anymore :D I didn't see that the Textformatter is the mother module. At the end it got installed but it's confusing.

Of course it has to do with ModulesManager and the nature of the modules. Modules Manager doesn't know what modules are there and how to install. It takes the module "class name" that is entered on modules.processwire.com to create folder and installs the main module. It's all information I got from modules.processwire.com and there's no manifest, dependencies or lifecycle informations to modules in PW (which IMO is requires rather sooner than later)

For some reason it seems now Ryan has changed the module class name to "TextformatterHannaCode", and this should work better now. Though changing those settings "class name" is dangerous once the module is installed via ModulesManager, because there's actually two different folders for the same module.

Share this post


Link to post
Share on other sites
I just tried to install it using ModulesManager, and I can't install it right after downloading as it requires Textformatter module to be installed.

Sorry about that, I went back and forth on the name a couple times and ultimately entered the wrong class name in the modules directory. It should have been TextformatterHannaCode, not ProcessHannaCode. I have corrected that.

Edit: When I create a new hanna code and not enter a tag name and save I get an error and can't see the form.

I was throwing an exception when I shouldn't have. I'm pushing a correction for this. 

 The TextformatterHannaCode and ProcessHannaCode have the same name - "Hanna Code" in PW module manager. This can be confusing :) (but not a big deal).

Technically they are part of the same program "Hanna Code", even if that program has two modules. But I know what you mean. I'm adding "(Process)" to the Process one, just so that the two next to each other can be differentiated. 

Also, one more section I just added to the README:

Using Hanna Code from the API
 
If you want to populate Hanna Code from the API, you can do so using the render() method, like this:
$hanna = $modules->get('TextformatterHannaCode'); 
$page->body = $hanna->render($page->body); 
8 people like this

Share this post


Link to post
Share on other sites

Just posted version 0.0.2 that addresses the items above. It also adds an option that lets you specify whether the immediate surrounding HTML tag should be replaced with your Hanna Code output or not. For instance, if your [[hello-world]] Hanna Code output is "Hello World" and is applied to the body copy containing "<p>[[hello-world]]</p>" then you probably don't want it to replace the surrounding <p> tags. Whereas if your Hanna Code outputs block level elements like "<ul><li>Hello World</li></ul>" then you probably do want it to replace the surrounding <p> tags, otherwise you'd end up with some invalid markup like: <p><ul><li>Hello World</li></ul></p>.

2 people like this

Share this post


Link to post
Share on other sites

I have tested Hanna with single {, ( and [, i.e. 

(hello)
[hello]
{hello} 
They all work fine in both PHP and Text mode.

Ryan, are these OK or they could throw up issues? Thx.

Share this post


Link to post
Share on other sites

I think it would be really cool if there was and easy (JSON?) way to import/export hanna codes (all or single). Maybe then we could setup a subforum to share them.

Otherwise this is amazing, thanks Ryan.

Share this post


Link to post
Share on other sites

I think it would be really cool if there was and easy (JSON?) way to import/export hanna codes (all or single). Maybe then we could setup a subforum to share them.

Otherwise this is amazing, thanks Ryan.

/site/assets/cache/HannaCode/ :). The PHP are stored as PHP files

Share this post


Link to post
Share on other sites

Is it just me or is Hanna version 1.0.4 broken? It no longer works - it outputs the raw tag :(

Don't know what's happening but even older versions do not work any more. I'm stumped. Ideas? Using it on 2.3 stable

Edited by kongondo

Share this post


Link to post
Share on other sites

/site/assets/cache/HannaCode/ :). The PHP are stored as PHP files

Haha, thats cool, I guess I could've taken a look before posting. Though a spot to officially discuss these maybe couldn't hurt. :P

Share this post


Link to post
Share on other sites

Is it just me or is Hanna version 1.0.4 broken? It no longer works - it outputs the raw tag  :(

Don't know what's happening but even older versions do not work any more. I'm stumped. Ideas? Using it on 2.3 stable

It's working for me at least, though I did change some things about the regex's in 0.0.4, so I might need to get more info about the context. What's an example of a tag that isn't working for you? What is the markup that surrounds it in your text? Also can you double check that "Hanna Code" is set as the textformatter for your body field (or whatever field you are using it in) in Setup > Fields > body > details?

Ryan, are these OK or they could throw up issues? Thx.

It should be fine to set your open/close tags to be whatever you want. Though [this] is a fairly common text construct, where as [[this]] is not. So if your [this] ever conflicts with the name of a Hanna Code, that could cause some confusion. As a result, I think it may be preferable to use open/close tags that don't duplicate things you would usually see in written copy. 

Share this post


Link to post
Share on other sites

I'm going to give this a go for inserting galleries on the fly. I think this combined with responsive CSS is pretty powerful stuff.

Share this post


Link to post
Share on other sites

It's working for me at least, though I did change some things about the regex's in 0.0.4, so I might need to get more info about the context. What's an example of a tag that isn't working for you? What is the markup that surrounds it in your text? Also can you double check that "Hanna Code" is set as the textformatter for your body field (or whatever field you are using it in) in Setup > Fields > body > details?

Sorry; I just wasted your precious time! I forgot to set it as my textformatter after I made a couple of changes!  :-[ Thanks :)

Share this post


Link to post
Share on other sites

What kills me about this module is that Ryan literally decided to make it because I had something similar in WordPress and needed a substitute solution in ProcessWire (as part of the move of CMS Critic to PW) otherwise I'd have a ton of weird shortcodes in my posts for no reason. He made this module, imported my code from the other module (called Hana Code in WP) and named his Hanna Code (after his daughter) and Poof! a module is born.

I am insanely jealous of his mad php skills (but glad they can be bought!)

10 people like this

Share this post


Link to post
Share on other sites

And we have you to thank for hiring him in the first place which led us to Hanna Code! Thank you!

4 people like this

Share this post


Link to post
Share on other sites

Ryan, brilliant stuff!
 

For me it won't work in my first attempt and it took me some time to figure out my failure.

You can't use the identifier "name" for a variable.

[[gallery name="Test"]]

I didn't found any comments on this issue, so perhaps it helps.

2 people like this

Share this post


Link to post
Share on other sites

Kent, that's correct–I'll update the readme file. The term "name" is set to the name of the Hanna code. This is provided to the PHP so that it can check the name of the code, just in case it needs it. Likewise, it's preferable not to use any API variable name for your attributes either. 

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.

  • Similar Content

    • By ethfun
      I've created a Process Module, and its execute() function renders the HTML response to an AJAX request. The AJAX request is being made outside of the admin panel, and in all likelihood will be made by "guest" users.
      Within my ModuleName.info.json file, I have added these lines:
      "permission": "generate-thumbnails", "permissions": { "generate-thumbnails": "Generate Thumbnails" }, Then within the Admin panel, I gave guests access to run that module.
      Unless logged in, the response to the AJAX request is always the login form's HTML, rather than the HTML my execute() function creates.
      So two questions:
      Is it possible to give non-logged-in users the ability to run that function via the AJAX request, or Is there a better ProcessWire way to create HTML to use as an AJAX response? Thank you!
    • By Robin S
      I have had this module sitting in a 95% complete state for a while now and have finally made the push to get it out there. Thanks to @teppo for his Hanna Code Helper module which I referred to and borrowed from during development.
      http://modules.processwire.com/modules/hanna-code-dialog/
      https://github.com/Toutouwai/HannaCodeDialog
      HannaCodeDialog
      A module for ProcessWire CMS/CMF. Provides a number of enhancements for working with Hanna Code tags in CKEditor. The main enhancement is that Hanna tags in a CKEditor field may be double-clicked to edit their attributes using core ProcessWire inputfields in a modal dialog.
      Requires the Hanna Code module.
      Installation
      Install the HannaCodeDialog module using any of the normal methods.
      For any CKEditor field where you want the "Insert Hanna tag" dropdown menu to appear in the CKEditor toolbar, visit the field settings and add "HannaDropdown" to the "CKEditor Toolbar" settings field.
      Module configuration
      Visit the module configuration screen to set any of the following:
      Exclude prefix: Hanna tags named with this prefix will not appear in the CKEditor toolbar dropdown menu for Hanna tag insertion. Exclude Hanna tags: Hanna tags selected here will not appear in the CKEditor toolbar dropdown menu for Hanna tag insertion. Background colour of tag widgets: you can customise the background colour used for Hanna tags in CKEditor if you like. Dialog width: in pixels Dialog height: in pixels Features
      Insert tag from toolbar dropdown menu
      Place the cursor in the CKEditor window where you want to insert your Hanna tag, then select the tag from the "Insert Hanna tag" dropdown.

      Edit tag attributes in modal dialog
      Insert a tag using the dropdown or double-click an existing tag in the CKEditor window to edit the tag attributes in a modal dialog.

      Tags are widgets
      Hanna tags that have been inserted in a CKEditor window are "widgets" - they have a background colour for easy identification, are protected from accidental editing, and can be moved within the text by drag-and-drop.

      Options for tag attributes may be defined
      You can define options for a tag attribute so that editors must choose an option rather than type text. This is useful for when only certain strings are valid for an attribute and also has the benefit of avoiding typos.
      Add a new attribute for the Hanna tag, named the same as the existing attribute you want to add options for, followed by "__options". The options themselves are defined as a string, using a pipe character as a delimiter between options. Example for an existing attribute named "vegetables":
      vegetables__options=Spinach|Pumpkin|Celery|Tomato|Brussels Sprout|Potato You can define a default for an attribute as normal. Use a pipe delimiter if defining multiple options as the default, for example:
      vegetables=Tomato|Potato Dynamic options
      Besides defining static options as above, you can use one Hanna tag to dynamically generate options for another. For instance, you could create a Hanna tag that generates options based on images that have been uploaded to the page, or the titles of children of the page.
      Your Hanna tag that generates the options should echo a string of options delimited by pipe characters (i.e. the same format as a static options string).
      You will probably want to name the Hanna tag that generates the options so that it starts with an underscore (or whatever prefix you have configured as the "exclude" prefix in the module config), to avoid it appearing as an insertable tag in the HannaCodeDialog dropdown menu.
      Example for an existing attribute named "image":
      image__options=[[_images_on_page]] And the code for the _images_on_page tag:
      <?php $image_names = array(); $image_fields = $page->fields->find('type=FieldtypeImage')->explode('name'); foreach($image_fields as $image_field) { $image_names = array_unique( array_merge($image_names, $page->$image_field->explode('name') ) ); } echo implode('|', $image_names); Choice of inputfield for attribute
      For attributes which you have defined options for, you can choose the inputfield that is used to select from the options.
      Inputfields that support the selection of a single option are select (this is the default inputfield for attributes with options so it isn't necessary to specify it if you want it) and radios.
      Inputfields that support the selection of multiple options are selectmultiple, asmselect and checkboxes.
      You can also specify a checkbox inputfield - this is not for attributes with defined options but will limit an attribute to an integer value of 1 or 0.
      The names of the inputfield types are case-insensitive.
      Example for an existing attribute named "vegetables":
      vegetables__type=asmselect Descriptions and notes for inputfields
      You can add a description or notes to an attribute and these will be displayed in the dialog.
      Example for an existing attribute named "vegetables":
      vegetables__description=Please select vegetables for your soup. vegetables__notes=Pumpkin and celery is a delicious combination. Notes
      When creating or editing a Hanna tag you can view a basic cheatsheet outlining the HannaCodeDialog features relating to attributes below the "Attributes" config inputfield.
      Troubleshooting
      HannaCodeDialog includes and automatically loads the third-party CKEditor plugins Line Utilities and Widget. If you have added these plugins to your CKEditor field already for some purpose and experience problems with HannaCodeDialog try deactivating those plugins from the CKEditor field settings.
    • By gRegor
      Updated 2017-03-27:
      Version 1.1.3 released
      Updated 2016-04-11:
      Version 1.1.2 released

      Updated 2016-02-26:
      Officially in the module directory! http://modules.processwire.com/modules/webmention/

      Updated 2016-02-25:
      Version 1.1.0 is now released. It's been submitted to the module directory so should appear there soon. In the meantime, it's available on GitHub: https://github.com/gRegorLove/ProcessWire-Webmention. Please refer to the updated README there and let me know if you have any questions!
      ------------
      Original post:
       
      This is now out of date. I recommend reading the official README.
       
      I've been working on this one for a while. It's not 100%, but it is to the point I'm using it on my own site, so it's time for me to release it in beta. Once I finish up some of the features described below, I will submit it to the modules directory as a stable plugin.
      For now, you can install from Github. It works on PW2.5. I haven't tested on PW2.6, but it should work there.
      Feedback and questions are welcome. I'm in the IRC channel #processwire as well as #indiewebcamp if you have any questions about this module, webmention, or microformats.
      Thanks to Ryan for the Comments Fieldtype which helped me a lot in the handling of webmentions in the admin area.
      ProcessWire Webmention Module
      Webmention is a simple way to automatically notify any URL when you link to it on your site. From the receiver's perspective, it is a way to request notification when other sites link to it.
      Version 1.0.0 is a stable beta that covers webmention sending, receiving, parsing, and display. An easy admin interface for received webmentions is under development, as well as support for the Webmention Vouch extension.
      Features
      * Webmention endpoint discovery
      * Automatically send webmentions asynchronously * Automatically receive webmentions * Process webmentions to extract microformats   Requirements * php-mf2 and php-mf2-cleaner libraries; bundled with this package and may optionally be updated using Composer. * This module hooks into the LazyCron module.   Installation Github: https://github.com/gRegorLove/ProcessWire-Webmention

      Installing the core module named "Webmention" will automatically install the Fieldtype and Inputfield modules included in this package.   This module will attempt to add a template and page named "Webmention Endpoint" if the template does not exist already. The default location of this endpoint is http://example.com/webmention-endpoint   After installing the module, create a new field of type "Webmentions" and add it to the template(s) you want to be able to support webmentions. Sending Webmentions
      When creating or editing a page that has the Webmentions field, a checkbox "Send Webmentions" will appear at the bottom. Check this box and any URLs linked in the page body will be queued up for sending webmentions. Note: you should only check the "Send Webmentions" box if the page status is "published."   Receiving Webmentions This module enables receiving webmentions on any pages that have have "Webmentions" field, by adding the webmention endpoint as an HTTP Link header. If you would like to specify a custom webmention endpoint URL, you can do so in the admin area, Modules > Webmention.   Processing Webmentions (beta) Currently no webmentions are automatically processed. You will need to browse to the page in the backend, click "Edit," and scroll to the Webmentions field. There is a dropdown for "Visibility" and "Action" beside each webmention. Select "Process" to parse the webmention for microformats.   A better interface for viewing/processing all received webmentions in one place is under development.   Displaying Webmentions (beta) Within your template file, you can use `$page->Webmentions->render()` [where "Webmentions" is the name you used creating the field] to display a list of approved webmentions. As with the Comments Fieldtype, you can also generate your own output.   The display functionality is also under development.   Logs This module writes two logs: webmentions-sent and webmentions-received.   Vouch The Vouch anti-spam extension is still under development.   IndieWeb The IndieWeb movement is about owning your data. It encourages you to create and publish on your own site and optionally syndicate to third-party sites. Webmention is one of the core building blocks of this movement.   Learn more and get involved by visiting http://indiewebcamp.com.   Further Reading * http://indiewebcamp.com/webmention * http://indiewebcamp.com/comments-presentation * http://indiewebcamp.com/reply
    • By kixe
      This morning I pushed a module to github which extends the page api with moving and sorting capability.
      https://github.com/kixe/PageSortMove
      /** * CALLABLE * PageSortMove::execute($pageID, $newIndex = 0, $parentID = null); * $modules->get('PageSortMove')->execute($pageID, $newIndex = 0, $parentID = null); * * EXTENDED PAGE API * @property $page->first // under same parent * @property $page->last * * @method $page->first($parentID = null) * @method $page->last($parentID = null) * @method $page->sort($newIndex) * @method $page->move($newIndex, $parentID = null) */ Have a nice weekend.