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: URLs

» Return to Contents



With such a complex and powerful Content Management System/Portal as ocPortal, it needs it's own URL functions, just to navigate around itself!

ocPortal transfers certain on-the-fly options around itself by naming them with the prefix 'keep_' and putting them into the URL. Once inside the URL, the URL functions will preserve them from one link to another.

sources/urls.php

Global_functions_urls.php

Function summary

void init__urls ()
URLPATH get_self_url_easy ()
mixed get_self_url (boolean evaluate, boolean root_if_posted, ?array extra_params, boolean posted_too, boolean avoid_remap)
URLPATH ocp_url_encode (URLPATH url_part, ?boolean consider_rewrite)
URLPATH ocp_url_encode_mini (URLPATH url_part, ?boolean consider_rewrite)
URLPATH ocp_url_decode_post_process (URLPATH url_part)
URLPATH remove_url_mistakes (URLPATH url)
boolean skippable_keep (string key, string val)
boolean tacit_https ()
boolean is_page_https (ID_TEXT zone, ID_TEXT page)
boolean can_try_mod_rewrite (boolean avoid_remap)
tempcode build_url (array vars, ID_TEXT zone_name, ?array skip, boolean keep_all, boolean avoid_remap, boolean skip_keep, string hash)
boolean url_monikers_enabled ()
string _build_url (array vars, ID_TEXT zone_name, ?array skip, boolean keep_all, boolean avoid_remap, boolean skip_keep, string hash)
?URLPATH _url_rewrite_params (ID_TEXT zone_name, array vars, boolean force_index_php)
boolean url_is_local (URLPATH url)
boolean looks_like_url (string value, boolean lax)
tempcode build_keep_form_fields (ID_TEXT page, boolean keep_all, ?array exclude)
tempcode build_keep_post_fields (?array exclude)
string url_to_filename (URLPATH url_full)
URLPATH qualify_url (URLPATH url, URLPATH url_base)
array page_link_decode (SHORT_TEXT param)
?PATH convert_url_to_path (URLPATH url)
URLPATH fixup_protocolless_urls (URLPATH in)
string url_to_pagelink (URLPATH url, boolean abs_only, boolean perfect_only)
string page_path_to_pagelink (string page)
void load_moniker_hooks ()
?string find_id_moniker (array url_parts)

void init__urls()

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

URLPATH get_self_url_easy()

Get a well formed URL equivalent to the current URL. Reads direct from the environment and does no clever mapping at all. This function should rarely be used.

Parameters…

Returns…

Description The URL
Type URLPATH

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

mixed get_self_url(boolean evaluate, boolean root_if_posted, ?array extra_params, boolean posted_too, boolean avoid_remap)

Get a well formed URL equivalent to the current URL.

Parameters…

Name evaluate
Description Whether to evaluate the URL (so as we don't return tempcode)
Default value boolean-false
Type boolean

Name root_if_posted
Description Whether to direct to the default page if there was a POST request leading to where we are now (i.e. to avoid missing post fields when we go to this URL)
Default value boolean-false
Type boolean

Name extra_params
Description A map of extra parameters for the URL (NULL: none)
Default value
Type ?array

Name posted_too
Description Whether to also keep POSTed data, in the GET request (useful if either_param is used to get the data instead of post_param - of course the POST data must be of the not--persistant-state-changing variety)
Default value boolean-false
Type boolean

Name avoid_remap
Description Whether to avoid mod_rewrite (sometimes essential so we can assume the standard URL parameter addition scheme in templates)
Default value boolean-false
Type boolean

Returns…

Description The URL (tempcode or string)
Type mixed

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

URLPATH ocp_url_encode(URLPATH url_part, ?boolean consider_rewrite)

Encode a URL component in such a way that it won't get nuked by Apache %2F blocking security and url encoded '&' screwing. The get_param function will map it back. Hackerish but necessary.

Parameters…

Name url_part
Description The URL to encode
Type URLPATH

Name consider_rewrite
Description Whether we have to consider mod_rewrite (NULL: don't know, look up)
Default value
Type ?boolean

Returns…

Description The encoded result
Type URLPATH

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

URLPATH ocp_url_encode_mini(URLPATH url_part, ?boolean consider_rewrite)

Encode a URL component, as per ocp_url_encode but without slashes being encoded.

Parameters…

Name url_part
Description The URL to encode
Type URLPATH

Name consider_rewrite
Description Whether we have to consider mod_rewrite (NULL: don't know, look up)
Default value
Type ?boolean

Returns…

Description The encoded result
Type URLPATH

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

URLPATH ocp_url_decode_post_process(URLPATH url_part)

Decode a URL component that was encoded with hackerish_url_encode

Parameters…

Name url_part
Description The URL to encode
Type URLPATH

Returns…

Description The encoded result
Type URLPATH

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

URLPATH remove_url_mistakes(URLPATH url)

Map spaces to %20 and put http:// in front of URLs starting www.

Parameters…

Name url
Description The URL to fix
Type URLPATH

Returns…

Description The fixed result
Type URLPATH

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

boolean skippable_keep(string key, string val)

Find whether we can skip the normal preservation of a keep value, for whatever reason.

Parameters…

Name key
Description Parameter name
Type string

Name val
Description Parameter value
Type string

Returns…

Description Whether we can skip it
Type boolean

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

boolean tacit_https()

Are we currently running HTTPS.

Parameters…

Returns…

Description If we are
Type boolean

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

boolean is_page_https(ID_TEXT zone, ID_TEXT page)

Find whether the specified page is to use HTTPS (if not -- it will use HTTP).All images (etc) on a HTTPS page should use HTTPS to avoid mixed-content browser notices.

Parameters…

Name zone
Description The zone the page is in
Type ID_TEXT

Name page
Description The page codename
Type ID_TEXT

Returns…

Description Whether the page is to run across an HTTPS connection
Type boolean

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

boolean can_try_mod_rewrite(boolean avoid_remap)

Find if mod_rewrite is in use

Parameters…

Name avoid_remap
Description Whether to explicitly avoid using mod_rewrite. Whilst it might seem weird to put this in as a function parameter, it removes duplicated logic checks in the code.
Default value boolean-false
Type boolean

Returns…

Description Whether mod_rewrite is in use
Type boolean

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

tempcode build_url(array vars, ID_TEXT zone_name, ?array skip, boolean keep_all, boolean avoid_remap, boolean skip_keep, string hash)

Build and return a proper URL, from the $vars array.Note: URL parameters should always be in lower case (one of the coding standards)

Parameters…

Name vars
Description A map of parameter names to parameter values. E.g. array('page'=>'example','type'=>'foo','id'=>2). Values may be strings or integers, or Tempcode, or NULL. NULL indicates "skip this". 'page' cannot be NULL.
Type array

Name zone_name
Description The zone the URL is pointing to. YOU SHOULD NEVER HARD CODE THIS- USE '_SEARCH', '_SELF' (if you're self-referencing your own page) or the output of get_module_zone.
Default value
Type ID_TEXT

Name skip
Description Variables to explicitly not put in the URL (perhaps because we have $keep_all set, or we are blocking certain keep_ values). The format is of a map where the keys are the names, and the values are 1. (NULL: don't skip any)
Default value
Type ?array

Name keep_all
Description Whether to keep all non-skipped parameters that were in the current URL, in this URL
Default value boolean-false
Type boolean

Name avoid_remap
Description Whether to avoid mod_rewrite (sometimes essential so we can assume the standard URL parameter addition scheme in templates)
Default value boolean-false
Type boolean

Name skip_keep
Description Whether to skip actually putting on keep_ parameters (rarely will this skipping be desirable)
Default value boolean-false
Type boolean

Name hash
Description Hash portion of the URL (blank: none). May or may not start '#' - code will put it on if needed
Default value
Type string

Returns…

Description The URL in tempcode format.
Type tempcode

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

boolean url_monikers_enabled()

Find whether URL monikers are enabled.

Parameters…

Returns…

Description Whether URL monikers are enabled.
Type boolean

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

string _build_url(array vars, ID_TEXT zone_name, ?array skip, boolean keep_all, boolean avoid_remap, boolean skip_keep, string hash)

Build and return a proper URL, from the $vars array.Note: URL parameters should always be in lower case (one of the coding standards)

Parameters…

Name vars
Description A map of parameter names to parameter values. Values may be strings or integers, or NULL. NULL indicates "skip this". 'page' cannot be NULL.
Type array

Name zone_name
Description The zone the URL is pointing to. YOU SHOULD NEVER HARD CODE THIS- USE '_SEARCH', '_SELF' (if you're self-referencing your own page) or the output of get_module_zone.
Default value
Type ID_TEXT

Name skip
Description Variables to explicitly not put in the URL (perhaps because we have $keep_all set, or we are blocking certain keep_ values). The format is of a map where the keys are the names, and the values are 1. (NULL: don't skip any)
Default value
Type ?array

Name keep_all
Description Whether to keep all non-skipped parameters that were in the current URL, in this URL
Default value boolean-false
Type boolean

Name avoid_remap
Description Whether to avoid mod_rewrite (sometimes essential so we can assume the standard URL parameter addition scheme in templates)
Default value boolean-false
Type boolean

Name skip_keep
Description Whether to skip actually putting on keep_ parameters (rarely will this skipping be desirable)
Default value boolean-false
Type boolean

Name hash
Description Hash portion of the URL (blank: none).
Default value
Type string

Returns…

Description The URL in string format.
Type string

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

?URLPATH _url_rewrite_params(ID_TEXT zone_name, array vars, boolean force_index_php)

Attempt to use mod_rewrite to improve this URL.

Parameters…

Name zone_name
Description The name of the zone for this
Type ID_TEXT

Name vars
Description A map of variables to include in our URL
Type array

Name force_index_php
Description Force inclusion of the index.php name into a short URL, so something may tack on extra parameters to the result here
Default value boolean-false
Type boolean

Returns…

Description The improved URL (NULL: couldn't do anything)
Type ?URLPATH

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

boolean url_is_local(URLPATH url)

Find if the specified URL is local or not (actually, if it is relative). This is often used by code that wishes to use file system functions on URLs (ocPortal will store such relative local URLs for uploads, etc)

Parameters…

Name url
Description The URL to check
Type URLPATH

Returns…

Description Whether the URL is local
Type boolean

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

boolean looks_like_url(string value, boolean lax)

Find if a value appears to be some kind of URL (possibly an ocPortalised Comcode one).

Parameters…

Name value
Description The value to check
Type string

Name lax
Description Whether to be a bit lax in the check
Default value boolean-false
Type boolean

Returns…

Description Whether the value appears to be a URL
Type boolean

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

tempcode build_keep_form_fields(ID_TEXT page, boolean keep_all, ?array exclude)

Get hidden fields for a form representing 'keep_x'. If we are having a GET form instead of a POST form, we need to do this. This function also encodes the page name, as we'll always want that.

Parameters…

Name page
Description The page for the form to go to (blank: don't attach)
Default value
Type ID_TEXT

Name keep_all
Description Whether to keep all elements of the current URL represented in this form (rather than just the keep_ fields, and page)
Default value boolean-false
Type boolean

Name exclude
Description A list of parameters to exclude (NULL: don't exclude any)
Default value
Type ?array

Returns…

Description The builtup hidden form fields
Type tempcode

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

tempcode build_keep_post_fields(?array exclude)

Relay all POST variables for this URL, to the URL embedded in the form.

Parameters…

Name exclude
Description A list of parameters to exclude (NULL: exclude none)
Default value
Type ?array

Returns…

Description The builtup hidden form fields
Type tempcode

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

string url_to_filename(URLPATH url_full)

Takes a URL, and converts it into a file system storable filename. This is used to cache URL contents to the servers filesystem.

Parameters…

Name url_full
Description The URL to convert to an encoded filename
Type URLPATH

Returns…

Description A usable filename based on the URL
Type string

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

URLPATH qualify_url(URLPATH url, URLPATH url_base)

Take a URL and base-URL, and fully qualify the URL according to it.

Parameters…

Name url
Description The URL to fully qualified
Type URLPATH

Name url_base
Description The base-URL
Type URLPATH

Returns…

Description Fully qualified URL
Type URLPATH

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

array page_link_decode(SHORT_TEXT param)

Take a page link and convert to attributes and zone.

Parameters…

Name param
Description The page link
Type SHORT_TEXT

Returns…

Description Triple: zone, attribute-array, hash part of a URL including the hash (or blank)
Type array

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

?PATH convert_url_to_path(URLPATH url)

Convert a URL to a local file path.

Parameters…

Name url
Description The value to convert
Type URLPATH

Returns…

Description File path (NULL: is not local)
Type ?PATH

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

URLPATH fixup_protocolless_urls(URLPATH in)

Sometimes users don't enter full URLs but do intend for them to be absolute. This code tries to see what relative URLs are actually absolute ones, via an algorithm. It then fixes the URL.

Parameters…

Name in
Description The URL to fix
Type URLPATH

Returns…

Description The fixed URL (or original one if no fix was needed)
Type URLPATH

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

string url_to_pagelink(URLPATH url, boolean abs_only, boolean perfect_only)

Convert a local URL to a page-link.

Parameters…

Name url
Description The URL to convert. Note it may not be a short URL, and it must be based on the local base URL (else failure WILL occur).
Type URLPATH

Name abs_only
Description Whether to only convert absolute URLs. Turn this on if you're not sure what you're passing is a URL not and you want to be extra safe.
Default value boolean-false
Type boolean

Name perfect_only
Description Whether to only allow perfect conversions.
Default value boolean-true
Type boolean

Returns…

Description The page link (blank: could not convert).
Type string

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

string page_path_to_pagelink(string page)

Convert a local page file path to a written page-link.

Parameters…

Name page
Description The path.
Type string

Returns…

Description The page link (blank: could not convert).
Type string

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

void load_moniker_hooks()

Load up hooks needed to detect how to use monikers.

Parameters…

(No return value)


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

?string find_id_moniker(array url_parts)

Find the textual moniker for a typical ocPortal URL path. This will be called from inside build_url, based on details learned from a moniker hook (only if a hook exists to hint how to make the requested link SEO friendly).

Parameters…

Name url_parts
Description The URL component map (must contain 'page', 'type', and 'id' if this function is to do anything).
Type array

Returns…

Description The moniker ID (NULL: could not find)
Type ?string

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