diff options
Diffstat (limited to 'user_guide_src/source/libraries')
| -rw-r--r-- | user_guide_src/source/libraries/input.rst | 40 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/language.rst | 90 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/pagination.rst | 78 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/parser.rst | 230 |
4 files changed, 320 insertions, 118 deletions
diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst index f9dbf1686..112347129 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -108,7 +108,7 @@ Class Reference .. method:: post([$index = NULL[, $xss_clean = NULL]]) - :param string $index: POST parameter name + :param mixed $index: POST parameter name :param bool $xss_clean: Whether to apply XSS filtering :returns: $_POST if no parameters supplied, otherwise the POST value if found or NULL if not :rtype: mixed @@ -136,10 +136,20 @@ Class Reference $this->input->post(NULL, TRUE); // returns all POST items with XSS filter $this->input->post(NULL, FALSE); // returns all POST items without XSS filter + + To return an array of multiple POST parameters, pass all the required keys + as an array. + :: + $this->input->post(array('field1', 'field2')); + + Same rule applied here, to retrive the parameters with XSS filtering enabled, set the + second parameter to boolean TRUE. + :: + $this->input->post(array('field1', 'field2'), TRUE); .. method:: get([$index = NULL[, $xss_clean = NULL]]) - :param string $index: GET parameter name + :param mixed $index: GET parameter name :param bool $xss_clean: Whether to apply XSS filtering :returns: $_GET if no parameters supplied, otherwise the GET value if found or NULL if not :rtype: mixed @@ -157,6 +167,16 @@ Class Reference $this->input->get(NULL, TRUE); // returns all GET items with XSS filter $this->input->get(NULL, FALSE); // returns all GET items without XSS filtering + + To return an array of multiple GET parameters, pass all the required keys + as an array. + :: + $this->input->get(array('field1', 'field2')); + + Same rule applied here, to retrive the parameters with XSS filtering enabled, set the + second parameter to boolean TRUE. + :: + $this->input->get(array('field1', 'field2'), TRUE); .. method:: post_get($index[, $xss_clean = NULL]) @@ -188,7 +208,7 @@ Class Reference .. method:: cookie([$index = NULL[, $xss_clean = NULL]]) - :param string $index: COOKIE parameter name + :param mixed $index: COOKIE name :param bool $xss_clean: Whether to apply XSS filtering :returns: $_COOKIE if no parameters supplied, otherwise the COOKIE value if found or NULL if not :rtype: mixed @@ -198,10 +218,15 @@ Class Reference $this->input->cookie('some_cookie'); $this->input->cookie('some_cookie, TRUE); // with XSS filter + + To return an array of multiple cookie values, pass all the required keys + as an array. + :: + $this->input->cookie(array('some_cookie', 'some_cookie2')); .. method:: server($index[, $xss_clean = NULL]) - :param string $index: Value name + :param mixed $index: Value name :param bool $xss_clean: Whether to apply XSS filtering :returns: $_SERVER item value if found, NULL if not :rtype: mixed @@ -211,9 +236,14 @@ Class Reference $this->input->server('some_data'); + To return an array of multiple ``$_SERVER`` values, pass all the required keys + as an array. + :: + $this->input->server(array('SERVER_PROTOCOL', 'REQUEST_URI')); + .. method:: input_stream([$index = NULL[, $xss_clean = NULL]]) - :param string $index: Key name + :param mixed $index: Key name :param bool $xss_clean: Whether to apply XSS filtering :returns: Input stream array if no parameters supplied, otherwise the specified value if found or NULL if not :rtype: mixed diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst index 6949c11c9..c3f9b6d5a 100644 --- a/user_guide_src/source/libraries/language.rst +++ b/user_guide_src/source/libraries/language.rst @@ -5,14 +5,24 @@ Language Class The Language Class provides functions to retrieve language files and lines of text for purposes of internationalization. -In your CodeIgniter system folder you'll find one called language -containing sets of language files. You can create your own language -files as needed in order to display error and other messages in other -languages. - -Language files are typically stored in your **system/language/** directory. -Alternately you can create a directory called language inside your -application folder and store them there. CodeIgniter will always load the +In your CodeIgniter **system** folder, you will find a **language** +subfolder containing a set of language files for the **english** idiom. +The files in this folder (**system/language/english/**) define the regular messages, +error messages, and other generally output terms or expressions, for the different parts +of the CodeIgniter core framework. + +You can create or incorporate your own language +files, as needed, in order to provide application-specific error and other messages, +or to provide translations of the core messages into other languages. +These translations or additional messages would go inside your application/language folder, +with separate subfolders for each idiom (for instance french or german). + +The CodeIgniter framework comes with a set of language files for the "english" idiom. +Additional approved translations for different idioms may be found in the +`CodeIgniter 3 Translations repositories <https://github.com/codeigniter3-translations>`_. +Each repository deals with a single idiom. + +When CodeIgniter loads language files, it will load the one in **system/language/** first and will then look for an override in your **application/language/** directory. @@ -26,6 +36,70 @@ your **application/language/** directory. <div class="custom-index container"></div> +*************************** +Handling Multiple Languages +*************************** + +If you want to support multiple languages in your application, you would provide folders inside +your **application/language/** directory for each of them, and you would specify the default +language in your **application/config/config.php**. + +The **application/language/english/** directory would contain any additional language files +needed by your application, for instance for error messages. + +Each of the other idiom-specific directories would contain the core language files that you +obtained from the translations repositories, or that you translated yourself, as well as +any additional ones needed by your application. + +You would store the language you are currently using, for instance in a session variable. + +Sample Language Files +===================== + +:: + + system/ + language/ + english/ + ... + email_lang.php + form_validation_lang.php + ... + + application/ + language/ + english/ + error_messages_lang.php + french/ + ... + email_lang.php + error_messages_lang.php + form_validation_lang.php + ... + +Example of switching languages +============================== + +:: + + $idiom = $this->session->get_userdata('language'); + $this->lang->load('error_messages',$idiom); + $oops = $this->lang->line('nessage_key'); + +******************** +Internationalization +******************** + +The Language class in CodeIgniter is meant to provide an easy and lightweight way to support multiple +languages in your application. It is not meant to be a full implementation of what is commonly called +`internationalization and localization <http://en.wikipedia.org/wiki/Internationalization_and_localization>`_. + +We use the term "idiom" to refer to a language using its common name, +rather than using any of the international standards, such as "en", "en-US", or "en-CA-x-ca" for English +and some of its variants. + +.. note:: There is nothing to prevent you from using those abbreviations in your application! + ************************ Using the Language Class ************************ diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 8a62376f1..8c5c2c63a 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -73,29 +73,25 @@ Customizing the Pagination The following is a list of all the preferences you can pass to the initialization function to tailor the display. -$config['uri_segment'] = 3; -=========================== +**$config['uri_segment'] = 3;** The pagination function automatically determines which segment of your URI contains the page number. If you need something different you can specify it. -$config['num_links'] = 2; -========================= +**$config['num_links'] = 2;** The number of "digit" links you would like before and after the selected page number. For example, the number 2 will place two digits on either side, as in the example links at the very top of this page. -$config['use_page_numbers'] = TRUE; -=================================== +**$config['use_page_numbers'] = TRUE;** By default, the URI segment will use the starting index for the items you are paginating. If you prefer to show the the actual page number, set this to TRUE. -$config['page_query_string'] = TRUE; -==================================== +**$config['page_query_string'] = TRUE;** By default, the pagination library assume you are using :doc:`URI Segments <../general/urls>`, and constructs your links something @@ -113,8 +109,7 @@ the pagination link will become:: Note that "per_page" is the default query string passed, however can be configured using ``$config['query_string_segment'] = 'your_string'`` -$config['reuse_query_string'] = FALSE; -====================================== +**$config['reuse_query_string'] = FALSE;** By default your Query String arguments (nothing to do with other query string options) will be ignored. Setting this config to @@ -126,14 +121,12 @@ URL after the URI segment and before the suffix.:: This helps you mix together normal :doc:`URI Segments <../general/urls>` as well as query string arguments, which until 3.0 was not possible. -$config['prefix'] = ''; -======================= +**$config['prefix'] = '';** A custom prefix added to the path. The prefix value will be right before the offset segment. -$config['suffix'] = ''; -======================= +**$config['suffix'] = '';** A custom suffix added to the path. The sufix value will be right after the offset segment. @@ -145,13 +138,11 @@ Adding Enclosing Markup If you would like to surround the entire pagination with some markup you can do it with these two preferences: -$config['full_tag_open'] = '<p>'; -================================= +**$config['full_tag_open'] = '<p>';** The opening tag placed on the left side of the entire result. -$config['full_tag_close'] = '</p>'; -=================================== +**$config['full_tag_close'] = '</p>';** The closing tag placed on the right side of the entire result. @@ -159,26 +150,22 @@ The closing tag placed on the right side of the entire result. Customizing the First Link ************************** -$config['first_link'] = 'First'; -================================ +**$config['first_link'] = 'First';** The text you would like shown in the "first" link on the left. If you do not want this link rendered, you can set its value to FALSE. .. note:: This value can also be translated via a language file. -$config['first_tag_open'] = '<div>'; -==================================== +**$config['first_tag_open'] = '<div>';** The opening tag for the "first" link. -$config['first_tag_close'] = '</div>'; -====================================== +**$config['first_tag_close'] = '</div>';** The closing tag for the "first" link. -$config['first_url'] = ''; -========================== +**$config['first_url'] = '';** An alternative URL to use for the "first page" link. @@ -186,21 +173,18 @@ An alternative URL to use for the "first page" link. Customizing the Last Link ************************* -$config['last_link'] = 'Last'; -============================== +**$config['last_link'] = 'Last';** The text you would like shown in the "last" link on the right. If you do not want this link rendered, you can set its value to FALSE. .. note:: This value can also be translated via a language file. -$config['last_tag_open'] = '<div>'; -=================================== +**$config['last_tag_open'] = '<div>';** The opening tag for the "last" link. -$config['last_tag_close'] = '</div>'; -===================================== +**$config['last_tag_close'] = '</div>';** The closing tag for the "last" link. @@ -208,21 +192,18 @@ The closing tag for the "last" link. Customizing the "Next" Link *************************** -$config['next_link'] = '>'; -============================== +**$config['next_link'] = '>';** The text you would like shown in the "next" page link. If you do not want this link rendered, you can set its value to FALSE. .. note:: This value can also be translated via a language file. -$config['next_tag_open'] = '<div>'; -=================================== +**$config['next_tag_open'] = '<div>';** The opening tag for the "next" link. -$config['next_tag_close'] = '</div>'; -===================================== +**$config['next_tag_close'] = '</div>';** The closing tag for the "next" link. @@ -230,21 +211,18 @@ The closing tag for the "next" link. Customizing the "Previous" Link ******************************* -$config['prev_link'] = '<'; -============================== +**$config['prev_link'] = '<';** The text you would like shown in the "previous" page link. If you do not want this link rendered, you can set its value to FALSE. .. note:: This value can also be translated via a language file. -$config['prev_tag_open'] = '<div>'; -=================================== +**$config['prev_tag_open'] = '<div>';** The opening tag for the "previous" link. -$config['prev_tag_close'] = '</div>'; -===================================== +**$config['prev_tag_close'] = '</div>';** The closing tag for the "previous" link. @@ -252,13 +230,11 @@ The closing tag for the "previous" link. Customizing the "Current Page" Link *********************************** -$config['cur_tag_open'] = '<b>'; -================================ +**$config['cur_tag_open'] = '<b>';** The opening tag for the "current" link. -$config['cur_tag_close'] = '</b>'; -================================== +**$config['cur_tag_close'] = '</b>';** The closing tag for the "current" link. @@ -266,13 +242,11 @@ The closing tag for the "current" link. Customizing the "Digit" Link **************************** -$config['num_tag_open'] = '<div>'; -================================== +**$config['num_tag_open'] = '<div>';** The opening tag for the "digit" link. -$config['num_tag_close'] = '</div>'; -==================================== +**$config['num_tag_close'] = '</div>';** The closing tag for the "digit" link. diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 5af504a03..e7c7e3abd 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -2,24 +2,26 @@ Template Parser Class ##################### -The Template Parser Class enables you to parse pseudo-variables -contained within your view files. It can parse simple variables or -variable tag pairs. If you've never used a template engine, -pseudo-variables look like this:: +The Template Parser Class can perform simple text substitution for +pseudo-variables contained within your view files. +It can parse simple variables or variable tag pairs. + +If you've never used a template engine, +pseudo-variable names are enclosed in braces, like this:: <html> - <head> - <title>{blog_title}</title> - </head> - <body> - - <h3>{blog_heading}</h3> - - {blog_entries} - <h5>{title}</h5> - <p>{body}</p> - {/blog_entries} - </body> + <head> + <title>{blog_title}</title> + </head> + <body> + + <h3>{blog_heading}</h3> + + {blog_entries} + <h5>{title}</h5> + <p>{body}</p> + {/blog_entries} + </body> </html> These variables are not actual PHP variables, but rather plain text @@ -28,8 +30,9 @@ representations that allow you to eliminate PHP from your templates .. note:: CodeIgniter does **not** require you to use this class since using pure PHP in your view pages lets them run a little faster. - However, some developers prefer to use a template engine if they work - with designers who they feel would find some confusion working with PHP. + However, some developers prefer to use a template engine if + they work with designers who they feel would find some + confusion working with PHP. .. important:: The Template Parser Class is **not** a full-blown template parsing solution. We've kept it very lean on purpose in order @@ -42,6 +45,10 @@ representations that allow you to eliminate PHP from your templates <div class="custom-index container"></div> +******************************* +Using the Template Parser Class +******************************* + Initializing the Class ====================== @@ -56,12 +63,13 @@ $this->parser Parsing templates ================= -You can use the ``parse()`` method to parse (or render) simple templates, like this:: +You can use the ``parse()`` method to parse (or render) simple templates, +like this:: $data = array( - 'blog_title' => 'My Blog Title', - 'blog_heading' => 'My Blog Heading' - ); + 'blog_title' => 'My Blog Title', + 'blog_heading' => 'My Blog Heading' + ); $this->parser->parse('blog_template', $data); @@ -74,7 +82,7 @@ template would contain two variables: {blog_title} and {blog_heading} There is no need to "echo" or do something with the data returned by $this->parser->parse(). It is automatically passed to the output class to be sent to the browser. However, if you do want the data returned -instead of sent to the output class you can pass TRUE (boolean) to the +instead of sent to the output class you can pass TRUE (boolean) as the third parameter:: $string = $this->parser->parse('blog_template', $data, TRUE); @@ -88,24 +96,24 @@ iteration containing new values? Consider the template example we showed at the top of the page:: <html> - <head> - <title>{blog_title}</title> - </head> - <body> - - <h3>{blog_heading}</h3> - - {blog_entries} - <h5>{title}</h5> - <p>{body}</p> - {/blog_entries} - </body> + <head> + <title>{blog_title}</title> + </head> + <body> + + <h3>{blog_heading}</h3> + + {blog_entries} + <h5>{title}</h5> + <p>{body}</p> + {/blog_entries} + </body> </html> In the above code you'll notice a pair of variables: {blog_entries} data... {/blog_entries}. In a case like this, the entire chunk of data between these pairs would be repeated multiple times, corresponding to -the number of rows in a result. +the number of rows in the "blog_entries" element of the parameters array. Parsing variable pairs is done using the identical code shown above to parse single variables, except, you will add a multi-dimensional array @@ -114,16 +122,16 @@ corresponding to your variable pair data. Consider this example:: $this->load->library('parser'); $data = array( - 'blog_title' => 'My Blog Title', - 'blog_heading' => 'My Blog Heading', - 'blog_entries' => array( - array('title' => 'Title 1', 'body' => 'Body 1'), - array('title' => 'Title 2', 'body' => 'Body 2'), - array('title' => 'Title 3', 'body' => 'Body 3'), - array('title' => 'Title 4', 'body' => 'Body 4'), - array('title' => 'Title 5', 'body' => 'Body 5') - ) - ); + 'blog_title' => 'My Blog Title', + 'blog_heading' => 'My Blog Heading', + 'blog_entries' => array( + array('title' => 'Title 1', 'body' => 'Body 1'), + array('title' => 'Title 2', 'body' => 'Body 2'), + array('title' => 'Title 3', 'body' => 'Body 3'), + array('title' => 'Title 4', 'body' => 'Body 4'), + array('title' => 'Title 5', 'body' => 'Body 5') + ) + ); $this->parser->parse('blog_template', $data); @@ -136,13 +144,128 @@ function:: $this->load->library('parser'); $data = array( - 'blog_title' => 'My Blog Title', - 'blog_heading' => 'My Blog Heading', - 'blog_entries' => $query->result_array() - ); + 'blog_title' => 'My Blog Title', + 'blog_heading' => 'My Blog Heading', + 'blog_entries' => $query->result_array() + ); $this->parser->parse('blog_template', $data); +Usage Notes +=========== + +If you include substitution parameters that are not referenced in your +template, they are ignored:: + + $template = 'Hello, {firstname} {lastname}'; + $data = array( + 'title' => 'Mr', + 'firstname' => 'John', + 'lastname' => 'Doe' + ); + $this->parser->parse_string($template, $data); + + Result: Hello, John Doe + +If you do not include a substitution parameter that is referenced in your +template, the original pseudo-variable is shown in the result:: + + $template = 'Hello, {firstname} {initials} {lastname}'; + $data = array( + 'title' => 'Mr', + 'firstname' => 'John', + 'lastname' => 'Doe' + ); + $this->parser->parse_string($template, $data); + + Result: Hello, John {initials} Doe + +If you provide a string substitution parameter when an array is expected, +i.e. for a variable pair, the substitution is done for the opening variable +pair tag, but the closing variable pair tag is not rendered properly:: + + $template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})'; + $data = array( + 'degrees' => 'Mr', + 'firstname' => 'John', + 'lastname' => 'Doe', + 'titles' => array( + array('degree' => 'BSc'), + array('degree' => 'PhD') + + ) + ); + $this->parser->parse_string($template, $data); + + Result: Hello, John Doe (Mr{degree} {/degrees}) + +If you name one of your individual substitution parameters the same as one +used inside a variable pair, the results +may not be as expected:: + + $template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})'; + $data = array( + 'degree' => 'Mr', + 'firstname' => 'John', + 'lastname' => 'Doe', + 'degrees' => array( + array('degree' => 'BSc'), + array('degree' => 'PhD') + + ) + ); + $this->parser->parse_string($template, $data); + + Result: Hello, John Doe (Mr Mr ) + +View Fragments +============== + +You do not have to use variable pairs to get the effect of iteration in +your views. It is possible to use a view fragment for what would be inside +a variable pair, and to control the iteration in your controller instead +of in the view. + +An example with the iteration controlled in the view:: + + $template = '<ul>{menuitems} + <li><a href="{link}">{title}</a></li> + {/menuitems}</ul>'; + $data = array( + 'menuitems' => array( + array('title' => 'First Link', 'link' => '/first'), + array('title' => 'Second Link', 'link' => '/second'), + ) + ); + $this->parser->parse_string($template, $data); + + Result: + - First Link + - Second Link + +An example with the iteration controlled in the controller, +using a view fragment:: + + $temp = ''; + $template1 = '<li><a href="{link}">{title}</a></li>'; + $data1 = array( + array('title' => 'First Link', 'link' => '/first'), + array('title' => 'Second Link', 'link' => '/second'), + ); + foreach ($data1 as $menuitem) { + $temp .= $this->parser->parse_string($template1, $menuitem, TRUE); + } + + $template = '<ul>{menuitems}</ul>'; + $data = array( + 'menuitems' => $temp + ); + $this->parser->parse_string($template, $data); + + Result: + - First Link + - Second Link + *************** Class Reference *************** @@ -167,8 +290,8 @@ Class Reference :returns: Parsed template string :rtype: string - This method works exactly like ``parse()``, only it accepts the template as a - string instead of loading a view file. + This method works exactly like ``parse()``, only it accepts + the template as a string instead of loading a view file. .. method:: set_delimiters([$l = '{'[, $r = '}']]) @@ -176,4 +299,5 @@ Class Reference :param string $r: Right delimiter :rtype: void - Sets the delimiters (opening and closing) for a value "tag" in a template.
\ No newline at end of file + Sets the delimiters (opening and closing) for a + pseudo-variable "tag" in a template.
\ No newline at end of file |