HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

ocPortal Developer's Guide: Options and values

» Return to Contents



The configuration interface defines two types of configuration datum:
  • Options; these are options that a user chooses the value of and determine ocPortals behaviour
  • Values; these are stored values that usually represent pre-calculated information (such as the download bandwidth tracking value)

sources/config.php

Global_functions_config.php

Function summary

void init__config ()
boolean multi_lang ()
void load_options ()
?SHORT_TEXT get_tutorial_link (ID_TEXT name)
void set_tutorial_link (ID_TEXT name, SHORT_TEXT value)
?SHORT_TEXT get_long_value (ID_TEXT name)
?SHORT_TEXT get_long_value_newer_than (ID_TEXT name, TIME cutoff)
void set_long_value (ID_TEXT name, ?SHORT_TEXT value)
?SHORT_TEXT get_value (ID_TEXT name, ?ID_TEXT default, boolean env_also)
?SHORT_TEXT get_value_newer_than (ID_TEXT name, TIME cutoff)
void set_value (ID_TEXT name, SHORT_TEXT value)
void delete_value (ID_TEXT name)
?SHORT_TEXT get_option (ID_TEXT name, boolean missing_ok)
void update_stat (ID_TEXT stat, integer increment)
ID_TEXT invert_value (ID_TEXT old)

void init__config()

Standard code module initialisation function.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

boolean multi_lang()

Find whether to run in multi-lang mode.

Parameters…

Returns…

Description Whether to run in multi-lang mode.
Type boolean

Return to the function index for this class Expand: View the source code to this function

void load_options()

Load all config options.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

?SHORT_TEXT get_tutorial_link(ID_TEXT name)

Find a specified tutorial link identifier.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Returns…

Description The value (NULL: value not found)
Type ?SHORT_TEXT

Return to the function index for this class Expand: View the source code to this function

void set_tutorial_link(ID_TEXT name, SHORT_TEXT value)

Set the specified value to the specified tutorial link identifier.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Name value
Description The value
Type SHORT_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

?SHORT_TEXT get_long_value(ID_TEXT name)

Find a specified long value. Long values are either really long strings, or just ones you don't want on each page load (i.e. it takes a query to read them, because you don't always need them).

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Returns…

Description The value (NULL: value not found)
Type ?SHORT_TEXT

Return to the function index for this class Expand: View the source code to this function

?SHORT_TEXT get_long_value_newer_than(ID_TEXT name, TIME cutoff)

Find the specified configuration option if it is younger than a specified time.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Name cutoff
Description The cutoff time (an absolute time, not a relative "time ago";)
Type TIME

Returns…

Description The value (NULL: value newer than not found)
Type ?SHORT_TEXT

Return to the function index for this class Expand: View the source code to this function

void set_long_value(ID_TEXT name, ?SHORT_TEXT value)

Set the specified situational value to the specified long value. Long values are either really long strings, or just ones you don't want on each page load (i.e. it takes a query to read them, because you don't always need them).

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Name value
Description The value (NULL: delete it)
Type ?SHORT_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

?SHORT_TEXT get_value(ID_TEXT name, ?ID_TEXT default, boolean env_also)

Find a specified value.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Name default
Description Value to return if value not found (NULL: return NULL)
Default value
Type ?ID_TEXT

Name env_also
Description Whether to also check server environmental variables
Default value boolean-false
Type boolean

Returns…

Description The value (NULL: value not found and default is NULL)
Type ?SHORT_TEXT

Return to the function index for this class Expand: View the source code to this function

?SHORT_TEXT get_value_newer_than(ID_TEXT name, TIME cutoff)

Find the specified configuration option if it is younger than a specified time.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Name cutoff
Description The cutoff time (an absolute time, not a relative "time ago";)
Type TIME

Returns…

Description The value (NULL: value newer than not found)
Type ?SHORT_TEXT

Return to the function index for this class Expand: View the source code to this function

void set_value(ID_TEXT name, SHORT_TEXT value)

Set the specified situational value to the specified value.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Name value
Description The value
Type SHORT_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

void delete_value(ID_TEXT name)

Delete a situational value.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

?SHORT_TEXT get_option(ID_TEXT name, boolean missing_ok)

Find the value of the specified configuration option.

Parameters…

Name name
Description The name of the option
Type ID_TEXT

Name missing_ok
Description Where to accept a missing option (and return NULL)
Default value boolean-false
Type boolean

Returns…

Description The value (NULL: either null value, or no option found whilst $missing_ok set)
Type ?SHORT_TEXT

Return to the function index for this class Expand: View the source code to this function

void update_stat(ID_TEXT stat, integer increment)

Increment the specified stored value, by the specified amount.

Parameters…

Name stat
Description The codename for the stat
Type ID_TEXT

Name increment
Description What to increment the statistic by
Type integer

(No return value)


Return to the function index for this class Expand: View the source code to this function

ID_TEXT invert_value(ID_TEXT old)

Very simple function to invert the meaning of an old hidden option. We often use this when we've promoted a hidden option into a new proper option but inverted the meaning in the process - we use this in the default value generation code, as an in-line aid to preserve existing hidden option settings.

Parameters…

Name old
Description The old value
Type ID_TEXT
Values restricted to 0 1

Returns…

Description The inverted value
Type ID_TEXT

Return to the function index for this class Expand: View the source code to this function

sources/config2.php

Global_functions_config2.php

Function summary

void find_lost_option (ID_TEXT name)
void set_option (ID_TEXT name, LONG_TEXT value, ?ID_TEXT type, ?LONG_TEXT current_value)

void find_lost_option(ID_TEXT name)

An option has dissappeared somehow - find it via searching our code-base for it's install code. It doesn't get returned, just loaded up. This function will produce a fatal error if we cannot find it.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

void set_option(ID_TEXT name, LONG_TEXT value, ?ID_TEXT type, ?LONG_TEXT current_value)

Set a configuration option with the specified values.

Parameters…

Name name
Description The name of the value
Type ID_TEXT

Name value
Description The value
Type LONG_TEXT

Name type
Description The type of the option. This is normally ommited, but to save a DB lookup, may be passed through (NULL: work out the type)
Default value
Type ?ID_TEXT
Values restricted to float integer tick line text transline transtext list date forum category usergroup

Name current_value
Description The current value of the config option (NULL: unknown). This is just for efficiency for remapping language config options.
Default value
Type ?LONG_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

Tutorial - Adding a Configuration Option


Adding a configuration option is necessary for many modules, so I will show you how to do so in this tutorial.

1) Open up your module, and find the install function.

2) Add the following code:

Code (php)

do_config_option('SECTION_CHAT','is_on_chat','tick','return 1;','FEATURE','SECTION_CHAT');

Explanation:

Argument 1: The human-readable name for this configuration, this is a language INI file entry.
Argument 2: The actual backend name for this option; this is the name you will use to refer to it in code.
Argument 3: The type of the option (i.e. the type of form element used), see the templates section for further details
Argument 4: The default value, this is actually PHP code that is stored in the database and evaluated as required, so don't forget the semicolon (';')!
Argument 5: The configuration page that this option will be on.
Argument 6: The section this configuration option will be in, this is a language INI file entry.