afPodBuilderExt

An easy tool to help you create SkySpark extensions of your Axon functions, Views, and Apps to share with others.

Pod Builder is a SkySpark extension requiring SkySpark v3.1.1 or later. For older v3.0.x versions of SkySpark, download Pod Builder v1.1.x.

Pod Builder is FREE to download and evaluate. All features are fully unlocked for the creation and continued modification of your first POD!

Note for security considerations, Pod Builder is only available to SkySpark users with Admin privileges.

Contents

• Why use Pod Builder?
• The Pod Builder App
  • Main View
  • Folio View
    • Axon Encryptor integration
  • Files View
  • My Pods View
• Archiving records
  • How does it work?
• StackHub integration
• How to...
  • Use custom icons
  • Add transient tags
• Licensing
  • Evaluation mode
• Disclaimer

Why use Pod Builder?

Maybe you need to copy Axon functions between SkySpark installations? Or maybe you need to share some amazing SkySpark views with your team?

Pod Builder saves you time and effort by "compiling" Axon functions, Folio records, and files into valid SkySpark extensions. With our StackHub integration, it's even easier to share and distribute your amazing code in a simple and convenient way!

Need to automate tasks to create pods? No problem, Pod Builder also ships with Axon functions you can use to access Pod Builder features without needing to open the app!

The Pod Builder App

Use Pod Builder to select Axon Functions, Views, Applications, and Tag definitions to be included in your extension. You may also add other files, such as images, icons, or help documentation. Pod Builder compiles all your content into a correctly formatted POD file, along with appropriate meta and display information for SkySpark.

Using Pod Builder ensures SkySpark will recognise your POD as a valid extension, making it easy to create, distribute, and install your extension on any SkySpark project!

Main View

The main Pod Builder view is where you can view and edit data at the pod level.

Any issues, inconsistencies, or deviations from SkySpark standards are highlighted in the Pod Problems table. Think of it as a pod linter!

The readme is displayed in SkySpark documentation and on any StackHub package description page. The "Preview" tab lets you see your fandoc before saving.

"Edit details..." lets you edit mandatory pod settings, like name, version, and summary.

"Edit meta..." is for editing details that will appear in a pod's meta.props and index.props configuration files, such as dependencies on other extensions.

"StackHub..." is for setting your StackHub credentials.

"Build pod..." is where the magic happens!

It builds and compiles your pod before giving options to:

• "Install..." it on the SkySpark instance it was built on
• "Upload to StackHub..." to be shared with clients, customers, and perhaps the public in general
• "Download" it in the Browser

The install option lets you create a pod in one SkySpark project to be used in another project on the same SkySpark server. Whereas using StackHub lets you install the pod onto other SkySpark instances.

Note: In SkySpark v3.1.6 & v3.1.7 on Windows machines, the install feature does not work.

Folio View

The Folio View is where you select records from Folio and bundle them up into .trio files to be built into your pod.

"Add" records to select them for inclusion into the .trio file. A preview of the .trio file is displayed on the right.

Each tab represents a different .trio file. Clicking "Edit..." lets you see which .trio file each tab is associated with.

The filter column is a Haystack filter expression that narrows down which Folio records are displayed for each tab.

Axon Encryptor integration

If you have Axon Encryptor installed and enabled in the same project, Pod Builder will automatically encrypt your Axon functions as part of the build process.

All Axon encryption settings are saved on a per-pod basis.

Files View

The Files View is where you can upload other resource files (to SkySpark) to be built into your pod.

Files must be uploaded to the project directory in the io/afPodBuilder/<podNmae>/ folder.

My Pods View

For licensed users only, this View lets you create and manage multiple Pod Builder projects.

Archiving records

The Folio View has the notion of archiving records whereby they still exist, but are subsequently ignored by SkySpark.

This can be useful for development machines where a pod project may leave you with tens or hundreds of Axon functions (and other records) that swamp various apps in SkySpark.

A simple, but useful, workflow is to archive all your records when a pod is released, and only un-archive them to make changes and updates. This can help you keep a clean development environment, and keep track of which records have been updated.

Note that archived records are still compiled into Pod Builder .trio files and will still appear in your pod.

How does it work?

Taking a function record as an example, archiving it removes the func tag and replaces it with a afPodBuilder_func tag. This way the record is preserved in Folio, but SkySpark no longer recognises it as an Axon func.

A similar process is then used for other record types such as view and rule.

Deleting a pod project, or performing a Factory Reset, will move all archived records to the Trash. This ensures archived records are recoverable, but do not interfere with similar records that may already exist in the project. (For example, two func records are not allowed to share the same name.)

StackHub integration

Pod Builder provides convenient StackHub integration for uploading Pods directly to your StackHub account.

Uploaded pods may be downloaded and installed in the SkySpark Install Manager. Pods may be open to the public or kept private to your organisation.

This presentation was a winning entry in the SkyPosium 2020 ViewBuilder BakeOff!

How to...

Use custom icons

Custom SVG icons may be packaged up in your resource pod and used within SkySpark for Apps, Views, or just as the extension icon in Install Manager.

To use an icon, you must first create an appropriate SVG. Details may be found in the SkySpark documentation on Icons but briefly, they should be square and contain x3 special group layers with the IDs outline, solid, and color to represent the x3 types of icon usage.

Below is a basic rectangle example, note the use of the style attribute - it must exist for SkySpark to change the colour of the solid and outline icons.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
  <g id="outline">
    <rect x="10" y="10" width="108" height="108" style="fill: none;stroke: #333;stroke-width: 6px"/>
  </g>
  <g id="solid">
    <rect x="10" y="10" width="108" height="108" style="fill: #555;stroke: #555;stroke-width: 6px"/>
  </g>
  <g id="color">
    <rect x="10" y="10" width="108" height="108" style="fill: #0f0;stroke: #000;stroke-width: 3px"/>
  </g>
</svg>

The SVG file may then be uploaded to an /svg folder of your PodBuilder project. Use the Files tab to do this.

For example, if your pod is called acmePodExt and the SVG is called myIcon.svg, then the SVG file would be uploaded to <SkySpark>/var/proj/<someProj>/io/afPodBuilder/acmePodExt/svg/myIcon.svg.

The file name of the SVG file is important, as it is used to reference the icon from within SkySpark. Keep the name to standard Haystack tag rules and use camelCase.

From the main PodBuilder view, click Edit Meta..., go to the SkySpark tab, and change skyarc.icons to true.

If you wish to change the icon that depicts your extension in the Install Manager, then go to the Meta tab and add a property for ext.icon.

ext.icon=myIcon

You may now build and install your new pod! SkySpark usually needs to be restarted for it to pick up any new icons in a freshly installed pod.

Visit the SkySpark Icon Test page at /ui/icon-test (e.g. http://localhost:8080/ui/icon-test) to view your new icon in all it's glory!

Adding transient tags

transient tags are special in SkySpark as they denote that the containing record is NOT to be saved to Folio.

So what happens when you have a def record in Folio, and you want to declare it as being transient!? Usually, you would add the transient tag - but then... Argh!

It turns out you cannot add the transient tag to def records in Folio - that honour is only bestowed upon defs loaded from pods. See this SkySpark forum post for details.

To get around this, you may instead add the tag afPodBuilder_transient to your def records in Folio. Pod Builder will then automatically convert this marker tag to transient when the owning record is compiled into a pod.

Licensing

Pod Builder is a commercial product and requires a licence for commercial use and to enable all features.

Pod Builder Licences are tied to a SkySpark installation / host ID. This means a separate licence will need to be purchased for each SkySpark server Pod Builder is installed on. You will need to enter your SkySpark licence ID when purchasing, see Where is my SkyArc Installation ID? for details.

Pod Builder licences expire after 1 year and a further licence will need to be purchased for continued use.

Purchased licences should be downloaded to the /var/lic/ directory of your SkySpark installation.

Minor updates and bug fixes to Pod Builder may be provided free of charge, but major updates will require a new licence to be purchased.

Use of this software is bound the terms of the End User Licence Agreement (EULA) which can be found within the software download.

For support and comments, please email -------------------------.

Evaluation mode

Although free to download, Pod Builder enters into an Evaluation Mode if it does not find a valid licence; whereby all features are enabled, but only for the creation of a single pod.

To manage and create multiple pods, a valid licence may be purchased from StackHub.

Disclaimer

The software is provided "AS IS" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.