NAME

AmphetaDesk::Settings - Controls our configuration and settings

SYNOPSIS

    # load in our OPML.
    load_my_settings;                    # use the defaults.
    load_my_settings("/path/to/file");   # defaults + user.

    # get the value of a setting.
    my $answer = get_setting("app_os");

    # store a value in the setting name.
    set_setting("app_version", "v6.66");

    # modify user_ settings en masse.
    modify_my_settings($form);

    # save user_ settings in OPML.
    save_my_settings;                    # the default location.
    save_my_settings("/path/to/file");   # user choosable location.

DESCRIPTION

This package handles AmphetaDesk settings. It loads, modifies, and saves the settings available, as well as provides a public API to access and set the values (either existing settings, or those that the user creates). A starting configuration is not needed - built-in defaults will be used in its absence. The output format of the saved configuration is OPML (an example follows after setting descriptions).

The following is a list of every setting accessible through the API. These first ones really concern themselves with egoistic crap, the name, the owner, the version, where to find more information, etc.

    app_version                    the current version of AmphetaDesk.
    app_url                        the home URL of AmphetaDesk.
    app_copyright                  the copyright statement for AmphetaDesk.
    app_contact                    name of whom to contact for support.
    app_email                      email of whom to contact for support.
    app_os                         the operating system as per Perl's $^0.

The following depend on the location of the AmphetaDesk executable, which is determined one of three ways: the AMPHETAHOME environment variable, the user's $HOME AmphetaDesk directory, or FindBin's $Bin as a last resort.

    dir_data                       full path of the /data/ directory.
    dir_docs                       full path of the /docs/ directory.
    dir_templates                  full path of the /templates/*/ directory.
    dir_gui                        full path of the /templates/*/gui directory.
    dir_data_channels              full path of the /data/channels/ directory.
    dir_data_lists                 full path of the /data/lists/ directory.
    dir_data_internal              full path of the /data/internal/ directory.

And, now the names of various files used within AmphetaDesk. After all these settings are created, they'll be combined with various dir_'s to create full fledged file_ paths (see below). The values in parenthesis are the default names given. Overriding them would be silly and dangerous.

    names_file_log                 our log file ("AmphetaDesk.log").
    names_file_myChannels          user's subscription list ("myChannels.opml").
    names_file_mySettings          user's configuration ("mySettings.xml").
    names_file_services_channels   list from Syndic8.com ("services-channels-recent.xml").
    names_file_version             the stored version file ("version.txt").
    names_gui_macos_icon           various GUI related files ("macos_icon.pict").
    names_gui_linux_icon           various GUI related files ("linux_icon.png").
    names_gui_win_icon             various GUI related files ("win_icon.ico").
    names_gui_macos_logo           various GUI related files ("macos_logo.pict").
    names_gui_linux_logo           various GUI related files ("linux_logo.png").
    names_gui_win_logo             various GUI related files ("win_logo.bmp").

And the full path versions:

    files_log                      full path to our log file.
    files_myChannels               full path to /data/myChannels.opml.
    files_mySettings               full path to /data/mySettings.xml.
    files_services_channels        full path to Syndic8.com list.
    files_version                  full path to version file.
    files_gui_macos_icon           various GUI related files.
    files_gui_linux_icon           various GUI related files.
    files_gui_win_icon             various GUI related files.
    files_gui_macos_logo           various GUI related files.
    files_gui_linux_logo           various GUI related files.
    files_gui_win_logo             various GUI related files.

These are various settings which don't fall nicely into any of our other categories. They're not saved in the user's configuration OPML - they're either one shots, or are specific to the currently running process:

    urls_services_channels         not currently implemented.
    urls_version_current           where to find the version info.
    webserver_port                 the bound port for the webserver.

And finally, all the user settings:

    user_allow_nonlocal_conn       should we be Web-accessible? Boolean (0)
    user_browser_path              what browser should AmphetaDesk use? (default)
    user_channels_check_interval   check for new channel data every x minutes (180).
    user_link_target               defaults to a new browser window (_blank).
    user_proxy_server              proxy server. must be "http://server:port".
    user_proxy_username            authentication details for the proxy server.
    user_proxy_password            authentication details for the proxy server.
    user_start_radio_webserver     listen to Radio Userland requests? Boolean (0).
    user_request_timeout           the timeout for Net requests, in seconds (10).
    user_webserver_address         IP or hostname of the local webserver (127.0.0.1).
    user_webserver_ports           possible ports for local webserver (8888,4888,48888).

The user_ settings are saved in the OPML as below. Note that the fields are stored in a random manner - the order has no effect whatsoever. They're listed here alphabetically for better referencing with the above descriptions:

   <?xml version="1.0"?>
   <settings>
     <user>
       <allow_nonlocal_conn>0</allow_nonlocal_conn>
       <browser_path>default</browser_path>
       <channels_check_interval>180</channels_check_interval>
       <link_target>_blank</link_target>
       <proxy_password></proxy_password>
       <proxy_server></proxy_server>
       <proxy_username></proxy_username>
       <request_timeout>10</request_timeout>
       <start_radio_webserver></start_radio_webserver>
       <webserver_address>127.0.0.1</webserver_address>
       <webserver_ports>8888,4888,48888</webserver_ports>
     </user>
   </settings>

METHODS

get_setting and set_setting: These routines get or set values that can be used throughout AmphetaDesk. get_setting accepts one value, the name of the setting you want the value from. If the setting exists, the value is returned. If it doesn't, undef is returned instead. set_setting accepts two inputs, the first being the name of the setting you want to create or change, and the second being the actual value. It returns the setting value you pass it.

load_my_settings: This routine accepts one optional value, which is the full path to an OPML file containing the user's configuration. If this file does not exist, or a configuration was not passed, it will use the default AmphetaDesk settings. This routine always returns positively.

modify_my_settings($hashref): This routine looks in the passed hash reference for keys that start with user_. If it finds any, it will replace the existing values with the values in the hashref. This is useful for doing mass rewriting all at once - we currently do this when people use the "My Settings" page to change their user settings. Once the settings have been modified, we save the new user settings to disk. This routine always returns successfully.

save_my_settings: This routine accepts one optional value, which is the full path where you want the user's configuration saved in OPML format. If this file does not exist, or a file path was not passed, it will save these values to the default location, /data/mySettings.xml. This routine returns 1 if the save was successful, or 0 otherwise.

AUTHOR

Morbus Iff, <morbus@disobey.com>

COPYRIGHT AND LICENSE