Page Exporting and Importing - SparkDevNetwork/Rock GitHub Wiki

NOTICE⚠️

🚫 THIS DOCUMENT IS NO LONGER CORRECT.

The page export/import feature was broken in 2014. If you want to submit a pull request to correct or re-implement this feature, we'd be grateful.

A simple mechanism for exporting a page (and it's child pages) along with all the corresponding blocks will create a "throw away" package. That package can then be imported into another page in Rock (on the same server or another Rock server).

• Step 1 - On the page properties, choose the "Import/Export" tab and optionally uncheck 'include all child pages' and press the "Export" button.
• Step 2 - The package is sent to the user and they are prompted to save the RockPages.nupkg file to their desktop.

• Step 1 - On the page properties, choose the "Import/Export" tab and click the browse-to-file button to choose a package (.nupkg) file.
• Step 2 - Press the import button.

Another system will allow for the packaging and re-packaging of a page, it's child pages, corresponding blocks, and corresponding related files (images, scripts, etc.).

• Step 1 - On the Package Manager page, select the "Package Exporter" tab.
• Step 2 - Select a page to export, one or all of its child pages, and one or more blocks on those pages (draft sketch)
• Step 3 - Select files (by convention we'll pre-select any Scripts, Assets, CSS folders inside the BlockType's folder (draft sketch)
• Step 4 - Name your export for saving (draft sketch)

During the last step of an export, a manifest specification of what is being exported will be stored for later use/re-use in the form of a .nuspec file. (This is very useful when creating new versions of a package, etc., but perhaps this shouldn't be requirement for exporting stuff from Rock?) The exported data (the virtual pages, block metadata, block content, security/auth, etc.) is stored in an export.json data file.

Lastly, the "package" (all their stuff) will be pushed to the client's browser for saving (and subsequently sharing with others?).

With a little more coding, we envision that one might also be able to "publish" this to a nuget gallery immediately after exporting. Also we think a person should be able to re-export using the previously saved .nuspec package manifest with very few clicks.

The NuGet library includes a NuGet.PackageBuilder class which is useful for creating the package and the manifest file.

The exported stuff will be (optionally?) stored under a App_Data/ExportedPackages/ folder, inside a folder named using the packageId + version as illustrated here:

App_Data
    +---ExportedPackages
    |   \---MyExportedStuff.1.0.0
    |           export.json
    |           MyExportedStuff.1.0.0.nuspec
    |
    \---packages
            AFakeLibrary.1.0.0.nupkg
            ANeedyPackage.1.0.0.nupkg

Note: Installed packages (aka "Plugins") are written to the App_Data/packages folder by NuGet used by our PluginManager, however, packages imported using this reusable export/import system should not be listed here nor maintained via nuget as an officially "installed" package.

The folders under ExportedPackages could be deleted without any problems except that it would not be possible to re-export the package without walking through the entire process again.

The .nuspec file retains ONLY references to source files which are relative file paths. Therefore it will not be useful for anyone to try to maintain actual package source code versioning using this system. (We believe attempting to handle this is probably out of scope for the requirements of the export system, but could possibly be done by making a copy of all referenced files/folders too.) However, because the export.json data-file is also being stored under the ExportedPackages/<packageId>.<version>/ folder, it is basically version controlling the data.

This is an example of a .nuspec file which would be saved into a ExportedPackages/MyExportedStuff.1.0.0/ folder:

<?xml version="1.0" encoding="utf-16"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>MyExportedStuff</id>
        <version>1.0.0</version>
        <title/>
        <authors>NickA, JasonO</authors>
        <owners />
        <summary>This is the summary</summary>
    </metadata>
    <files>
        <file src="export.json" target="App_Data\temp\export.json" />
        <file src="..\..\Plugins\MyChurch.com\CoolPackage\BlockA.ascx" target="Plugins\MyChurch.com\CoolPackage\BlockA.ascx" />
        <file src="..\..\Plugins\MyChurch.com\CoolPackage\BlockA.ascx.cs" target="Plugins\MyChurch.com\CoolPackage\BlockA.ascx.cs" />
        <file src="..\..\Plugins\MyChurch.com\CoolPackage\Assets\Images\logo.gif" target="Plugins\MyChurch.com\CoolPackage\Assets\Images\logo.gif" />
        <file src="..\..\Plugins\MyChurch.com\CoolPackage\Assets\Xslt\trans.xslt" target="Plugins\MyChurch.com\CoolPackage\Assets\Xslt\trans.xslt" />
        <file src="..\..\Plugins\MyChurch.com\CoolPackage\Scripts\mylib.js" target="Plugins\MyChurch.com\CoolPackage\Scripts\mylib.js" />
    </files>
</package>

TBD