Difference between revisions of "Upgrading to JReviews 3"
| (10 intermediate revisions by the same user not shown) | |||
| Line 3: | Line 3: | ||
== Upgrading to JReviews 3 == | == Upgrading to JReviews 3 == | ||
| + | This guide is valid for upgrading from JReviews 2.7 to all JReviews 3 versions | ||
| + | |||
'''Please read the entire upgrade guide in detail and follow every step for a seamless upgrade. If you encounter any issues, it's better to submit a ticket with access so we can help you.''' | '''Please read the entire upgrade guide in detail and follow every step for a seamless upgrade. If you encounter any issues, it's better to submit a ticket with access so we can help you.''' | ||
| Line 9: | Line 11: | ||
* PHP 7.0-7.2 | * PHP 7.0-7.2 | ||
* ionCube Loaders | * ionCube Loaders | ||
| − | * PHP Extensions: json, mbstring, curl, bcmath | + | * PHP Extensions: json, mbstring, curl, bcmath, fileinfo |
* upload_max_filesize in php.ini must be higher than 6M to be able to upload the installation packages | * upload_max_filesize in php.ini must be higher than 6M to be able to upload the installation packages | ||
| Line 31: | Line 33: | ||
<pre>/jreviews_overrides</pre> | <pre>/jreviews_overrides</pre> | ||
| + | After you finish the upgrade, you can create a new overrides folder and start migrating your customizations using the new versions of the files in JReviews 3. | ||
| − | 3. Disable all installed Add-ons by renaming or deleting the entire Add-ons folder. Do not rename the folder back to its original name after the upgrade. You can find the Add-ons folder at: | + | |
| + | 3. Disable all installed Add-ons by renaming or deleting the entire Add-ons folder. Do not rename the folder back to its original name after the upgrade. You will re-install them in the lat step. You can find the Add-ons folder at: | ||
'''Joomla''' | '''Joomla''' | ||
| Line 58: | Line 62: | ||
6. Clear the browser cache to force the browser to load updated versions of CSS and Javascript files. | 6. Clear the browser cache to force the browser to load updated versions of CSS and Javascript files. | ||
| + | |||
| + | 7. Finally, if you had any add-ons installed before, you will re-install the new versions through the JReviews Remove Install & Update page. | ||
| + | |||
| + | == Must Read About Caching == | ||
| + | |||
| + | This is specifically related to Joomla so if you are using WordPress feel free to ignore. JReviews 3 has a new Asset Loader System Plugin which is fed all the CSS and scripts required by component and modules and then sends them all at the same time to the head of the page before the page is rendered. | ||
| + | |||
| + | '''So what does this have to do with caching?''' | ||
| + | |||
| + | In Joomla, when you use the Configuration Cache, once a module is cached the code for the module is no longer run so it's not possible to load the necessary CSS and scripts for that module. To fix this you need to speficifically disable caching inside the module settings. So the recommendation, unless you have a very specific reason to use the Configuration Cache, is to leave that disabled, and instead enable the Page Cache System Plugin. This one caches the entire page (component and modules), so all CSS and Scripts are taken into account in the cache. | ||
| + | |||
| + | While on the topic of caching, make sure you have the '''platform specific''' caching option enabled in the Joomla configuration to ensure proper caching of pages for both mobile and desktop devices. | ||
== Troubleshooting After the Upgrade == | == Troubleshooting After the Upgrade == | ||
| − | === JReviews admin doesn't load, shows blank page or error Class ' | + | === JReviews admin doesn't load, shows blank page or error Class 'XYZ' not found === |
| − | If you see a blank page, enable Development error reporting in the Joomla configuration or [https://codex.wordpress.org/Debugging_in_WordPress enable debug mode in WordPress]. If the "Class 'ConfigComponent' not found" error shows up, then this means that you have outdated code from JReviews 2 on your installation and you need to re-do the upgrade steps above. It's important to make sure that you: | + | If you see a blank page, enable Development error reporting in the Joomla configuration or [https://codex.wordpress.org/Debugging_in_WordPress enable debug mode in WordPress]. If the "Class 'ConfigComponent' not found" or "Class 'JReviews\Models\ConfigurationModel' not found" error shows up, then this means that you have outdated code from JReviews 2 on your installation and you need to re-do the upgrade steps above. It's important to make sure that you: |
1. Renamed your overrides folder if you have customizations | 1. Renamed your overrides folder if you have customizations | ||
| Line 73: | Line 89: | ||
4. Do not rename back the overrides or add-ons folders after the upgrades. The renaming is only for backup purposes and you can delete those renamed folders once you have transferred all customizations and everything is working as you expect. | 4. Do not rename back the overrides or add-ons folders after the upgrades. The renaming is only for backup purposes and you can delete those renamed folders once you have transferred all customizations and everything is working as you expect. | ||
| + | === Expired upgrades message === | ||
| + | |||
| + | After upgrading, if you see a message similar to the one below it means your installation contains outdated files. | ||
| + | |||
| + | <pre> | ||
| + | To use JReviews v2.7.xx.xx with this license you need to renew your upgrades. | ||
| + | This version of JReviews was released after your upgrades expired. | ||
| + | </pre> | ||
| + | |||
| + | You just installed JReviews 3, so there should be no reference to JReviews 2.7. Proceed to completely uninstall the JReviews component from the Joomla extensions manager or WordPress plugins manager. In Joomla there's no need to uninstall modules or plugins, only the component. Then re-install using the package download from the client area. '''Uninstalling JReviews does not remove any of your data or media from the site.''' | ||
| − | === Some front-end pages don't load === | + | === Some front-end and admin moderation pages don't load === |
If you are using custom code in the PHP Format setting of custom fields, it's possible that some of this code no longer works and needs to be updated with new syntax. For example the $Access class is no longer used in JReviews 3. For now please post in the forum your existing code so I can provide the updated one. You can unpublish the custom field(s) until you get it working again. | If you are using custom code in the PHP Format setting of custom fields, it's possible that some of this code no longer works and needs to be updated with new syntax. For example the $Access class is no longer used in JReviews 3. For now please post in the forum your existing code so I can provide the updated one. You can unpublish the custom field(s) until you get it working again. | ||
Latest revision as of 10:32, 2 October 2018
Contents
- 1 Upgrading to JReviews 3
- 2 Server Requirements
- 3 Step By Step Upgrade Guide
- 4 Must Read About Caching
- 5 Troubleshooting After the Upgrade
Upgrading to JReviews 3
This guide is valid for upgrading from JReviews 2.7 to all JReviews 3 versions
Please read the entire upgrade guide in detail and follow every step for a seamless upgrade. If you encounter any issues, it's better to submit a ticket with access so we can help you.
Server Requirements
- PHP 7.0-7.2
- ionCube Loaders
- PHP Extensions: json, mbstring, curl, bcmath, fileinfo
- upload_max_filesize in php.ini must be higher than 6M to be able to upload the installation packages
Step By Step Upgrade Guide
JReviews 3 has a very large number of code changes so it is not possible to upgrade using the remote updates feature. Also, given the number of changes, none of the previous version files, including theme files, are compatible with this version, so you will need to bring all your code overrides up to date. You may also want to read What happens with modified files when JReviews is upgraded.
To upgrade from JReviews 2.x you need to follow these steps without skipping any of them.
1. Make a backup of your site and be prepared to use it if something goes wrong. Consider first testing the update in localhost or a development domain, especially if you have customizations.
2. If you have customizations, disable JReviews overrides to disable them because they will not be compatible with JReviews 3. To do this, rename the following folder to keep a backup of your changes. Do not rename the folder back to its original name after the upgrade:
Joomla
/templates/jreviews_overrides
WordPress:
/jreviews_overrides
After you finish the upgrade, you can create a new overrides folder and start migrating your customizations using the new versions of the files in JReviews 3.
3. Disable all installed Add-ons by renaming or deleting the entire Add-ons folder. Do not rename the folder back to its original name after the upgrade. You will re-install them in the lat step. You can find the Add-ons folder at:
Joomla
/components/com_jreviews_addons
WordPress:
/wp-content/plugins/jreviews_addons
4. Uninstall the S2Framework and JReviews components from your site. This step is important to remove all the outdated files from the system before installing the new version.
Joomla: Use the Extensions manager to uninstall the S2Framework Component and the JReviews component. Don’t uninstall the JReviews modules because you will lose all your module settings if you do this. WordPress: Use the Plugins Manager to uninstall the S2Framework Plugin and the JReviews Plugin.
5. Continue with normal installation steps for JReviews.
Joomla
Use the Extensions Manager to install the S2Framework component first, then the JReviews component.
WordPress
Use the Plugins Manager to install the S2Framework plugin first, then the JReviews plugin.
6. Clear the browser cache to force the browser to load updated versions of CSS and Javascript files.
7. Finally, if you had any add-ons installed before, you will re-install the new versions through the JReviews Remove Install & Update page.
Must Read About Caching
This is specifically related to Joomla so if you are using WordPress feel free to ignore. JReviews 3 has a new Asset Loader System Plugin which is fed all the CSS and scripts required by component and modules and then sends them all at the same time to the head of the page before the page is rendered.
So what does this have to do with caching?
In Joomla, when you use the Configuration Cache, once a module is cached the code for the module is no longer run so it's not possible to load the necessary CSS and scripts for that module. To fix this you need to speficifically disable caching inside the module settings. So the recommendation, unless you have a very specific reason to use the Configuration Cache, is to leave that disabled, and instead enable the Page Cache System Plugin. This one caches the entire page (component and modules), so all CSS and Scripts are taken into account in the cache.
While on the topic of caching, make sure you have the platform specific caching option enabled in the Joomla configuration to ensure proper caching of pages for both mobile and desktop devices.
Troubleshooting After the Upgrade
JReviews admin doesn't load, shows blank page or error Class 'XYZ' not found
If you see a blank page, enable Development error reporting in the Joomla configuration or enable debug mode in WordPress. If the "Class 'ConfigComponent' not found" or "Class 'JReviews\Models\ConfigurationModel' not found" error shows up, then this means that you have outdated code from JReviews 2 on your installation and you need to re-do the upgrade steps above. It's important to make sure that you:
1. Renamed your overrides folder if you have customizations
2. Renamed the JReviews Add-ons folder if you have any add-ons installed
3. Completely uninstall both JReviews and S2Framework from the site before installing the new versions
4. Do not rename back the overrides or add-ons folders after the upgrades. The renaming is only for backup purposes and you can delete those renamed folders once you have transferred all customizations and everything is working as you expect.
Expired upgrades message
After upgrading, if you see a message similar to the one below it means your installation contains outdated files.
To use JReviews v2.7.xx.xx with this license you need to renew your upgrades. This version of JReviews was released after your upgrades expired.
You just installed JReviews 3, so there should be no reference to JReviews 2.7. Proceed to completely uninstall the JReviews component from the Joomla extensions manager or WordPress plugins manager. In Joomla there's no need to uninstall modules or plugins, only the component. Then re-install using the package download from the client area. Uninstalling JReviews does not remove any of your data or media from the site.
Some front-end and admin moderation pages don't load
If you are using custom code in the PHP Format setting of custom fields, it's possible that some of this code no longer works and needs to be updated with new syntax. For example the $Access class is no longer used in JReviews 3. For now please post in the forum your existing code so I can provide the updated one. You can unpublish the custom field(s) until you get it working again.
If you were using the $Access class to perform checks before in themes or in custom fields, you need to update your code. Here are some of the most common uses and the new requivalent code:
| Use | JReviews 2 | JReviews 3 Theme | JReviews 3 - Field PHP Format |
| Check if current user belongs to admin group | $Access->isAdmin() | $this->auth->admin | $User->admin |
| Check if current user is a guest | $Access->isGuest() | $this->auth->guest | $User->guest |
| Current user ID | $User->id | $this->auth->id | $User->id |
Other important framework changes
Notifications
In JReviews 2 email notifications were handled through /controllers/components/notifications.php. In JReviews 3 they are handled through event listeners. These notification listeners can be found in the /jreviews/events/listeners directory and most of them begin with the "send_" prefix. You can see this is very modular and much easier to read and modify than having a single, huge file, that was responsible for all system notifications. Read the Events documentation article to learn more.
Community Integrations
This mostly applies to Joomla for stream posting to EasySocial and JomSocial. In JReviews 2 these actions were handled through plugins in cms_compat\joomla\plugins\ with one plugin file per component handling all actions. In JReviews 3 they are handled through event listeners that can be found in /jreviews/cms_compat/joomla/events/listeners. Each component has it's own directory with individual listeners for each type of event. Read the Events documentation article to learn more.