I understand the basic premise for shortcodes. However, I am confused about how to set one up.

I tried it like the below snippet in the template, contact.php, and then calling [hello] from within the <cms:editable>...</cms:editable> in the HTML body.

<?php require_once( 'couch/cms.php' ); ?>
<cms:template title='Contact Us' order='10'>

<cms:do_shortcodes>

<cms:show main_content />

</cms:do_shortcodes>

</cms:template>

It didn't work. I also tried wrapping <cms:editable>...</cms:editable> in the HTML body section with the shortcode tags. That didn't work either.

I had read comments referring to <cms:do_shortcodes><cms:show my_content /></cms:do_shortcodes>, but I don't use the show tag anywhere.

Are shortcodes not compatible with the "editable" tag? Is utilizing the "show" tag required?

I am missing something. Can someone please clarify?

Thanks.

[KK]

I'll try to explain, @TFG.

But to do so, let us forget shortcodes for the moment and simply concentrate on how we display normal content in Couch.

Please take a look at the following code -

Code: Select all

<?php require_once( 'couch/cms.php' ); ?>
<cms:template title='Contact Us' order='10'>

    <cms:editable
        name='main_content'
        label='Content'
        type='richtext'
    />

</cms:template>


<?php COUCH::invoke(); ?>

If you use the code above in a template and register the template, when you visit the admin-panel you'll see a richtext editor in that template's edit screen. I'm sure you are familiar with that.

Now if you input some text into the richtext editor, click save and then then visit the template on the frontend - you'll see *nothing*.

Why? Because in our code we have just defined the editable region (and sure enough, we get it in the admin-panel) but no where are outputting the current contents of the region.

To do that (i.e. display the content of a region) we use <cms:show> tag. So if we modify our original code and make it as follows we should now see on the frontend whatever we inputted in the backend -

Code: Select all

<?php require_once( 'couch/cms.php' ); ?>
<cms:template title='Contact Us' order='10'>

    <cms:editable
        name='main_content'
        label='Content'
        type='richtext'
    />

</cms:template>

<h1>My Content:</h1>
<div id='my_content'>
    <cms:show main_content />
</div>    

<?php COUCH::invoke(); ?>

To reiterate the pattern - there are *two* steps -
1. Define a region within <cms:template> block
2. Display the region's contents anywhere using <cms:show>

There is a variation of the above-mentioned pattern where we can combine the two steps into just one (useful in simple non-clonable templates).

We do this by defining the editable region *outside* the <cms:template> block right at the spot where we wish the content to appear.

For example, we can change our code above to the following at it will still work just the same -

Code: Select all

<?php require_once( 'couch/cms.php' ); ?>
<cms:template title='Contact Us' order='10'>
    <!-- no regions defined here -->
</cms:template>

<h1>My Content:</h1>
<div id='my_content'>
    <cms:editable
        name='main_content'
        label='Content'
        type='richtext'
    />
</div>    

<?php COUCH::invoke(); ?>

Those are the only two ways we can define/display editable regions in Couch.

I'll draw your attention to just one more nuance before we move on to the problem at hand.
In both the examples above we declared the editable region as a 'self-closing' tag (i.e. there is no closing tag with the same name - take a look and you'll see what I mean).

If we wish, we can also declare the regions as a tag-pair like this -

Code: Select all

<cms:editable
    name='main_content'
    label='Content'
    type='richtext'
>

</cms:editable>

What's the point of doing so? Well, with the pair of tags, any content enclosed with the tags becomes the default content of the region - for example the following will make <h3>Hello World!</h3> the default content of the 'main_content' region.

Code: Select all

<cms:editable
    name='main_content'
    label='Content'
    type='richtext'
>
    <h3>Hello World!</h3>
</cms:editable>

So what does 'default content' mean?
In the earlier examples when we visit the admin-panel after defining the region (self-closing), we see a blank richtext editor.

If we define the region as a tag-pair, as in the last example, when we visit the admin-panel the richtext region will already be populated with the default content.

We can, of course, edit this default content in the richtext editor and input anything we like.

So the point is - whatever appears in the editable region in the admin-panel is what gets shown on the front-end.

The point above is pivotal for understanding shortcodes, which we can finally tackle now.
You need to input the shortcodes in the editor that appears in the admin-panel.

So, suppose you go to the admin-panel and enter the following in the editable region -

Code: Select all

Hello [youtube video="1aBSPn2P9bg" /]

what do you suppose you'll see on the frontend where we are using the folowing to show contents of the region?

Code: Select all

<div id='my_content'>
    <cms:show main_content />
</div> 

Well, it will simply display

Hello [youtube video="1aBSPn2P9bg" /]

The [youtube video="1aBSPn2P9bg" /] is *not* going to be converted into the code required to actually display a Youtube video with that ID because <cms:show> can only display verbatim whatever text is present in the region in the admin-panel.

Getting my point?

To actually make the [youtube video="1aBSPn2P9bg" /] *expand* into code capable of displaying videos, we need to wrap the <cms:show> tag with <cms:do_shortcodes></cms:do_shortcodes> as follows -

Code: Select all

<div id='my_content'>
    <cms:do_shortcodes><cms:show main_content /></cms:do_shortcodes>
</div> 

And now, assuming that you have indeed defined a shortcode named 'youtube' (as shown in the docs http://docs.couchcms.com/miscellaneous/shortcodes.html), when you visit the page, the <cms:do_shortcodes> tag will parse the content outputted by <cms:show main_content />, find any shorcode within it and expand it to whatever code has been specified.

The same needs to be done even if you are not using <cms:show> to display the contents - the code will now become

Code: Select all

<?php require_once( 'couch/cms.php' ); ?>
<cms:template title='Contact Us' order='10'>
    <!-- no regions defined here -->
</cms:template>

<h1>My Content:</h1>
<div id='my_content'>
    <cms:do_shortcodes>
        <cms:editable
            name='main_content'
            label='Content'
            type='richtext'
        />
    </cms:do_shortcodes>
</div>    

<?php COUCH::invoke(); ?>

Hope this explains clearly how to use shortcodes.

Thanks for your help. I probably did not explain my problem very well. You spent alot of time outlining things I already knew. Sorry about that.

I do understand editable tags and have been using them successfully for single pages and cloned templates. I am not calling "regions" between the template tags or using the "show" tag. I am more comfortable working within the classic HTML structure where possible, and wrapping actual HTML with the tags I need.

The assumption I was making was that since wrapping HTML content using <cms:editable />... tags picks up the HTML content between the open and close editable tags and displays it in the Admin editor, I assumed it would pull in the shortcode as well.

I had placed the shortcode [hello] in the HTML between the editable tags in the actual php file. Apparently this doesn't work.

So, I went into the Admin editor, added the [hello] shortcode in the editor and Voila! It works. So, now I will go back to the documentation and work out the shortcodes for the various types of embeds that I need - YouTube and Google Maps.

What I was missing is that you have to add the shortcode in the Admin editor. You can't add it in the HTML code and expect it to be pulled in like the HTML markup is.

Maybe add this point to the documentation for clarification.

Thanks so much for helping me figure this out. I appreciate your time.

Update: It's now working perfectly! Successfully embedded a Google Map.

Thanks so much!