functions

fhGetPluginDataFileName

Description

fhGetPluginDataFileName provides a file or folder name for plugins to use to store settings or other data, on a per-project, per-user, or per-machine basis. For example, the function can be used to store the last settings used, for a specific project. If the bFolder flag is set, the function will ensure that the full path name returned exists, as a folder. If the bFolder flag is not set, the function will ensure that all folders, mentioned in the path name returned exist - creating them them if necessary - except the last part, which the plugin can then itself create as either a file or folder.

The plugin name is used as the last part of the string returned. An empty string is returned if the plugin does not yet have a name, or if an error occurs.

The function will create a "Plugin Data" folder in the project folder automatically if one does not exist and return the name of a file or folder to use.

Syntax

fhGetPluginDataFileName([strScope[, bFolder]])

Parameters

strScope

Requires version 5.0.8 or later. Specifies whether the settings or other data are to be stored on a per-project, per-user or per-machine basis.

CURRENT_PROJECT	The default. The returned path is to a file or folder within the folder, 'Plugin Data', in the current project folder. The application must be in project mode. The returned path will be: <path to current project folder>\Plugin Data\<plugin name>
CURRENT_USER	The returned path is to a file or folder within the folder, 'Plugin Data' in the Family Historian application data area for the current user. The returned path will be: <path to application data for current user>\Calico Pie\Family Historian\Plugin Data\<plugin name>
LOCAL_MACHINE	The returned path is to a file or folder with the folder, 'Data' in the Plugins folder. The returned path will be: <path to Family Historian plugins folder>\Data\<plugin name>

bFolder

Requires version 5.0.8 or later. boolean. False by default. If true, the returned path is treated as a path to a folder which will be created if it does not exist.

Return Value

strFileName: The filename / folder name which should be used for storing settings and other data for the plugin.

Remarks

Note: If bFolder is not true, the file or folder is not automatically created. See examples below for different methods of use:

Example

--[[
@Title: Save Settings File
@Author: Calico Pie 2011
@LastUpdated: March 2011
@Description: Example of Reading and Writing a simple settings file, it only supports simple string variables.
]]
-- functions
 
-- Check for File
function file_exists(name)
    local f=io.open(name,"r")

    if f~=nil then io.close(f) return true

    else
        return false
    end
end
-- Split a String
function string:split(sep)

    local sep, fields = sep or ":", {}
    local pattern = string.format("([^%s]+)", sep)

    self:gsub(pattern, function(c) fields[#fields+1] = c end)

    return fields
end
 
-- Save Settings
function savesettings(settings,strFileName)
    file,err = io.open( strFileName, "w" )

    if err then
        error('unable to write settings file:'..strFileName)
    end
 

    for k,v in pairs(settings) do
        file:write(k..'='..v..'\n')

        print(k,v)
    end
    file:close()
end
function loadsettings(strFileName)

    if not(file_exists(strFileName)) then
        -- Set Default settings
        settings = {['filename']="myfile.txt",
        ['prompt']="true",
        }

    else
        -- Load Settings File
        tblsettings = {}
        -- read the file in table 'lines'
        for line in io.lines(strFileName) do

            fields = line:split('=')
            tblsettings[fields[1]] = fields[2]

        end
    end
    return tblsettings
end
 
-- Main Script
settingfile = fhGetPluginDataFileName("CURRENT_PROJECT")

mysettings = loadsettings(settingfile)
-- Update a setting
mysettings['prompt']='no'

-- Add or update a setting
mysettings['greeting']='hello world'
-- Save Settings to file
savesettings(mysettings,settingfile)