Nature is constantly teaching us that change is just part of life ... moving on to start over is an inevitable cycle which also happens to apply to internet technologies. We are all constantly seeking for the best tools to grow our web presence in the most effective way.
Joomlatools has been a key player in the CMS market for over a decade and during this time we have witnessed a progressive migration from Joomla towards WordPress. WordPress has evolved quite a bit over the years and at present provides, hands down, the best and easiest to use interface, whilst also harbouring the largest user community in the market at the time of this writing.
DOCman for Joomla already provided the tools for migrating your entire document library from one Joomla site to another. During the development of the WordPress plugin we took great care to make it possible to move your DOCman data from Joomla into WordPress. That is what this article is all about, so, let's get to it!
Pre-flight checklist
First things first, it's very important that we go through the process of prepping the field so that everything goes smoothly and so that we can roll it all back, just in case it doesn't.
Backup the backup
In life it's always better to be safe than sorry, this adage couldn't apply more here! Before you start the upgrade process please make a full backup of both sites. You never know what could go wrong during migrations, this will allow you to properly roll back the operation and restore your site(s) to a working state. If you have private documents, make sure your source site is offline or make a copy of your site that you can work in.
Update and install DOCman
It is very important that you are running the latest DOCman available on both Joomla and WordPress. This ensures that the exporter/importer are synced, meaning that the importer will know how to properly handle the exported data when it's imported into WordPress.
You may check these guides if you need help on upgrading your DOCman install on your Joomla site. Naturally on WordPress, you just need to install the latest available package and leave everything as is for now.
It's impportant to note that DOCman can only import data in your target site if it's a fresh install of DOCman and there are no documents or categories already set up. DOCman should always be in a clean state so as to ensure that the exported data gets properly imported.
Export from Joomla
This is where everything starts. Are you ready? OK then, let's go:
The first thing we need to do is to get to the DOCman export view on your Joomla site. From the Joomla site's backend interface, and while using the left sidebar, go to Components > DOCman > Settings. Then, click on the Export DOCman data button within the Migrate section.
Once the exporter opens, click the Export button for the process to begin. You'll be able to see the live progress of each step of the exporting process, with a file download prompt at the very end of the process.
Once you have downloaded the export file, it's now time to go your WordPress site and start the import process.
Import into WordPress
Logically, the import step will take place on your WordPress site. The first thing you need to do is log into the admin interface of your site and the follow these steps:
Log in to your WordPress site's admin area and from the left sidebar go to DOCman > Settings. Once in the DOCman settings view, go to the maintenance section and click on the Import from ZIP file button.
In the Import view you will find a button which will allow you to upload the export file you downloaded, following the steps provided above. All you need to do here is to press the Select export file button, then browse for the export zip file that you downloaded and let the import process begin.
During the import process you'll have progress bars showing for each step of the process. When DOCman is done importing your data you'll be prompted with a message about the successful status of the task. At this point you can return to your WordPress site's admin interface by using the Go back button.
Move your files
The exported file only contains the migratable database data. The actual files that DOCman documents link to are not included in the export. Using your file transfer method of choice (e.g. FTP, rsync, etc.) move the files and folders from your Joomla site (located at: JOOMLA_SITE_FOLDER/joomlatools-files) over to the following location on your WordPress site: WORDPRESS_SITE_FOLDER/wp-content/foliolabs-files.
The reason that we don't include the file in the export is that, depending on the size of your documentation library, the resulting zip file could be way too big for the webserver to handle. There are better and more efficient ways for moving these files instead.
Are downloads are broken after manually moving your files?
This means that the data import took place before moving the files. The import process takes care of re-scanning your DOCman files folders and mapping them into a database table. If your files were not yet in place when you data got imported then the mapping did not take place.
To solve this you just need to go to DOCman settings and click on the Clear Cache button located on the Maintenance section. This will clear the file mapping cache and force a full re-scan of your physical DOCman files and folders.
What did we just migrate?
Short answer - everything we could. It's pretty clear that not all of your DOCman for Joomla data is migratable to WordPress. For example, Joomla menu items cannot be migrated as WordPress doesn't share the same concept of menu items, it uses pages and posts instead (more on this later). The same goes for:
- Permissions: DOCman for WordPress implements a custom permission system which is fundamentally different from the one provided by Joomla.
- Configuration: global settings on WordPress differ from the ones presented in Joomla.
- Users: all user relations present on document and category entries still point to IDs from users that got registered in Joomla. It is up to you to make sure that those are properly addressed after importing the data into your WordPress site (tools for migrating core data from Joomla to WordPress do seem to exist, but they are outside the scope of this post).
- Overrides: template overrides cannot be migrated. Even if similarities between equivalent views exist, layouts are not guaranteed to remain identical on both platforms.
Create pages and posts
As mentioned above, you need to get your DOCman views showing somewhere on your WordPress site. This does not happen automatically since we cannot possibly know where DOCman should actually show within your WordPress content. Don't get me wrong, this is totally possible but still a manual process, let me show you how...
Fortunately, all the DOCman menu item types available in Joomla (layouts included) are also supported in WordPress. All that's needed is to re-create these menu items (or modules) by using the corresponding WordPress block inside your WordPress content. Here's a table showing the one to one correspondence from a Joomla menu item to a WordPress block:
You'll be able to use either a page or a post (or indeed, both) depending on the WordPress block that you are planning on using. Some blocks like the hierarchical and tree list blocks are only compatible with WordPress Pages, while the others can be also used on posts.
Modules in Joomla can be replaced in WordPress with template widgets. We currently support adding DOCman blocks as widgets by using shortcodes in the WordPress customizer UI (theme editor). DOCman has shortcodes for every block that's listed in the table above. The Joomla DOCman documents module can be reproduced by utilising a flat list block in WordPress, simply by tweaking the block settings for hiding both the action buttons (toolbar buttons) and list pagination.
DOClinks in Joomla are easily replaced in WordPress using the Attachment block. This block can also be set on both pages and posts and you can use as many of these blocks as you want in your content.
Wrapping it up
If you made into here then you know everything there is to know so you can get ready for this exciting new venture. We've made DOCman for Joomla great but DOCman for WordPress is an improvement on so many ways.
Joomlatools' new WordPress plugin is not just a simple port of the same application from one platform into another, we have completely re-factored it from the ground-up, while also making sure to fill those holes where DOCman for Joomla was lacking (due to platform constraints). We've got big plans regarding DOCman for WordPress so make sure to join the party on your current and future WordPress projects!
Get started
Supercharge your WordPress file and document management with DOCman. Go ahead and try DOCman on our demo or download it from our Dashboard. Not yet a member? Get a subscription and start using DOCman today!