Exporting and Packaging

This is intended for internal use. These are the notes for our plans regarding exporting pages, blocks, etc from Rock. This is for Trello card #34 and Trello card #133.

Export Overview

• Step 1 - Select child pages, and blocks on those pages (draft sketch)
• Step 2 - Select files (by convention we'll pre-select any Scripts, Assets, CSS folders inside the BlockType's folder (draft sketch)
• Step 3 - Name your export for saving (draft sketch)

Export Save

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 need not be a requirement for exporting stuff from Rock?) The exported data (the virtual pages, block metadata, block content) 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.

Filesystem Location

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

Example *.nuspec File

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>