Vely logo Empower C
install  tutorials  examples
documentation  license  about

12.1.0 released on Sep 19, 2022

url-param



PURPOSE:


Manipulate URL input parameters.

SYNTAX:


url-param \
    ( create <url params> ) \
    | ( <url params> get from-request | ( from <url string> ) ) \
    | ( <url params> to [ define ] <url string> ) \
    | ( <url params> replace param <param name> with-value <param value> )


DESCRIPTION:


url-param statement manipulates URL parameter string (either the one received from a request, or created from an arbitrary URL string), parses it into name/value pairs, replaces or adds input parameters and constructs a URL string from parameters.

"create" clause creates <url params> variable that contains all the URL parameter information needed, and is used by all other url-param statements.

<url params> is of a type that provides an array of URL parameter names and values. The total number of parameters is in the member "num_of_input_params", the parameter names are in the array "names" and the parameter values are in the array "values", both of which are indexed from "0" up to (excluding) "num_of_input_params", for instance:
url-param create urlp
...
urlp.num_of_input_params
urlp.names[..]
urlp.values[..]

"to" clause creates a URL string <url string> from the <url params> variable, the example of such string:

req=do_something&par1=some_value&par2=other_value

"replace" clause replaces parameter <param name>'s value (in subclause "param") with value <param value> (in "with-value" subclause). For example, in URL string

req=do_something&par1=some_value&par2=other_value

the clause:
... replace param "par1" with-value "new_value"

would produce URL string

req=do_something&par1=new_value&par2=other_value

If the <param name> does not exist in the URL, it is added. If it does exist, its value is replaced. There is no "removing" a parameter - typically you would just assign an empty string to it to that effect.

"get" clause with "from-request" subclause obtains the current request's URL string and converts it into <url params> variable. If "from" subclause is used, then the <url params> variable is obtained from URL string <url string> - this string must be without the web address, i.e. just a URL string like

req=do_something&par1=new_value&par2=other_value

which can be produced with "to" clause.

EXAMPLES:


This example creates a new URL-param variable, obtains the URL string of the current request (which might be for instance "x=1&par1=some_value&y=2") and converts it into the URL-param variable, then replaces "par1" parameter's value and creates a new URL string from the changed URL-param variable. Next, it creates a new URL-param variable from such string and verifies the data is correct:
// Create URL-param variable
url-param create my_par

// Store input parameters from the request's URL into URL-param variable created above
url-param my_par get from-request

// Print out the parameters from the URL
num i;
for (i=0; i< my_par.num_of_input_params; i++) {
    @Parameter <<p-out my_par.names[i]>> has value of <<p-out my_par.values[i]>>
}

@Replacing parameter value...
// Replace parameter value
url-param my_par replace param "par1" with-value "NEW VALUE1"

// Store new URL into a string (web address excluded)
url-param my_par to define par_str_only params-only
@Param only part of URL is <<p-out par_str_only>>

// Make new URL-param variable from altered URL
@Create new url-param from params-only string <<p-out par_str_only>>
url-param create new_par1
url-param new_par1 get from par_str_only

// Display parameter names and values to verify 
for (i=0; i< new_par1.num_of_input_params; i++) {
    @Parameter <<p-out new_par1.names[i]>> has value of <<p-out new_par1.values[i]>>
}


SEE ALSO:


Requests ( after_request_handler   before_request_handler   global_request_data   input-param   non_request   request   startup_handler   url-param   vely_dispatch_request  )  SEE ALL (documentation)



Copyright (c) 2022 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. Icons copyright PaweĊ‚ Kuna licensed under MIT. This web page is licensed under CC-BY-SA-4.0.