Atom Packages Documentation

Moderator: SecondMan

User avatar
SecondMan
Site Admin
Posts: 3349
Joined: Thu Jul 31, 2014 5:31 pm
Answers: 1
Location: Vancouver, Canada
Been thanked: 65 times
Contact:

Atom Packages Documentation

#1

Post by SecondMan » Sun Jan 14, 2018 3:12 pm


Creating Atom Packages


An atom package is used to define a new installable item that is accessible in the Reactor package manager.

This is a visual image of what a new atom package folder could look like:

example-atom-package.png
An example of the Atom package structure
example-atom-package.png (72.4 KiB) Viewed 192 times

A Reactor atom package is arranged with a basic file hierarchy like this:

Code: [Select all] [Expand/Collapse] [Download] (atomhierarchy.txt)
  1. com.YourCompanyName.YourPackageName (folder)
  2.     com.YourCompanyName.YourPackageName.atom (file)
  3.     Macros  (folder)
  4.         YourCompanyName (folder)
  5.         your-custom.bmp (file)
  6.         your-custom.setting (file)
  7.     Fuses (folder)
  8.         your-custom.fuse (file)
  9.     Scripts (folder)
  10.         Comp (folder)
  11.         YourCompanyName (folder)
  12.         your-script.lua (file)

The com.YourCompanyName.YourPackageName.atom file contents would look like this:

Code: [Select all] [Expand/Collapse] [Download] (com.YourCompanyName.YourPackageName.atom)
  1. Atom {
  2.     Name = "YourPackageName",
  3.     Category = "Tools",
  4.     Author = "YourCompanyName",
  5.     Version = 1.0,
  6.     Date = {2017-11-18},
  7.  
  8.     Description = [[A minimal Reactor example atom package.]],
  9.  
  10.     Deploy = {
  11.         "Macros/YourCompanyName/your-custom.setting",
  12.         "Fuses/your-custom.fuse",
  13.         "Scripts/Comp/YourCompanyName/your-script.lua",
  14.     },
  15.  
  16.     Dependencies = {
  17.         "com.wesuckless.Switch",
  18.     },
  19. }

You only need to add the intermediate folders required for the content your atom is installing. This means if you are creating an Atom package for delivering a Macro, you only need to add a "Macros/" folder and "Deploy" entry for the .setting file and its thumbnail bin icon.

Adding a Description to an Atom Package


When creating a Atom file Description entry you should place the text inside a pair of double square brackets [[Your Description Text]] so Lua will fully escape the quote characters and other symbols.

Description = [[A minimal "FUZIONMONGER" Reactor example atom package description.]],

You are able to use HTML formatted text in the description field like:

<p>This is a new paragraph of text</p>

or

<pre>This looks like monospaced source code</pre>

You can also create an HTML ordered list of items in the description field using:

Code: [Select all] [Expand/Collapse] [Download] (orderedlist.html)
  1. Description = [[<p>YourPackageName includes support for:</p>
  2.     <ul>
  3.     <li>Note 1</li>
  4.     <li>Note 2</li>
  5.     <li>Note 3</li>
  6.     <li>Note 4</li>
  7. </ul>]],

This HTML formatting creates an Atom description entry like:

YourPackageName includes support for:

  • Note 1
  • Note 2
  • Note 3
  • Note 4
The rich text formatting capability is possible since the description GUI element is created using a Fusion 9 ui:TextEdit field (which is internally done as a QTextEdit item). This means you can read the QT documentation on rich text HTML tags to see what HTML formatting tags can be used.


HTML Encoded Entity Characters

If you want to insert a < character in the description you should use the HTML encoded "entity" version &lt;. If you want to insert a > character in the description you should use the HTML encoded "entity" version &gt;.

The copyright symbol would be added using the HTML encoded "entity" version &copy;.

If you need to write multiple square brackets in an atom file's HTML based description tag, the easiest and most reliable approach is to use the HTML encoded symbol for the characters:

[ has an HTML encoded format of &#91;
] has an HTML encoded format of &#93;

If you wanted to write in Well [[hello]] there! in the text part of the atom description text field that could be entered as:

Well &#91;&#91;hello&#93;&#93; There!

You can read a summary of HTML 4 style encoded entities here.

When adding html tags to the description text, you are unable to add any <img> image tags that use an external (http) based internet URL. Also any <a href=""></a> links added in the description field will not be clickable.

Adding Emoticon Images to the Description


The atom description field supports the insertion of HTML based smilie/emoticon images. You have 19 different images to choose from:

atom-description-emoticons.png
Available Atom emoticons
atom-description-emoticons.png (13.86 KiB) Viewed 192 times

The way you add an emoticon to the HTML code in your description field is by using the following HTML "img" tag syntax:

Code: [Select all] [Expand/Collapse] [Download] (emoticons.atom)
  1. <img src="Emoticons:/banana.png">
  2. <img src="Emoticons:/bowdown.png">
  3. <img src="Emoticons:/buttrock.png">
  4. <img src="Emoticons:/cheer.png">
  5. <img src="Emoticons:/cheers.png">
  6. <img src="Emoticons:/cool.png">
  7. <img src="Emoticons:/cry.png">
  8. <img src="Emoticons:/facepalm.png">
  9. <img src="Emoticons:/lol.png">
  10. <img src="Emoticons:/mad.png">
  11. <img src="Emoticons:/mrgreen.png">
  12. <img src="Emoticons:/nocheer.png">
  13. <img src="Emoticons:/popcorn.png">
  14. <img src="Emoticons:/rolleyes.png">
  15. <img src="Emoticons:/sad.png">
  16. <img src="Emoticons:/smile.png">
  17. <img src="Emoticons:/whistle.png">
  18. <img src="Emoticons:/wink.png">
  19. <img src="Emoticons:/wip.png">

The emoticon PNG images are stored in the Reactor managed "Reactor:/UI/Emoticons/" folder.

Using Atomizer to Edit Your Atoms

You can access Atomizer using the Reactor > Tools > Atomizer menu item.

When Atomizer loads you are presented with a welcome screen. You can use this window to either open up an existing atom package with the "Open Atom Package" button, or you can click the "Create New Atom Package" button to start preparing your own content for submission to Reactor.

atomizer-welcome.png
The Atomizer Welcome page
atomizer-welcome.png (29.33 KiB) Viewed 192 times

The Create New Atom Package from Clipboard option on the welcome screen is interesting if you have a lot of similar atoms to prepare as you can copy the text from an existing .atom file into your clipboard copy/paste buffer and then use that information as the basis for creating each of your new atoms.

When you click the Create New Atom Package from Clipboard button your current copy/paste clipboard data is pre-filled into the Atomizer fields in the editing window. Note: Sometimes you might have to click this button a few times for Fusion to read the latest clipboard data and process the information. If there is an issue with the text in your clipboard you will see the output details in the Console tab.

Let's take a look at the main Atomizer window. This view is the heart of the Atomizer tool. It is where the atom editing occurs. Your atom descriptions are typed into the HTML Code Editor part of the user interface.

atomizer-emoticons.png
The Atomizer HTML code editor

The Author text field is for entering your personal or company name.

The Package Name text field is used for the name of the atom as it will be shown to the end user inside of the Reactor package manager window.

The Version field holds a floating point number like 1.2

The Category combo control menu is used to define the purpose of your atom and where it will show up inside of Reactor.

The Date Fields are where you can specify what the original release date was for the current version of your tool. You can either enter the date manually in the Year - Month - Day (YYYY)-(MM)-(DD) textfields, or you can simply press the "Today" button to enter today's date.

The Donation URL allows you to specify an optional web link URL that will be shown to the user when they install or update your atom in Reactor. Typically this is a PayPal.me based address, or a link to your personal/company webpage.

The Donation Amount field would be used to specify a dollar amount you want to be paid as a suggested donation value when the user installs your atom. This is an optional field that should only be used if you have also entered a value in the Donation URL field.

The Description section has two elements. An upper HTML Code Editor zone and a lower HTML Live Preview view.

The HTML Code Editor is a multi-line text entry field that is used to create the Atom package description text. You can enter HTML formatted text in this field and the results will be shown in the HTML Live Preview view in Atomizer. You can enter HTML bolds, italics, underline, blockquotes, pre-formatted code, unordered lists, ordered lists, list elements, images, links, tables, font color, strike through, new paragraph, and headings. It is important to know that HTML based web links are not clickable in an Atom description field.

There is an HTML formatting icon bar that can be clicked on to add new HTML code snippet elements to end of the text in the HTML Code Editor view.

The only images supported in the HTML Code Editor and in an Atom description field are local filepath based emoticon images since those pictures are built into Reactor. This limitation comes from the ui:TextEdit GUI element that is used in the Reactor package manager window since it lacks support for displaying internet HTTP based image URLs.

The Dependencies section lets you list other Reactor atom packages that are required in order for your atom to function correctly. These extra atoms will be installed automatically by Reactor when an end user chooses to add your atom to their system.

The Deploy text fields are where the content that will be installed by Reactor is listed. The Common (No Architecture) text field is where material like fuses, macros, and scripts are added that work across all of Fusion's supported os platforms. If you are deploying a plugin that only works on a specific OS platform you can enter that file in the appropriate heading like "Windows", "Mac", or "Linux". The Deploy fields are case-sensitive and must match the filenames on disk that are included with your atom package.

To the far right of the Deploy section is a Refresh icon that looks like a pair of spinning arrows. You can press that button to instantly refresh the entries in the Deploy fields based upon the content in your Atom package folder. The "Refresh" button doesn't automatically save this edit to the atom file so you can close the Atomizer window with the Close Atom button if you don't like the changes that have been made to the Deploy list.

The Working Directory section lists the local filepath for the current .atom file that is loaded in the Atomizer view. The Show Atom Folder Button to the right of the Working Directory text field is used to quickly open up a desktop folder browsing window so you can access the files inside the atom package folder.

The Close Atom button will exit the Atomizer editing session for your current .atom package file. Any unsaved edits in the Atomizer window will be discarded. You are also able to close any of the Atomizer windows using the Control + W (Win/Linux) or Command + W (MacOS) hotkeys.

The Copy BBCode button will convert the information in your .atom file into the WSL website's phpBB forum format BBCode syntax. This button helps cut down on the effort needed to create a new "WSL Reactor Submissions" thread post in the Home > Projects > Reactor > Reactor Submissions forum section on the steakunderwater website. You will still need to attach a manually zipped copy of your atom package folder your new the WSL Reactor Submissions thread post.

The Copy Atom button will place the plain text contents of your .atom file into the copy/paste clipboard buffer. The Copy Atom feature is designed to be used when you need to create multiple similar atom packages quickly and is paired with a matching Atomizer Create New Atom Package from Clipboard option that is accessible on the main welcome screen.

The View Raw Text button shows a plain text code view window that lets you see the raw atom formated package file. Atom file code syntax highlighting is supported on MacOS and Windows platforms but is disabled on Linux due to a Fusion 9 compatibility issue.

The Save Atom button is used to write your atom editing changes to disk.

Adding a Category to an Atom Package

reactor-window-categories.png
The Reactor categories
reactor-window-categories.png (31.6 KiB) Viewed 192 times

When creating an Atom package it helps to look over the existing Category entries in the Reactor GUI to see if something appropriate exists before you create a new category that performs a similar task.

Here is a quick summary of the typical Reactor categories you can choose from:

  • Bin
  • Brushes
  • Comps
  • Comps/Templates
  • Console
  • Docs
  • Fun
  • LUTs
  • Menus
  • Modifiers
  • Modules
  • Scripts
  • Scripts/Bin
  • Scripts/Comp
  • Scripts/Job
  • Scripts/Slave
  • Scripts/Reactor
  • Scripts/Tool
  • Scripts/Utility
  • Scripts/Views
  • Testing
  • Tools
  • Tools/3D
  • Tools/Color
  • Tools/Composite
  • Tools/Creator
  • Tools/Effect
  • Tools/Filter
  • Tools/Flow
  • Tools/Miscellaneous
  • Tools/Optical Flow
  • Tools/Particles
  • Tools/Plugins
  • Tools/Tracking
  • Tools/Transform
  • Tools/Warp
  • Viewshaders

Adding a Required Donation to an Atom Package

If you want to mark your Atom package as having a required (suggested) donation you can add the following Donation tag inside the Atom {} code block.


PayPal.me Links

A Donation tag with a PayPal.me based www link:
Code: [Select all] [Expand/Collapse] [Download] (paypalme.atom)
  1. Atom {
  2.     Donation = {
  3.         URL = [[http://www.paypal.me/andrewhazelden]],
  4.         Amount = "$5.00 USD",
  5.     },
  6. }`

This is a preview of the PayPal.me based donation link in the Reactor UI:

reactor-donation-view.png
The Reactor Donation view
reactor-donation-view.png (24.11 KiB) Viewed 192 times

When the Paypal.me link is clicked in the dialog you are then brought to a PayPal payment webpage that looks like this:

paypal-donation-link-webpage.png
An example Paypal donation web page
paypal-donation-link-webpage.png (86.78 KiB) Viewed 192 times


WWW Links

A Donation tag with an HTTP based www link:

  1. Atom {
  2.     Donation = {
  3.         URL = [[http://www.yourcompany.com/Products/YourPackageName/]],
  4.         Amount = "$5.00 USD",
  5.     },
  6. }


Email Links

A Donation tag with an email mailto: link:

  1. Atom {
  2.     Donation = {
  3.         URL = [[mailto:you@yourcompany.com]],
  4.         Amount = "$5.00 USD",
  5.     },
  6. }


Bitcoin Links

A Donation tag with a bitcoin link should generally use the Bitcoin URI scheme BIP21:

  1. Atom {
  2.     Donation = {
  3.         URL = [[bitcoin:<myaddress>?amount=1&message=mymsg]],
  4.         Amount = "$5.00 USD",
  5.     },
  6. }

Adding a Deploy Platform Requirement

The Deploy tag allows you to have files defined as being shared across all OS platforms, or files can be defined as being Windows/Mac/Linux platform dependent.

When you enter a specific platform entry in the Deploy tag those resources will only be installed by Reactor if it is running on that platform. This is handy if you have included customized versions of a script, resource, compiled command line tools, .dll/.so/.dylib library, or a Lua binary module for a specific OS platform.

Here is an example of a deploy tag with platform specific definitions:

Code: [Select all] [Expand/Collapse] [Download] (platforms.atom)
  1. Atom {
  2.     Deploy = {
  3.         "Scripts/Comp/YourCompanyName/your-shared-script.lua"
  4.         "Scripts/Comp/YourCompanyName/another-shared-script.lua"
  5.         "Scripts/Comp/YourCompanyName/yet-another-shared-script.lua"
  6.         Windows = {
  7.             "Scripts/Comp/YourCompanyName/WindowsOnly.lua",
  8.         },
  9.         Mac = {
  10.             "Scripts/Comp/YourCompanyName/MacOnly.lua",
  11.         },
  12.         Linux = {
  13.             "Scripts/Comp/YourCompanyName/LinuxOnly.lua",
  14.         },
  15.     },
  16. }

In this deploy example, the your-shared-script.lua, another-shared-script.lua, and yet-another-shared-script.lua entries are installed on all platforms.

The WindowsOnly.lua script is installed only if Reactor is running on a Windows system.

The MacOnly.lua script is installed only if Reactor is running on a Mac system.

The LinuxOnly.lua script is installed only if Reactor is running on a Linux system.

All filepaths entires that are specified inside a Deploy tag are going to be installed to following PathMap folder location on disk:

AllData:/Reactor/Deploy/

The AllData:/Reactor/Deploy/ PathMap location translates to:

Fusion Deploy Paths

Windows Reactor Path:

C:\ProgramData\Blackmagic Design\Fusion\Reactor\Deploy\

Mac Reactor Path:

/Library/Application Support/Blackmagic Design/Fusion/Reactor/Deploy/

Linux Reactor Path:

/var/BlackmagicDesign/Fusion/Reactor/Deploy/

Resolve Deploy Paths

Windows Reactor Path:

C:\ProgramData\Blackmagic Design\DaVinci Resolve\Fusion\Reactor\Deploy\

Mac Reactor Path:

/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Reactor/Deploy/

Linux Reactor Path:

/var/BlackmagicDesign/DaVinci Resolve/Fusion/Reactor/Deploy/



Platform Specific Deploy Entries

It is important to know that a set of platform specific deploy entries that are listed in the Atom file like this:

  1. Windows = {
  2.     "Scripts/Comp/YourCompanyName/WindowsOnly.lua",
  3. },
  4. Mac = {
  5.     "Scripts/Comp/YourCompanyName/MacOnly.lua",
  6. },
  7. Linux = {
  8.     "Scripts/Comp/YourCompanyName/LinuxOnly.lua",
  9. },

Will end up being be stored in the Atom folder hierarchy on disk like this:

com.YourCompanyName.YourPackageName/Windows/Scripts/Comp/YourCompanyName/WindowsOnly.lua
com.YourCompanyName.YourPackageName/Mac/Scripts/Comp/YourCompanyName/MacOnly.lua
com.YourCompanyName.YourPackageName/Linux/Scripts/Comp/YourCompanyName/LinuxOnly.lua

A platform specific deploy file needs to be stored inside of a folder with the intermediate folder name of "Windows", "Mac", and "Linux". This is due to the way most Fusion plugins have the same filename on Windows/Mac/Linux.

A custom compiled Fusion plugin you create would be called Your-Custom.plugin on all three supported Fusion OS platforms.

Adding a Package Dependency

You can mark your atom package as having a dependency on another Atom package.

If you add a Dependencies tag, when your Atom package is selected for installation, Reactor will automatically install each of those dependencies at the same time as your atom.

Code: [Select all] [Expand/Collapse] [Download] (dependencies.atom)
  1. Atom {
  2.     Dependencies = {
  3.         "com.wesuckless.SlashCommand",
  4.     },
  5. }

At this current time, Reactor will not remove the dependent Atom packages that are installed automatically when remove the original base package you selected.

Adding Documentation

If you want to add a single page HTML or Markdown formatted documentation file to your atom package you can do that by adding an entry in your Deploy section. This will install your documentation file to the Reactor:/Deploy/Docs/ folder.

HTML:
  1. Deploy = {
  2.     "Docs/com.YourCompanyName.YourPackageName.html"
  3. },

Markdown:
  1. Deploy = {
  2.     "Docs/com.YourCompanyName.YourPackageName.md"
  3. },

Then if you want to link to your local documentation file from your Script/Macro/Plugin the PathMap address would be:

Reactor:/Deploy/Docs/com.YourCompanyName.YourPackageName.html

Adding Fusion Minimum/Maximum Compatibility

Since atom packages are able to work across several different Fusion versions it is important to have the capability to define the minimum and maximum supported version of Fusion. This additional pair of new Minimum and Maximum Atom tags is a requirement for Reactor to be able to support the unique needs of tools deployment inside Resolve 15's Fusion page while still allowing for atom installation compatibility with Fusion 9.

If an atom package is being used to install a macro that might work perfectly well in all versions of Fusion, you can omit adding the Minimum and Maximum attributes.

These two Reactor screenshots show what you see when an atom package is prevented from running in either Fusion or Resolve.

reactor-limits-installation-to-supported-fusion-version.png
Reactor limits installation to supported Fusion version
reactor-limits-installation-to-supported-resolve-version.png
Reactor limits installation to supported Resolve version

Fusion and Resolve Version Numbers

For the purpose of atom packages, Fusion's version numbers are listed as:
  • 7.71
  • 8.0
  • 8.10
  • 8.20
  • 8.21
  • 9.00
  • 9.01
  • 9.02
  • 15
Note: The version number "15" is what Resolve 15's Fusion's page is detected as in a Lua script. When checking for a Fusion version number this value is reported to Reactor with the following Lua command:

local fuVersion = tonumber(bmd._VERSION)

Usage Examples

If an atom worked with Fusion 9.0 - 9.0.2 you could define both the `Minimum` and the `Maximum` values:
  1. Atom {
  2.     Minimum = 9.00,
  3.     Maximum = 9.02,
  4. }

If an atom only worked with Fusion 9.0.2 you could define both the `Minimum` and the `Maximum` values:
  1. Atom {
  2.     Minimum = 9.02,
  3.     Maximum = 9.02,
  4. }

If an atom package had a .fu based Menus {} entry that didn't work in Resolve 15 you could define just the `Maximum` value:
  1. Atom {
  2.     Maximum = 9.02,
  3. }

If an atom package only worked in Resolve 15 you could define just the `Minimum` value:
  1. Atom {
  2.     Minimum = 15,
  3. }

InstallScripts and UninstallScript

atom-package-installscript-confirmation-dialog.png
Atom package Installscript confirmation dialog

A new addition to the Reactor v2.0 atom package specification is the InstallScript and UninstallScript tag capability.

InstallScript = {} and UninstallScript = {} atom tags can be either Lua, or Python 2.x / Python 3.x code. Python code is defined with the addition of a !Py:, !Py2: or !Py3 prefix in the inline code block.

This InstallScript feature allows for more complex install procedures to be supported like: Automatic PathMap entry mapping, file permissions adjustments, Windows Desktop shortcut link creation for "Reactor:/Deploy/Bin/" based items, and the abillity to update the "Profile:/Fusion.prefs" settings so a script works automatically.

When an InstallScript tag is present in the atom file a "Fusion Reactor | Install Script Confirmation" dialog is shown during the atom install/update/remove processes. This confirmation dialog allows you to visually see in advance the proposed Install Script code snippet that would be run, and you have the option to click either the "Cancel Installation" button to skip running the code, or the "OK" button to run the InstallScript.

The Reactor package manager window's Description field also shows the text "Install Script: Yes" and "Uninstall Script: Yes" if either of these two items are present in the atom file. This gives you added information you can see before you choose to install the atom package.

atom-package-installscript-reactor-window.png
Atom package Installscript window in Reactor

An InstallScript element can be present in an atom file for all architectures with the use of the base InstallScript = {} and UninstallScript = {} tags.

Then entries can be added inside those tables for having code that runs on specific platforms only with the nesting of the child tags Mac = {}, Windows = {}, and Linux = {}. Multiple strings of InstallScript code can be attached inside each table area and each script element will prompt the user with a dialog window for a confirmation that you want to allow the code to run.

atom-package-installscript-code-example.png
An Atom package Installscript code example

If a developer adds an InstallScript/UninstallScript code block to their atoms they are expected to follow Lua/Python coding best practices for clarity and syntax formatting.

When a new atom is submitted to Reactor that has an InstallScript added, the developer should anticipate the need for external code review by WSL and the developer needs to be willing to accept a request to revise their code to ensure compatibility and reliability across all supported Fusion/Resolve versions of Reactor running on Windows/Mac/Linux. Highly obfuscated, messy, or unreliable InstallScript code will not be accepted in the Reactor repository as it poses an unacceptable security risk.

If you have technical questions about writing InstallScript code you should ask it in the WSL Reactor forum section before you submit your new atom package to speed up the atom submission and review process.

If you are interested in seeing InstallScript code examples check out the following atom packages in the Reactor GitLab repository:

  • com.AndrewHazelden.FusionGuiColorSwitcher
  • com.wesuckless.ReactorDocs
  • com.wesuckless.ffmpeg
  • com.wesuckless.ffmpegPermissions
  • com.wesuckless.NotepadPlusPlus
  • com.wesuckless.NotepadPlusPlusPreferences

Here is a sample InstallScript Lua code snippet from the "com.wesuckless.NotepadPlusPlusPreferences.atom" atom package. It allows Notepad++ to be specified as the default Fusion script editor on Windows:

Code: [Select all] [Expand/Collapse] [Download] (InstallScript.atom)
  1. InstallScript = {
  2.     Windows = {
  3.         [[if platform == "Windows" then
  4. -- Convert the notepad++ PathMap to an absolute file path
  5. editorPath = app:MapPath("Reactor:/Deploy/Bin/notepad++/notepad++.exe")
  6.  
  7. -- Update Fusion's "Profile:/Fusion.prefs" settings file with a new EditorPrefs entry
  8. app:SetPrefs("Global.Script.EditorPath", editorPath)
  9. app:SavePrefs()
  10.  
  11. -- Print back the result
  12. updatedEditorPath = app:GetPrefs("Global.Script.EditorPath")
  13. dprintf("[Fusion Editor Path] " .. tostring(updatedEditorPath) .. "\n")
  14.  
  15. -- Add a "Notepad++ for Fusion.lnk" Shortcut to the Desktop Folder
  16. CreateShortcut(editorPath, "Desktop:", "Notepad++ for Fusion", "file")
  17. else
  18. dprintf("[Warning] Notepad++ is only available for Windows.\n")
  19. end]],
  20.     },
  21. },
  22. UninstallScript = {
  23.     Windows = {
  24.         [[-- Update Fusion's "Profile:/Fusion.prefs" settings file to clear out the EditorPrefs entry
  25. app:SetPrefs("Global.Script.EditorPath", "")]],
  26.     },
  27. },

InstallScript and UninstallScript code blocks expose the Lua "app:" pointer variable which is equivalent to "fu:" or "fusion:". This variable can be used to change Fusion preferences with "app:SetPrefs()" or "app:GetPrefs()". You can also access PathMaps using "app:MapPath()".

Your script can find out the active operating system platform using the Lua "platform" variable which returns a value of "Mac", "Windows", or "Linux".

The "dprintf()" function can be used to debug print textual information from your script to the Reactor log file that is saved to the temp folder on the users system. This can help with troubleshooting installation issues. "dprintf()" works very similar to the standard "print()" command in Lua. (Note: The user has to manually enable the "REACTOR_DEBUG" environment variable on their system for the reactor log file writing feature to be active.)

There is a "REACTOR_DEBUG_COLLECTIONS" environment variable that can be used to help do automated testing of InstallScript codeblocks when you are creating a Reactor "Collections" category atom that uses multiple dependency tags.


UI Manager GUIs

atom-package-installscript-ui-manager-gui.png
Atom package Installscript UI Manager GUI
atom-package-installscript-ui-manager-gui.png (20.94 KiB) Viewed 192 times

It is possible to add an inline UI Manager GUI to an InstallScript that is capable of accepting user input. If you want to see an example of an Atom package that has an inline UI Manager GUI check out the "com.AndrewHazelden.FusionGuiColorSwitcher" atom on the Reactor GitLab page.

The UI Manager "ui:" pointer variable already exists inside of an InstallScript Lua script scope. This means you don't need to add the typical UI manager code entries of:

Code: [Select all] [Expand/Collapse] [Download] (ui-manager.lua)
  1.     ui = fu.UIManager
  2.     disp = bmd.UIDispatcher(ui)


Create Shortcut Function

There is an InstallScript "CreateShortcut()" function that can be used by "Bin" category based atoms to add new Windows "Shortcut" / Mac Finder Alias / Linux .desktop links to the installed binary tool/documentation on a user's desktop folder.

This feature is intended to be used only by "core" atoms in the com.wesuckless.* namespace at this time and is something that new atom Developers will have to discuss on their WSL Reactor Submission thread in advance of using the feature in their shipping atom packages to avoid overuse.

The arguments for the CreateShortcut() function are:

CreateShortcut(sourcePath, shortcutPath, shortcutName, fileType)

The "fileType" argument should be set to "file" if you are linking to a document or executable, or "folder" if you are linking to a folder on disk. This is required as Mac and Linux need that extra detail to customize how the Finder Alias/Linux .desktop links are generated.

The "sourcePath" argument is either an absolute filepath, or a relative PathMap address to the original file that you want to create the link to.

The "shortcutPath" argument is the destination folder where the desktop link will be created. You should generally use "Desktop:/" as the shortcutPath value since that is custom relative PathMap address that is supported inside this function when you want to put the resulting link on your desktop folder.

The CreateShortcut() function at runtime will automatically re-write the slash direction for each platform and any duplicate (doubled up) slashes in the filepath will be removed too.

Note: On some localized operating systems the regional language settings might change the desktop folder name to use another path. In this case the "Desktop:" based PathMap "$HOME/Desktop/" folder that is created by the atom will still hold your shortcut but it will be ignored by the host OS. In those situations the end user can manually move the files if they wish. From a technical perspective there isn't anything that can be done further in a cross-platform compatible way in Fusion Standalone and Resolve 15 to improve on this issue.

Notepad++ for Fusion Shortcut Example

atom-package-installscript-example-notepadplusplus.png
Atom package Installscript, the Notepad++ Example
atom-package-installscript-example-notepadplusplus.png (79.73 KiB) Viewed 192 times

This example creates a desktop folder based shortcut to the Notepad++ for Fusion program:

Code: [Select all] [Expand/Collapse] [Download] (InstallScript.atom)
  1. InstallScript = {
  2.     [[-- Create a shortcut link on your desktop to the Notepad++ for Fusion program
  3.     CreateShortcut(Reactor:/Deploy/Bin/notepad++/notepad++.exe, "Desktop:", "Notepad++ for Fusion", "file")]],
  4. }

Reactor Docs Shortcut Example

atom-package-installscript-example-reactor-docs.png
Atom package Installscript, the Reactor Docs Example
atom-package-installscript-example-reactor-docs.png (31.63 KiB) Viewed 192 times

This example creates a desktop folder based shortcut to the Reactor Docs folder:
Code: [Select all] [Expand/Collapse] [Download] (InstallScript.atom)
  1. InstallScript = {
  2.     [[-- Create a shortcut link on your desktop to the Reactor documentation folder
  3.     CreateShortcut("Reactor:/Deploy/Docs/ReactorDocs", "Desktop:", "ReactorDocs", "folder")]],
  4. }

Tags:

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

HTML Encoded Entities

#2

Post by AndrewHazelden » Sat Feb 10, 2018 1:18 pm

If you need to write multiple square brackets in an atom file's HTML based description tag, the easiest and most reliable approach is to use the HTML encoded symbol for the characters:

[ has an HTML encoded format of &#91;
] has an HTML encoded format of &#93;

If you wanted to write in "Well [[hello]] there!" in the text part of the atom description text field that could be entered as:

Code: Select all

Well &#91;&#91;hello&#93;&#93; There!