Important : The editing mode is a very powerful feature and it's easy to use it incorrectly and cause yourself problems. It is advised that you read this page first before using the feature.
Editing mode in Jomres is a powerful feature which allows Site Administrators and Property Managers to edit text via the Front end of Jomres.
Site Administrators can use an extension of the editing mode in the administrator area of Jomres called Label Editing, but here we will discuss the merits of using the Editing mode's functionality as a context sensitive editing feature.
Before we continue, we should point out that you don't need to be translating in Jomres to use the editing mode. You can use the editing mode as a way of renaming labels that is upgrade safe, or because one property likes the word "Rates", as opposed to the word "Tariffs", and a third prefers "Prices". All of these properties can have the labels they want.
Editing mode started out as a way to provide users with the ability to rename elements from the language files in such a way as for the changes to remain after an upgrade overwrites the language files. Changes are added to a custom_text table in the mysql database, and are property id specific, so any changes saved have the id of the current property added to the appropriate column in the database. After a short while some bright spark came up with the idea of adding a language column to this table, because at the time there wasn't a reliable version of Joomfish for Joomla 1.0.x, to help with translations, and so the basic functionality of the Editing Mode came to be.
Who can use it
The Editing Mode isn't available to everybody. If the Site Administrator has chosen to configure Jomres so that "Minimised Config Options" is set to Yes, then non-super property managers (see Users in Jomres) will not be offered the Editing Mode as a dropdown at the top of the page. Regardless of that setting Super Property Managers will always see this as an option. Additionally, if the Global Editing Mode is enabled, then this will have an effect too, but only for them. See further for details.
How it works
In short, Jomres has labels defined in Language files and text stored in the database from when things like rooms, tariffs guest types etc are added. The user defined text for tariffs etc is slightly more complicated, but for labels a string such as _JOMRES_COM_MR_YES is used to denote the English string "Yes". Using a function in Jomres called ''jr_gettext'' these labels can be modified to output whatever a property manager chooses to translate that string to. Frequently, unfortunately, some people seem to find themselves translating "Yes" to "No" or vice versa, which can cause no end of trouble until somebody logs in and sees what's been done. Try not to add yourself to that list.
When editing mode is enabled any text that's editable has it's colour changed to a pale blue, and if you click on it you will find that you can edit this text, and your changes saved to the database after you click Ok. These changes are specific to the property that you are currently editing, so you can have different labels for different properties.
The advantage of this mode is that you can navigate to the page you want to change, then select the item you want to edit from that point, which saves trawling through a language file for the correct definition.
Not every item is editable, for things like Configuration options (generally) it's safest to not offer this as an option because then help files and manuals may no longer make sense.
Super Property Managers have an added benefit if the Global Editing Mode in the administrator area's Site Configuration is set to Yes. Any changes they make are saved with a property id of 0 (zero) and when Jomres starts it's run it will first use these changes as an override of definitions made in language files, although any property specific language customisations will in turn override the Super Property Manager's changes, but only for the current property.
Take care with this feature. If the Global Editing Mode is enabled then any customisations you make to things like the property detail text, tariff room or guest type names will be mirrored across all properties, so if you're translating a specific property's information then switch this option off first.
A special case
Normally, if you add something new like a tariff then the description is saved to the rates table and you have to use the editing mode later to rename that if you want different descriptions in different languages.
At one time, the same could be said for the property details (Frontend manager's menu -> Manager's toolbar -> Property description) however you cannot use a WYSIWYG editor when using the Editing Mode so we decided that any changes made in the Property Description page should be saved direct into the Custom Text table. Put another way : Custom text is automatically made for information added/changed via the Property description editing feature.
Bear this in mind, because if Global Editing is enabled (see above and below), this may cause you problems.
Let's say you want to add both English and German property descriptions to a property. The easiest way to do it is to ensure that your active language is English then edit the property description. Now, to translate this text to German you just need to change your current language to German and edit the property's description again.
As stated before the editing mode is powerful, but with power comes responsibility. If you don't understand how the editing mode works you're likely to make problems for yourself.
Before looking further at common issues, I'd like to clarify to you how Jomres uses translations through the jr_getext function :
A label is defined in the language file so in the English language file _JOMRES_COM_MR_YES = "Yes".
When Jomres starts it looks in the _jomres_custom_text table for any definitions that have a property uid of 0 (zero). If there are, then these definitions are Global custom texts and this definition is used instead of the contents of _JOMRES_COM_MR_YES. If you've used the Label Editing feature then you've done a global edit and you will have some rows in that table with the property uid of 0.
If we're looking at a specific property, then when Jomres runs it will also look in that table for rows with a property uid of the current property, eg 1 (one). If the results contain, for example "_JOMRES_COM_MR_YES" then this definition is used in favour of that found when looking for the global definitions.
How can this cause problems?
Global editing mode
Well, the first most obvious one is when somebody, who doesn't understand the implications, switches on the Global Editing Mode in the administrator area Site Config, then uses the Editing Mode in the frontend. If this user is a Super Property Manager (and on a default installation the "admin" user is) then any changes they make using the editing mode with Global Editing set to Yes, are saved as Global text (for that language). This is perfect if you know what you're doing because you can change things in the frontend that affect all of the properties. Where this can become a problem is if you also edit something that's specific to a property, like the property's tariff descriptions. By editing the description while Global Editing is switched on and you're logged in as a Super Property Manager, you've now created a global tariff description that will apply to all properties. Again, this might be what you want, however not many people do.
Another example (mentioned above, but clarified here), one that happens surprisingly often, is that a user will re-label _JOMRES_COM_MR_YES to "No" or _JOMRES_COM_MR_NO to "Yes" (or their language's equivalent). This results in configuration options having Yes/Yes or No/No in the dropdown, inevitably resulting in property configurations being completely messed up and no settings making sense. If a configuration's been completely messed up due to this it's often easier and better to create a completely new property and start again.
Fixing these issues
There is now a plugin in the Jomres plugin manager called ''custom_global_strings''. "Lists and allows you to delete custom global strings. This is useful if you've used editing mode with Global Editing enabled and created a string that you don't want." Use the delete option in that plugin's page to remove the unwanted label(s).
What can I as the developer do programattically to prevent these mistakes from being made? Frankly, not a heck of a lot. Over the years we've tried adding certain exclusions to the save custom text function to stop certain common errors from being made, however this then means that users who were using the Editing Mode feature correctly were then unable to make changes they were expecting to make and we've had to then remove these exclusions. Eventually the decision was taken to not have any exclusions and to simply encourage people to learn how the feature works.
This document is copyright Vince Wooll/Woollyinwales IT, 2011. All rights reserved.