Günter Schenk :: Tutorials Corner
Adobe Dreamweaver Developer Toolbox

DW, ADDT and TinyMCE: the SMImage plugin

1. Introduction

Patient History

The discontinuation of Interakt´s web based HTML WYSIWYG editor "KTML" in 2006 has been a desaster to many MX Kollection users, and the general "we need a real KTML replacement or a workaround to the failings of alternatives" outcry was doubtlessly a legitimate one.

KTML was a Dreamweaver extension and hence provided a tight integration into forms built with Dreamweaver respectively MX Kollection -- and particularly in conjunction with MX Kollection´s single & multiple Insert/Update Record forms KTML´s advanced Image and File Management components truly played to their strength, because website administrators could easily define a unique image/file folder path for each editor instance, what´s certainly a huge improvement over the common "assets" folder provided by most other WYSIWYG editors out there.

Contemporary methods of treatment

It´s all water under the bridge, and since KTML´s discontinuation the developers of other WYSIWYG editors such as TinyMCE or FCKEditor (both open source) have put much effort into making their editors a de-facto standard. They do rule the market for very good reasons, and - honestly said - the core functionality provided by both editors has by now become much better than what KTML ever offered, and the real edge is :: both can be easily extended by a huge collection of user-contributed "plugins" which add a variety of features.

Well, you guess what has been missing so far, after KTML was discontinued ?? Image and File management plugins for those abovementioned WYSIWYG editors, which provide about the same features as KTML´s native modules did, are easy to integrate into Dreamweaver/MX Kollection and of course ADDT forms, and which mimic KTML´s "per editor instance" versatility.

Recommended medication

This sort of plugin is now finally available at least to TinyMCE users ! Jens Stolinski, who´s an absolutely brilliant PHP developer from Germany and runs a company named Synasys Media, just recently announced his plugins SMImage and SMExplorer on the TinyMCE forums, and while giving them a try I soon noticed that they can indeed be considered the "missing link" between TinyMCE and the usual MX Kollection / ADDT workflow.

Initially both plugins did not play nice with Kollection/ADDT at all, but yours truly (besides keeping Jens busy with many feature suggestions in regards to usability and security plus some lines of contributed code :-) helped make sure they work, and now they truly ROCK :-)

2. SMimage: a virtual walkthrough

Well, a movie says more than a 1000 words :: here´s a Captivate presentation I created to walk you through the SMImage plugin and help you explore its features.

Ever since this movie was created, Jens Stolinski, the plugin author, has of course released several updates which provide quite some technical improvements as well as a much slicker layout -- and as it´s practically impossible to keep the movie up-to-date with every new plugin release, let´s just show how the layout has changed for the version 1.4.2:



a new toolbar on top with pretty cool icons :-)




the table view now provides an image preview

3. Plugin installation and configuration overview

Installing the SMImage plugin

the SMImage plugin is distributed as ZIP file. After extracting the archive to whatever location on your harddrive...

a) copy the folder "smimage" (Windows: CTRL + C)

b) navigate to the folder that´s holding your local Dreamweaver site, and open your site´s TinyMCE installation directory -- example: C:\xampp\htdocs\your_sitename\tiny_mce

c) open the tiny_mce "plugins" folder

d) copy the "smimage" folder in here (Windows: CTRL + V)

Adding the plugin and desired configuration parameters to an existing TinyMCE instance

Open a form that´s containing an existing TinyMCE instance with whatever HTML or text editor software you´re using, and add...

1. smimage to TinyMCE´s comma separated list of plugins

2. smimage to TinyMCE´s "theme_advanced_buttons1_add" parameter

3. the desired plugin_smimage_... - configuration parameters:



How does the configuration work ?

As already indicated in the "virtual walkthrough" movie, SMImage provides a variety of configuration options which may even be defined differently for each TinyMCE editor instance of your form.

SMImage (as well as SMExplorer, for that matter) comes with a pretty smart and truly flexible approach in regards to configuring the plugin:

a) you can assign default values for most of the SMImage configuration options in a "global" configuration file named "config.php", which is located in the "smimage/php" directory, as displayed next:




Opening this file with e.g. Dreamweaver will reveal an array of configuration settings, which are mostly related to the parameters you can also define for each editor instance:



The last five mentioned *global parameters* named "chmod_folder", "chmod_file", "preview_thumbnail_size", "no_cache" and "document_root" are an exception from the rule, as they don´t have any "per editor setting" counterpart for a very good reason :: these parameters will define some additional plugin settings which - sort of "site wide" - are meant to to affect all TinyMCE instances you´re setting up on your website´s pages. Please see the next chapter "Configuration parameters compendium" for a more detailed explanation.

As some parameters such as "thumbnails_perpage" will supposedly not need to vary between editor instances, declaring a "global" value of e.g. 20 in this file will actually free you from having to introduce the corresponding parameter "plugin_smimage_thumbnails_perpage" to each TinyMCE instance everytime.

b) if you want to assign a different configuration value for e.g. the parameter "plugin_smimage_show_upload" (show/hide the plugin´s upload module) to a specific TinyMCE instance, just add it to the respective "tinyMCE.init" array -- in this case the default value of the corresponding parameter "show_upload" defined in "config.php" file will be overridden with the specified value.

Configuration parameters compendium

Trying to provide an exhaustive explanation on each and every parameter just doesn´t make any sense, as they are all well explained on Jens´ website and in the "smimage/docs/help.txt" -- I´d rather prefer to mention those parameters which actually deserve some extra explanation.

a) parameter categories

Determining the image path
plugin_smimage_server	Protocol and domain name, examples: - "http://localhost" - "http://www.example.com" Well, in theory you could even leave this parameter undefined, but if you prefer SMImage to insert a fully-fledged absolute path to your images like... img src="http://www.example.com/some_directory/myimage_jpg" ... you definitely will have to define this parameter, otherwise your Content Management System (CMS) might display a "broken" image icon in case some page can´t find the requested image Deciding between a relative or an absolute image path is obviously a matter of personal preference, but when developing a CMS I personally strongly favor an absolute image path anyway, because you usually never know if you´re going to publish a public page to the server root or inside some subdirectory after all -- that said, using an absolute image/file path as standard practice will keep you out of unpredictable trouble.
plugin_smimage_directory	the path to an image directory from "plugin_smimage_server", which may not only contain static values, but makes it particularly easy to integrate dynamic values derived from standard Dreamweaver PHP_MYSQL recordsets, URL/Form parameters or Session variables. Some examples: Please note: the folder path you´re specifying for this variable *must* have a leading and a trailing forward slash, e.g. /articles/ -- if they are missing, SMImage can´t find the directory on your server !

As you might guess, both abovementioned parameters will actually team up for making SMImage insert an fully-fledged absolute image path such as "http://www.example.com/some_directory/myimage.jpg"

Personally I´ve decided to rather turn the "plugin_image_server" value into a global setting by defining "http://www.example.com" as static value in the corresponding $CONFIG["directory"] variable that´s available in SMImage´s "config.php" file.

Some related tipps:

a) make sure that TinyMCE´s own parameters "remove_script_host" and "relative_urls" are both set to false, otherwise TinyMCE is going to destroy SMImage´s absolute image path when saving your work !!

b) see a :-)

Image display and sorting options
plugin_smimage_jpg_quality	a value between 1 (really bad, you don´t wanna use this one :-) and 100 (best display quality, no loss). What´s important to keep in mind :: this setting will affect both the display of the on-the-fly generated thumbnails as well as the quality of uploaded .jpg files !
plugin_smimage_orderby	Beginning with SMImage version 1.4.4, the available default sorting options are: 1 -> file name, ascending order 2 -> file name, descending order 3 -> file size, ascending order 4 -> file size, descending order 5 -> image size, ascending order 6 -> image size, descending order 7 -> file time, ascending order 8 -> file time, descending order (alternate value: 0) These options will affect both types of display (thumbnail or table view). While SMImage´s "thumbnail" view will, when launching the plugin, get sorted according to the given default option, switching to "table" view - from version 1.4.4 - will reveal a pretty handy feature :: by clicking on the desired table header (e.g. "Date"), it´s possible to override the default sorting option and subsequently re-sort the list by... - file name - file size - image size - file date ... in ascending or descending order, as displayed next: In case you´re wondering whether the "thumbnail" view will always be sorted according to the default criteria :: a dynamic subsequent re-sorting is also available here ! Just switch to "table" view, sort the list as desired, and switch back to "thumbnail" view -- the order of images will now change accordingly.

Security related options Possible values for the first four parameters: 0 for Hide, 1 for Show
plugin_smimage_show_upload	hide/show the Upload function
plugin_smimage_show_image_menu	hide/show the whole "image menu" which exposes the security-sensitive actions "Delete Image", "Rename Image", "Rotate Left" and "Rotate Right"
plugin_smimage_show_folder_menu	hide/show the "folders menu" which exposes the security-sensitive actions "rename" and "delete" for displayed subfolders.
plugin_smimage_show_newfolder	show/hide the "create new folder" button
plugin_smimage_check_session_variable from version 1.4.3	hats off to an ADDT user who recently contacted the SMImage author and asked him if it were possible to protect the complete plugin against unauthorized access. This feature wish was indeed more than justified, as previous plugin versions would have allowed anyone to open the plugin´s "index.php" directly in a browser and - under certain circumstances - get at least "view access" to an image directory. What session variable should I check against, if any ? When you´re building a Content Management System (CMS) with ADDT or Dreamweaver´s native server hehaviours, you most probably did add some sort of "login" functionality to your application -- and if you did, the PHP session variables which are available and set after a successful login are... kt_login_id (ADDT) MM_user_id (Dreamweaver) ..which both represent the "login_usr" table´s Primary Key value that´s allocated to the currently logged in user. Other CMS applications like Joomla or Drupal will have a different naming convention for session variables they allocate to logged in users, so please check the respective manual :-) How does it work ? as with most SMImage configuration parameters, you can set this parameter for each editor instance individually or (certainly the preferred way, if you ask me) define it as global paramater in SMImage´s "config.php" -- however, if you don´t want to use this extra protection at all, just don´t set this parameter anywhere and leave the $CONFIG["check_session_variable"] - option blank. How will the plugin be protected ? if this parameter has been set anywhere, and if the current PHP session has not yet expired, SMImage will of course work as intended -- but if the session has expired or some nasty hacker tries to open the plugin´s "index.php" directly in the browser, the visitor will by default get to see this instead: Cool icon, ain´t it ? ;-) Honestly said, I personally would rather want to replace this icon with a probably more meaningful text like "access denied" or "you´ll need to be logged in to access SMImage" or "your session has expired, please log in again" or any combination of all that -- and if *you* would like to adapt this to your needs as well, just open the file "plugin/smimage/php/error.php" with e.g. Dreamweaver and simply replace the embedded image with whatever textual contents you like.
plugin_smexplorer_upload_filesize	this was a feature suggestions from yours truly, and it´s obvious that the idea behind this parameter has been inspired by MX Kollection´s respectively ADDT´s "setMaxSize" directive used by the Image- and File Upload server behaviours. This parameter is meant to impose a filesize limit on the to-be-uploaded image, e.g. a value of 100 (KB) will reject uploaded files which exceed this limit -- however, if this parameter is not set, SMImage will examine the server´s php.ini configuration and use the core directive "post_max_size" for determining the max size of upload data allowed. SMImage´s Upload component will of course indicate the maximum file size, as displayed next:

Global Parameters - can not be defined for each editor instance individually -
chmod_folder	Change the permission of newly created subfolders. Not effective on Windows servers Default value: 0777 You could also try with setting this parameter to 0755 instead in order to add a little more protection to a newly created subfolder, but this might - depending on your server configuration - lock that folder against file uploads. Just try what works best for you !
chmod_file	Change the permission of uploaded images. Not effective on Windows servers default value: 0755 setting this parameter to a lower value such as 0644 is in theory possible, but might prevent uploaded files from being renamed or deleted at a later time. This also depends on your server configuration, so again -- try what works best for you :-)
preview_thumbnail_size from version 1.4.3	since this version an image thumbnail is also available when switching SMImage to "table" view: default value: 200 (px width)
no_cache from version 1.4.2	after uploading a new image and returning to SMImage´s main window, it might well happen that you can´t see the new image in there -- how comes ? Well, let´s quote this EADS article: "The browser cache stores temporary copies of already visited web pages in order to speed up a repeat visit of them" -- and this includes images and other files (like external javascript or CSS files), which are embedded in a page or are getting referenced from a page. As helpful as the browser cache can be under normal circumstances, the abovementioned behaviour might come in your way, as you´ll certainly expect SMImage to always display the "current state of affairs" rather than an outdated page version -- and this is where the parameter "no_cache" will be very helpful, as setting its value to "1" will enforce your browser to always load the images from the server everytime you´re switching SMImage to "view images" mode.
document_root from version 1.4.4	Handle with care ! the vast majority of users will actually not have to care about this parameter at all -- this one is meant to define the *absolute* document root directory path on your webserver and should only be used in the very rare case when the remote server´s PHP configuration file (php.ini) should return an empty (or wrong) value for the server environment variable $_SERVER["DOCUMENT_ROOT"] (on Apache servers) or $_SERVER["APPL_PHYSICAL_PATH"] (on IIS servers). So does SMImage refuse to display an image list from the specified folder respectively doesn´t seem to "connect" to the server at all, although you´re absolutely certain that all other configuration parameters have been correctly defined ? In this case you might want to have a look at your host´s php.ini file and check whether the $_SERVER["DOCUMENT_ROOT"] PHP variable does return some value or not: If this variable should indeed return a blank value, please check the "Document Root" environment variable: The absolute path that´s displayed here, should be taken over to SMImage´s "document_root" parameter, example: "/usr/local/etc/httpd/vhtdocs/whatever", what´s a common setting on shared hosts running Apache on a Linux server.

b) configuration hints and recommended practices

The pretty versatile "global vs. per-editor-instance settings" approach used by both SMImage and SMExplorer is not just "cool", it´s in fact a mandatory approach when used for security-sensitive systems. The probably most critical example is a web-based CMS that´s supposed to get managed by several users with different permission levels or "roles".

Let´s assume your CMS´s user login component is based on a "users_usr" database table that´s containing an integer "permission_level" column, and let´s assume that only a subset of users (the so-called "super-users") are supposed to be granted "file upload" permissions :: how´s it possible to expose SMImage´s Upload feature to only those users who are known to always behave well and will never be cramming the server´s file system with thousands of dingy images ?

• assign them a "permission_level" of 1
• make sure that the respective PHP document that´s holding the TinyMCE instance can access the session variable $_SESSION['permission_level']
• set SMImage´s default value for "show_upload" to 0 in the file "config.php" (strongly recommended !)
• wrap a PHP IF condition around TinyMCE´s "plugin_smimage_show_upload" parameter, like displayed next:
  
  

Note about using SMImage in conjunction with TinyMCE´s native "inlinepopups" plugin

this note only applies to versions prior to 1.4.2 !

SMImage clearly works best when being opened in a separate popup window -- but in case TinyMCE´s native plugin inlinepopups (desribed as "should be treated as experimental since it's not 100% compatible yet") has been activated for the respective editor instance, all plugin dialogs are opened as floating DIV layers instead of popup windows, and here´s where SMImage may look a little weird due to the horizontal/vertical scrollbars:



While SMimage will of course work as expected, having to deal with with the scrollbars is indeed somewhat inconvenient.

Regretfully there´s no "fix" available for this -- except one : don´t use TinyMCE´s "inlinepopups" plugin, which is certainly a nice thing for comparatively tiny plugin dialogs, but not for more sophisticated plugins such as SMImage, which require more space than the "inlinepopups" floating layer is capable to provide.

4. using SMImage with local Dreamweaver sites

Let´s assume the following is all true:

1. you´re developing websites and web applications, and you certainly start developing on your local computer before uploading your files to the remote server.

2. you´re developing websites and PHP based web applications on your local computer with or without Dreamweaver, and you´re most probably running a local Apache webserver which requires you to store your files in e.g. the "C:\htdocs" folder -- when running Microsoft´s IIS web server instead, the server´s root folder will usually be "C:\Inetpub".

3. you´re developing websites and PHP based web applications with Dreamweaver, and you have correctly defined a "testing server" which points to Apache´s "htdocs" folder -- and depending on how many "Dreamweaver sites" you´re developing, the way you´re spreading your files within the "htdocs" folder and have defined the corresponding Dreamweaver "testing server"will most likely look like this:

Single Dreamweaver site	Multiple Dreamweaver sites
site files located directly within the htdocs folder:	site files located within various htdocs´s subfolders:
Dreamweaver testing server definition:	Dreamweaver testing server definition:

How do I define SMImage´s absolute path to an image directory?

When giving the SMImage plugin a first try with one of my local *multiple* Dreamweaver sites, I assumed that the value for SMImage´s configuration parameters "plugin_smimage_server" would have to match the site´s URL prefix -- how wrong I was ;-)

SMImage is of course a multi-purpose plugin and hence doesn´t know and doesn´t care whether you´re using it with or without Dreamweaver sites. Regardless if you´re using SMImage with a single site or multiple sites, all that´s required for defining the "plugin_smimage_server" parameter, is http://localhost -- and this means, that all remaining information related to the image folder´s path will be specified in the other parameter "plugin_smimage_directory".

Some examples:

What do I need to change before uploading my files to a web host ?

When publishing your TinyMCE´d form to your web host, neither Dreamweaver´s "testing server" definition nor the way you did spread your site files across your local "htdocs" directory will have any relevance -- and SMImage´s "plugin_smimage_server" parameter just needs to be changed to "http://www.example.com"

If you´re running a single Dreamweaver site, you´ll apparently not have to change anything at all, but if you´re like me and run multiple Dreamweaver sites, some of the originally defined "plugin_smimage_directory" path segments will have to be deleted before uploading the form, as they will not be physically available on the remote server.

According to the given examples above you´d simple have to delete the /project_1 - path segment from this parameter, that is, your "plugin_smimage_directory" parameter should be set to "/some_subfolder/1/".

5. Integrating SMImage into Content Management Systems

Regardless if you´re going to integrate the SMImage plugin into pre-built Content Management Systems (CMS) such as Joomla or if you´re developing your own CMS, the question remains the same: how can I tell SMImage´s configuration parameter "plugin_smimage_directory" to access *different* image folders within my form ? Short answer: we obviously need to add some "dynamic" value to the file path, and that´s where PHP will come into play.

Let´s assume you´re developing an article management application and you prefer having the images for each article stored in separate directories rather than cramming them all together in just one "assets" folder -- if so, what would be the best way for clearly assigning a certain image directory to a certain article ?

1. use an auto-increment Primary Key column as unique identifier

You might wonder why it´s recommended to provide an auto- increment "Primary Key" column at all :: each newly added record will then have its unique numeric identifier, what´s not just mandatory for having SMImage access different image directories, but what will enable you to display different articles on the very same "article.php" page :: simply link to this page like this: a href="article.php?id=2", what will of course only work when adding an adequate query to "article.php" for retrieving the URL parameter $_GET['id'].

If you´re using a 3rd party CMS, you´ll have to read the documentation to find out if - and how - it´s passing a Primary Key from page to page as URL parameter -- and if so, the parameter´s name will most likely *not* be named "id". However, you get the idea :-)

Have a look at your "article" database table with e.g. PHPMyAdmin and see what´s been defined as "Primary Key" column:



2. create an image directory for each record´s Primary Key

after adding a new record to your "article" table, you´ll apparently need to create an image directory that´s matching the newly added article´s Primary Key value, as displayed next:



Well, at this point I can hear some of you readers scratching your wigs and wondering "how on earth am I supposed to know what the new record´s Primary Key value will be ?" Yes indeed, this issue will come in your way, all the more it´s definitely not safe to simply assume "no big deal, my last record´s ID was 5, and the next one will be 6 then" -- no way, as your "article" table might have been configured to auto-increment its Primary Key by e.g. 5 every time, and this makes any prediction pretty much useless.

a) if you´re a dedicated "I hate programming so much and just wanna see some code if I have no other choice !" - type of user, you´re apparently stuck with having to launch your preferred Database Administration tool everytime and look at the new newly inserted record -- see, that´s what you get from being that reluctant :-))

b) if you´re a half-decent PHP programmer equipped with some basic knowledge and/or a certain sense of curiosity, you could create yourself a script and use mysql_insert_id, what will retrieve the ID generated for an AUTO_INCREMENT column by the previous INSERT query

c) if you´re using some pre-built CMS application, it might in theory well be that it´s providing a feature to automatically create a folder after inserting a record -- in case of doubt please consult the documentation or ask on the respective forums.

3. make the image directory writeable

When hosting your website on a Unix/Linux server, and when intending to use SMimage´s Upload feature, you need to make sure that your image directories are writeable, otherwise the Upload will fail.

Again, you could use some PHP to additionally automatize this step everytime you´re creating a new folder after inserting a new record. But as this tutorial is also getting read by less skilled users, I don´t want to scare them away by too much tech-talk -- so let me explain how to set the folder permission with a regular FTP application:

a) launch your FTP application and navigate to your "article_images" folder



your FTP application will usually display folder and file permissions as pretty cryptical data like "drwxrwxrwx". But rather than making you understand what that means in particular, let me show how to change a given permission value to something else :: right click a folder to open a context menu, and click the "file attributes" entry:



b) change the folder permission to either 777 or 755

you´ll next be greeted with a dialog which allows you to change the selected folder´s permission:



Now, what should you change the permission to in order to have SMImage perform the Upload just fine ?

Try with either 755 or 777 -- some server configurations will work well with 755, but some others will only allow 777 folders to not reject uploaded files.

If possible, it´s actually recommended to set folder permissions to 755, as this will add some more security against - loosely said - weirdos trying to delete a folder using some nasty script.

6. Integrating SMimage into ADDT´s Dynamic Forms :: proof of concept

Introduction for those who have never heard of ADDT

The Adobe Dreamweaver Developer Toolbox extension (ADDT) is well known for replacing Dreamweaver´s native - and comparatively basic - PHP/MySQL database handling with many advanced features.

One of ADDT´s outstanding features is called "Dynamic Forms", which allow for adding/editing/deleting multiple recordsets in one swoop and by implementing all this functionality on just one form, what´s certainly much more convenient than having to spread each "action" across several pages respective having to update existing records one after the other.

About the movie

This following movie is meant as proof of concept and basically shows *that* it´s possible to edit multiple records with unique image directories using ADDT -- in addition it also shows that it´s technically possible to hide the SMImage button from a TinyMCE instance in case the very same form is going to insert records into the database, what´s a mandatory thing to do, as the corresponding image directories for the to-be-inserted records apparently don´t exist yet.

And how´s that done technically ? Well, this will be explained in the next chapter :-)

7. Integrating SMimage into ADDT´s Dynamic Forms :: in-depth tutorial

Hint: The following does also work with MX Kollection :-)

1. Introduction

As seasoned ADDT developer you probably know that ADDT´s "Dynamic Form" is based on something called "transaction recordset". This thing will, loosely said, "repeat" the form instance depending on how many records you select in the "Dynamic List" to become added/updated/deleted.

So far so good, but here´s the catch :: this default transaction recordset is meant to work with the given form, but it isn´t capable to integrate "external components" such as a TinyMCE instance into this workflow -- and as you´ll need to ensure that your TinyMCE instance will be iterating using the same number of repetitions just as the form instance does, you´ll need to add some extra code to get this accomplished.

2. have a look at the original "transaction recordset"

After applying a "Dynamic Form" to an empty PHP document, ADDT´s default transaction recordset is usually placed preceeding the page´s DOCTYPE, as displayed next:



Let´s analyze the displayed piece of code and ask ourselves some simple questions:

a) what database table will be affected ? It´s apparently the "article" table.

b) all code lines contain the combination of "rs" + "tablename" all over the place, like "$rsarticle", "$row_rsarticle", "$totalRows_rsarticle" -- is that important to keep an eye on ? Yes, see next point...

3. create an additional "transaction recordset" instance for TinyMCE

For making your TinyMCE instance repeat the same as the form, you´ll first need to create an alias instance of the original transaction recordset and place it below, as displayed next:



This alias instance will also be related to the "article" table, but it´s been slightly modified, as all original rsarticle occurences have been replaced with "rsarticle_tinymce" -- we need to give them a different name, because Dreamweaver can´t reuse one recordset in more than one places within a page.

4. Loop a TinyMCE instance by using the transaction´s alias instance



Let´s see, what do we have here ? When comparing the displayed code with what ADDT generates for the form instance, you might note that the form itself gets iterated using the same "logic":

a) a counter variable $cnt1, which first just gets initialized plus set to a zero value: $cnt1 = 0;

b) a standard PHP do-while loop that´s related to the transaction recordset: while (row_rsrecordsetname = mysql_fetch_assoc($rsrecordsetname));

c) and within the do-while loop, the previously initialized counter variable $cnt1 will increment by 1: $cnt1++;

And this is exactly what we need to apply to the TinyMCE instance as well -- with one exception :: unlike the "form iterator" which is tied to the default transaction recordset "rsarticle", TinyMCE will get iterated using the alias transaction recordset "rsarticle_tinymce".

5. specify the dynamic path to the image directory

It´s now time to add the dynamic path for SMImage´s plugin_smimage_directory parameter, as displayed next:



What´s certainly interesting to see, is that the last path segment is using the kt_pk_article value that´s part of your alias transaction recordset "rsarticle_tinymce" -- now what does kt_pk_tablename stand for ?

Well, that´s fortunately easy to explain :: kt_pk_tablename is a generic identifier for the respective record´s Primary Key value, means that it will later translate to "/article_images/1/" or "article_images/2/" -- and that´s exactly the reason why I´m suggesting to use image directories which are named according to a record´s Primary Key

6. make a difference between insert and update transaction

Houston, we´re having a problem :-) No, it´s not the NASA which would have to find a way to hide the SMImage button in case ADDT´s Dynamic Form is executing an Insert Record transaction -- it´s *you* who should apply the following PHP if-else condition to the TinyMCE parameter theme_advanced_buttons1_add : "smimage":



Good question: why do I recommend this ? When ADDT´s Dynamic Form performs an Insert Record transaction, the new record´s Primary Key is yet unknown, and at this point you´d still have to create the image directory for that newly added record.

Imagine your customer adding one or more new records while adding some content using TinyMCE, and trying to click the SMImage button to integrate some image from a directory which doesn´t exist yet ? There you have it :-)

7. the complete code

Here´s how a complete TinyMCE instance could look like when integrated into a Dynamic Form the way I described in the previous steps:



8. one last step

When looking at the "complete code" more closely, you can see an extra line of code which hasn´t been mentioned before:



This one will have to match the CSS class you´ll also need to add to the textarea that´s supposed to be converted to a TinyMCE editor:



9. Conclusion

That´s all there is to do :-))

8. Tips & Tricks: accessing different image folders using a dropdown menu

Earlier in this tutorial I provided several clues about how to set SMImage´s "plugin_smimage_directory" configuration parameter to a dynamically created value -- alright, you get one defined image directory.

But does this imply that you´re restricted to exclusively access this particular image directory (including its subdirectories of course) once the page loads in your browser ? Not at all !

TinyMCE has an amazingly flexible internal architecture anyway, and this will also allow you replace the initially defined values of "tinyMCE.init({" - configuration parameters "on the fly" using JavaScript.

The following examples will show you how override your initially defined "plugin_smimage_directory" value with stuff that´s defined in a regular HTML menu -- for the simple purpose of choosing from more than just one "base" image directory.

Here´s how I just incorporated this pretty helpful feature into a custom-made CMS I developed for a customer:




In this example the underlying "value" of each menu entry represents a certain subdirectory below the site root.


So far, so good, but how can the value of the currently selected menu entry be passed to the SMImage plugin in order to have it open the desired subdirectory ? Let´s throw some basic JavaScript code into the page to make this happen -- but let´s first of all consider what "type" of dropdown menu you´re actually dealing with, because the required JavaScript routines will depend on whether it´s a...

Menu Type A:



...which is s simple array of Label/Value pairs, where each entry has a defined value.

Menu Type B:



...which does have an additional "select image directory..." label with an empty value

Regardless the chosen menu type, your page will need the following 2 JavaScript components:

1. an "onchange" Event Handler that´s added to the menu´s "select" tag and which will "do something" when the user changes a menu entry

2. a corresponding function which goes inside the "head" tag and which will pass the currently selected menu "value" to the SMImage plugin.


Let´s now have a closer look at the inevitable discrepancies -- and let me take this opportunity to thank Jens Stolinski, the SMImage inventor, for listening to my "how can I do this ?" petition and providing the following JavaScript "components" for each menu type.

the following code samples are also provided in this tutorial´s "download related files" area !

Menu Type A

a) the Event Handler:

onchange="Editor_ChangeSMImageDir(this.options[this.selectedIndex].value);"

b) the function:

function Editor_ChangeSMImageDir(dir) {
tinyMCE.activeEditor.settings['plugin_smimage_directory'] = dir;
};

Q: Why is the "type A" related JavaScript code that simple ?
A: Because the related menu is absolutely fool-proof and will always pass a value


Menu Type B

a) the Event Handler:

onchange="Editor_ChangeSMImageDir(this.options[this.selectedIndex].value, this.options[1].value);"

b) the function:

function Editor_ChangeSMImageDir(dir, dir_default) {
if (dir != '') {
tinyMCE.activeEditor.settings['plugin_smimage_directory'] = dir;
}
else {
tinyMCE.activeEditor.settings['plugin_smimage_directory'] = dir_default;
}
};


Q: and why is the "type B" related function that comparatively complex ?
A: this menu could pass an empty value (aka "no image subdirectory") to the plugin, what´s pretty dangerous, so this function needs to contain a security check to keep users from accessing the site root

Q: what does the event handler´s "this.options[1].value" - argument stand for, and what does it do?
A: it´s part of the security check and will - in case a user explicitely selected the "value-less" first menu option - set the value of SMImage´s "plugin_smimage_directory" parameter to the value of the menu´s 2nd option, which is usually not empty

Q: what if I want to make the value of the 3rd menu option the default one instead ?
A: change the previously mentioned argument to "this.options[2].value" and please remember: JavaScript counts arrays from 0


Possible code variations

When implementing the provided code samples and toying around with them, I soon discovered that the previously explained "set the value of SMImage´s plugin_smimage_directory parameter to the value of the menu´s [whatever] option" - approach may not be an appropriate solution under different circumstances.

It´s fine when you´re dealing with a static menu which you created yourself -- but what if the array of menu entries gets generated from a database query ? In this case "this.options[1].value" may represent an unpredictable value respectively one which I´d rather not prefer as default image directory.

When dealing with this issue I came to the conclusion that introducing a hard-coded "image directory" to the main JavaScript function may be the better approach -- and it´s also a slightly easier one, because your Event Handler can be simplified.

Here´s what I came up with:


a) the Event Handler:

onchange="Editor_ChangeSMImageDir(this.options[this.selectedIndex].value);"

b) the function:

function Editor_ChangeSMImageDir(dir) {
if (dir != '') {
tinyMCE.activeEditor.settings['plugin_smimage_directory'] = dir;
}
else {
tinyMCE.activeEditor.settings['plugin_smimage_directory'] = "directory_name/";
}
};


That´s it for now :-)

9. Tips & Tricks: how to replace embedded images in the editor instance

So far this tutorial was all about grabbing images from the server and inserting them into an editor instance -- but is it also possible to *replace* an embedded image without having to first delete it from the editor instance and then call SMimage to insert another image at the same position ?

This optional feature has been implemented in SMImage version 1.5.2, and here´s...

1. how it works

1.1. click the to-be-replaced image and click on Tiny MCE´s native "insert/edit image" icon:





1.2. click the "Image URL" button to call SMImage and select a different image from the server:





SMImage will now navigate to the specified image directory and lets you (as usual) select the desired image -- the difference is: this image will now be passed back to TinyMCE´s "advimage" plugin, which in turn will update its Preview. After confirming with OK, TinyMCE´s editor window will display this new image in place of the previous one.


2. how to enable this feature

2.1. establish a link to another javascript file in your document´s "head":



SMImage version 1.5.2 and later has this functionality "outsourced" to an external javascript file that´s part of the distribution, sits in the "smimage" plugin root, and is named "smplugins.js" -- and the "src" attribute of your additional javascript link needs to point to this file like this:

"../../tiny_mce/plugins/smimage/smplugins.js"


2.2. modify the tinymce.init array:




a) add TinyMCE´s "advimage" plugin to the comma separated list of plugins

b) add the line file_browser_callback : "SMPlugins", somewhere within the tinymce.init array


2.3. make sure that TinyMCE´s "image" icon is visible

depending on your general editor configuration it might well be that some of TinyMCE´s standard icons are missing -- and just in case TinyMCE´s "Insert/edit image" - icon is not visible, you´ll have to add image to one of the existing "theme_advanced_buttons" lists, e.g.

theme_advanced_buttons1 : "bold,italic,underline,image",