diff options
Diffstat (limited to 'user_guide_src')
| -rw-r--r-- | user_guide_src/source/changelog.rst | 2 | ||||
| -rw-r--r-- | user_guide_src/source/contributing/index.rst | 4 | ||||
| -rw-r--r-- | user_guide_src/source/database/configuration.rst | 3 | ||||
| -rw-r--r-- | user_guide_src/source/database/forge.rst | 149 | ||||
| -rw-r--r-- | user_guide_src/source/database/helpers.rst | 61 | ||||
| -rw-r--r-- | user_guide_src/source/database/index.rst | 2 | ||||
| -rw-r--r-- | user_guide_src/source/database/queries.rst | 24 | ||||
| -rw-r--r-- | user_guide_src/source/database/query_builder.rst | 230 | ||||
| -rw-r--r-- | user_guide_src/source/database/results.rst | 43 | ||||
| -rw-r--r-- | user_guide_src/source/database/utilities.rst | 126 | ||||
| -rw-r--r-- | user_guide_src/source/documentation/index.rst | 18 | ||||
| -rw-r--r-- | user_guide_src/source/index.rst | 17 | ||||
| -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 |
16 files changed, 804 insertions, 313 deletions
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst index 00cdd58c5..08b692168 100644 --- a/user_guide_src/source/changelog.rst +++ b/user_guide_src/source/changelog.rst @@ -477,6 +477,7 @@ Release Date: Not Released - Changed default value of the ``$xss_clean`` parameter to NULL for all methods that utilize it, the default value is now determined by the ``$config['global_xss_filtering']`` setting. - Added method ``post_get()`` and changed ``get_post()`` to search in GET data first. Both methods' names now properly match their GET/POST data search priorities. - Changed method ``_fetch_from_array()`` to parse array notation in field name. + - Changed method ``_fetch_from_array()`` to allow retrieving multiple fields at once. - Added an option for ``_clean_input_keys()`` to return FALSE instead of terminating the whole script. - Deprecated the ``is_cli_request()`` method, it is now an alias for the new :func:`is_cli()` common function. - Added an ``$xss_clean`` parameter to method ``user_agent()`` and removed the ``$user_agent`` property. @@ -503,6 +504,7 @@ Release Date: Not Released - Added methods ``get_content_type()`` and ``get_header()``. - Added method ``delete_cache()``. - Changed caching behavior to compress the output before storing it, if ``$config['compress_output']`` is enabled. + - Changed caching to take the query string into account. - :doc:`Config Library <libraries/config>` changes include: diff --git a/user_guide_src/source/contributing/index.rst b/user_guide_src/source/contributing/index.rst index c784a59e5..3548dbca1 100644 --- a/user_guide_src/source/contributing/index.rst +++ b/user_guide_src/source/contributing/index.rst @@ -31,9 +31,9 @@ If you are having trouble using a feature of CodeIgniter, ask for help on the fo If you are wondering if you are using something correctly or if you have found a bug, ask on the forum first. -*************************** +**************************** Tips for a Good Issue Report -*************************** +**************************** Use a descriptive subject line (eg parser library chokes on commas) rather than a vague one (eg. your code broke). diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 34cefffbd..9f52ad2a2 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -141,7 +141,8 @@ Query Builder The :doc:`Query Builder Class <query_builder>` is globally enabled or disabled by setting the $query_builder variable in the database -configuration file to TRUE/FALSE (boolean). If you are not using the +configuration file to TRUE/FALSE (boolean). The default setting is TRUE. +If you are not using the query builder class, setting it to FALSE will utilize fewer resources when the database classes are initialized. diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst index 48642ad7e..371397d26 100644 --- a/user_guide_src/source/database/forge.rst +++ b/user_guide_src/source/database/forge.rst @@ -6,6 +6,7 @@ The Database Forge Class contains methods that help you manage your database. .. contents:: Table of Contents + :depth: 3 **************************** Initializing the Forge Class @@ -35,8 +36,11 @@ object:: $this->dbforge->some_method(); -$this->dbforge->create_database('db_name') -========================================== +******************************* +Creating and Dropping Databases +******************************* + +**$this->dbforge->create_database('db_name')** Permits you to create the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:: @@ -46,8 +50,7 @@ Returns TRUE/FALSE based on success or failure:: echo 'Database created!'; } -$this->dbforge->drop_database('db_name') -========================================== +**$this->dbforge->drop_database('db_name')** Permits you to drop the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:: @@ -57,6 +60,7 @@ Returns TRUE/FALSE based on success or failure:: echo 'Database deleted!'; } + **************************** Creating and Dropping Tables **************************** @@ -123,11 +127,11 @@ After the fields have been defined, they can be added using ``$this->dbforge->add_field($fields);`` followed by a call to the ``create_table()`` method. -$this->dbforge->add_field() ---------------------------- +**$this->dbforge->add_field()** The add fields method will accept the above array. + Passing strings as fields ------------------------- @@ -181,6 +185,7 @@ below is for MySQL. // gives KEY `blog_name_blog_label` (`blog_name`, `blog_label`) + Creating a table ================ @@ -211,6 +216,7 @@ You could also pass optional table attributes, such as MySQL's ``ENGINE``:: ``create_table()`` will always add them with your configured *char_set* and *dbcollat* values, as long as they are not empty (MySQL only). + Dropping a table ================ @@ -224,6 +230,7 @@ Execute a DROP TABLE statement and optionally add an IF EXISTS clause. // Produces: DROP TABLE IF EXISTS table_name $this->dbforge->drop_table('table_name'); + Renaming a table ================ @@ -235,12 +242,15 @@ Executes a TABLE rename // gives ALTER TABLE old_table_name RENAME TO new_table_name + **************** Modifying Tables **************** -$this->dbforge->add_column() -============================ +Adding a Column to a Table +========================== + +**$this->dbforge->add_column()** The ``add_column()`` method is used to modify an existing table. It accepts the same field array as above, and can be used for an unlimited @@ -269,8 +279,11 @@ Examples:: 'preferences' => array('type' => 'TEXT', 'first' => TRUE) ); -$this->dbforge->drop_column() -============================= + +Dropping a Column From a Table +============================== + +**$this->dbforge->drop_column()** Used to remove a column from a table. @@ -279,8 +292,11 @@ Used to remove a column from a table. $this->dbforge->drop_column('table_name', 'column_to_drop'); -$this->dbforge->modify_column() -=============================== + +Modifying a Column in a Table +============================= + +**$this->dbforge->modify_column()** The usage of this method is identical to ``add_column()``, except it alters an existing column rather than adding a new one. In order to @@ -295,4 +311,111 @@ change the name you can add a "name" key into the field defining array. ), ); $this->dbforge->modify_column('table_name', $fields); - // gives ALTER TABLE table_name CHANGE old_name new_name TEXT
\ No newline at end of file + // gives ALTER TABLE table_name CHANGE old_name new_name TEXT + + +*************** +Class Reference +*************** + +.. class:: DB_forge + + .. method:: __construct(&$db) + + :param object $db: Database object + :returns: DB_forge object for the specified database + :rtype: DB_forge + + Initializes a database forge. + + .. method:: add_column($table = '', $field = array(), $_after = NULL) + + :param string $table: Table name + :param array $field: Column definitions + :param string $_after: Column for AFTER clause (deprecated) + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Add a column to a table. Usage: See `Adding a Column to a Table`_. + + .. method:: add_field($field = '') + + :param array $field: Field to add + :returns: DB_forge instance + :rtype: object + + Add a field to the set that will be used to create a table. Usage: See `Adding fields`_. + + .. method:: add_key($key = '', $primary = FALSE) + + :param array $key: Name of a key field + :param boolean $primary: TRUE if this key is to be a primary key + :returns: DB_forge instance + :rtype: object + + Specify a key field to be used to create a table. Usage: See `Adding Keys`_. + + .. method:: create_database($db_name) + + :param string $db_name: Name of the database to create + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Create a new database. Usage: See `Creating and Dropping Databases`_. + + .. method:: create_table($table = '', $if_not_exists = FALSE, array $attributes = array()) + + :param string $table: Name of the table to create + :param string $if_not_exists: TRUE to add an 'IF NOT EXISTS' clause + :param string $attributes: Associative array of table attributes + :returns: DB_driver on success, FALSE on failure + :rtype: mixed + + Create a new table. Usage: See `Creating a table`_. + + .. method:: drop_column($table = '', $column_name = '') + + :param string $table: Table name + :param array $column_name: Column to drop + :returns: DB_driver on success, FALSE on failure + :rtype: mixed + + Drop a column from a table. Usage: See `Dropping a Column From a Table`_. + + .. method:: drop_database($db_name) + + :param string $db_name: Name of the database to drop + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Drop a database. Usage: See `Creating and Dropping Databases`_. + + .. method:: drop_table($table_name, $if_exists = FALSE) + + :param string $table: Name of the table to create + :param string $if_exists: TRUE to add an 'IF EXISTS' clause + :returns: DB_driver on success, FALSE on failure + :rtype: mixed + + Drop a table. Usage: See `Dropping a table`_. + + .. method:: modify_column($table = '', $field = array()) + + :param string $table: Table name + :param array $field: Column definitions + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Modify a column in a table. Usage: See `Modifying a Column in a Table`_. + + .. method:: rename_table($table_name, $new_table_name) + + :param string $table: Name of the table + :param string $new_table_name: New name of the table + :returns: DB_driver on success, FALSE on failure + :rtype: mixed + + Rename a table. Usage: See `Renaming a table`_. + + + diff --git a/user_guide_src/source/database/helpers.rst b/user_guide_src/source/database/helpers.rst index 77bf1b5d2..2d997a9e0 100644 --- a/user_guide_src/source/database/helpers.rst +++ b/user_guide_src/source/database/helpers.rst @@ -1,9 +1,11 @@ -###################### -Query Helper Functions -###################### +#################### +Query Helper Methods +#################### -$this->db->insert_id() -====================== +Information From Executing a Query +================================== + +**$this->db->insert_id()** The insert ID number when performing database inserts. @@ -11,8 +13,7 @@ The insert ID number when performing database inserts. driver, this function requires a $name parameter, which specifies the appropriate sequence to check for the insert id. -$this->db->affected_rows() -========================== +**$this->db->affected_rows()** Displays the number of affected rows, when doing "write" type queries (insert, update, etc.). @@ -22,8 +23,23 @@ Displays the number of affected rows, when doing "write" type queries affected rows. By default this hack is enabled but it can be turned off in the database driver file. -$this->db->count_all() -====================== +**$this->db->last_query()** + +Returns the last query that was run (the query string, not the result). +Example:: + + $str = $this->db->last_query(); + + // Produces: SELECT * FROM sometable.... + + +.. note:: Disabling the **save_queries** setting in your database + configuration will render this function useless. + +Information About Your Database +=============================== + +**$this->db->count_all()** Permits you to determine the number of rows in a particular table. Submit the table name in the first parameter. Example:: @@ -32,38 +48,24 @@ Submit the table name in the first parameter. Example:: // Produces an integer, like 25 -$this->db->platform() -===================== +**$this->db->platform()** Outputs the database platform you are running (MySQL, MS SQL, Postgres, etc...):: echo $this->db->platform(); -$this->db->version() -==================== +**$this->db->version()** Outputs the database version you are running:: echo $this->db->version(); -$this->db->last_query() -======================= - -Returns the last query that was run (the query string, not the result). -Example:: - - $str = $this->db->last_query(); - - // Produces: SELECT * FROM sometable.... - - -.. note:: Disabling the **save_queries** setting in your database - configuration will render this function useless. - -$this->db->insert_string() +Making Your Queries Easier ========================== +**$this->db->insert_string()** + This function simplifies the process of writing database inserts. It returns a correctly formatted SQL insert string. Example:: @@ -78,8 +80,7 @@ array with the data to be inserted. The above example produces:: .. note:: Values are automatically escaped, producing safer queries. -$this->db->update_string() -========================== +**$this->db->update_string()** This function simplifies the process of writing database updates. It returns a correctly formatted SQL update string. Example:: diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index 7ccb8fb00..cfd624238 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -1,5 +1,5 @@ ################## -The Database Class +Database Reference ################## CodeIgniter comes with a full-featured and very fast abstracted database diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst index 76ff1083f..43a0a30bf 100644 --- a/user_guide_src/source/database/queries.rst +++ b/user_guide_src/source/database/queries.rst @@ -2,10 +2,14 @@ Queries ####### -$this->db->query(); -=================== +************ +Query Basics +************ -To submit a query, use the following function:: +Regular Queries +=============== + +To submit a query, use the **query** function:: $this->db->query('YOUR QUERY HERE'); @@ -18,10 +22,11 @@ this:: $query = $this->db->query('YOUR QUERY HERE'); -$this->db->simple_query(); -========================== +Simplified Queries +================== -This is a simplified version of the $this->db->query() method. It DOES +The **simple_query** method is a simplified version of the +$this->db->query() method. It DOES NOT return a database result set, nor does it set the query timer, or compile bind data, or store your query for debugging. It simply lets you submit a query. Most users will rarely use this function. @@ -116,7 +121,9 @@ this: :: - $search = '20% raise'; $sql = "SELECT id FROM table WHERE column LIKE '%".$this->db->escape_like_str($search)."%'"; + $search = '20% raise'; + $sql = "SELECT id FROM table WHERE column LIKE '%" . + $this->db->escape_like_str($search)."%'"; ************** @@ -150,8 +157,7 @@ you. Handling Errors *************** -$this->db->error(); -=================== +**$this->db->error();** If you need to get the last error that has occured, the error() method will return an array containing its code and message. Here's a quick diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst index 5bfdfdb52..3203ff103 100644 --- a/user_guide_src/source/database/query_builder.rst +++ b/user_guide_src/source/database/query_builder.rst @@ -19,7 +19,9 @@ system. class in your database config file, allowing the core database library and adapter to utilize fewer resources. -.. contents:: Page Contents +.. contents:: + :local: + :depth: 1 ************** Selecting Data @@ -28,7 +30,7 @@ Selecting Data The following functions allow you to build SQL **SELECT** statements. $this->db->get() -================ +---------------- Runs the selection query and returns the result. Can be used by itself to retrieve all records from a table:: @@ -39,7 +41,8 @@ The second and third parameters enable you to set a limit and offset clause:: $query = $this->db->get('mytable', 10, 20); - // Produces: SELECT * FROM mytable LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) + // Produces: SELECT * FROM mytable LIMIT 20, 10 + // (in MySQL. Other databases have slightly different syntax) You'll notice that the above function is assigned to a variable named $query, which can be used to show the results:: @@ -54,10 +57,13 @@ $query, which can be used to show the results:: Please visit the :doc:`result functions <results>` page for a full discussion regarding result generation. +:returns: DB_Result for a successful "read", + TRUE for a successful "write", FALSE if an error + $this->db->get_compiled_select() -================================ +-------------------------------- -Compiles the selection query just like `$this->db->get()`_ but does not *run* +Compiles the selection query just like **$this->db->get()** but does not *run* the query. This method simply returns the SQL query as a string. Example:: @@ -79,14 +85,15 @@ will be reset (by default it will be reset, just like when using `$this->db->get // Produces string: SELECT title, content, date FROM mytable LIMIT 20, 10 The key thing to notice in the above example is that the second query did not -utilize `$this->db->from()`_ and did not pass a table name into the first +utilize **$this->db->from()** and did not pass a table name into the first parameter. The reason for this outcome is because the query has not been -executed using `$this->db->get()`_ which resets values or reset directly -using `$this->db->reset_query()`_. +executed using **$this->db->get()** which resets values or reset directly +using **$this->db->reset_query()**. +:returns: The SQL select string $this->db->get_where() -====================== +---------------------- Identical to the above function except that it permits you to add a "where" clause in the second parameter, instead of using the db->where() @@ -98,8 +105,11 @@ Please read the about the where function below for more information. .. note:: get_where() was formerly known as getwhere(), which has been removed +:returns: DB_Result for a successful "read", + TRUE for a successful "write", FALSE if an error + $this->db->select() -=================== +------------------- Permits you to write the SELECT portion of your query:: @@ -119,9 +129,10 @@ with backticks. This is useful if you need a compound select statement. $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); $query = $this->db->get('mytable'); +:returns: The query builder object $this->db->select_max() -======================= +----------------------- Writes a "SELECT MAX(field)" portion for your query. You can optionally include a second parameter to rename the resulting field. @@ -135,8 +146,7 @@ include a second parameter to rename the resulting field. $query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members -$this->db->select_min() -======================= +**$this->db->select_min()** Writes a "SELECT MIN(field)" portion for your query. As with select_max(), You can optionally include a second parameter to rename @@ -148,8 +158,7 @@ the resulting field. $query = $this->db->get('members'); // Produces: SELECT MIN(age) as age FROM members -$this->db->select_avg() -======================= +**$this->db->select_avg()** Writes a "SELECT AVG(field)" portion for your query. As with select_max(), You can optionally include a second parameter to rename @@ -161,8 +170,7 @@ the resulting field. $query = $this->db->get('members'); // Produces: SELECT AVG(age) as age FROM members -$this->db->select_sum() -======================= +**$this->db->select_sum()** Writes a "SELECT SUM(field)" portion for your query. As with select_max(), You can optionally include a second parameter to rename @@ -173,9 +181,11 @@ the resulting field. $this->db->select_sum('age'); $query = $this->db->get('members'); // Produces: SELECT SUM(age) as age FROM members +:returns: The query builder object + $this->db->from() -================= +----------------- Permits you to write the FROM portion of your query:: @@ -186,8 +196,10 @@ Permits you to write the FROM portion of your query:: .. note:: As shown earlier, the FROM portion of your query can be specified in the $this->db->get() function, so use whichever method you prefer. +:returns: The query builder object + $this->db->join() -================= +----------------- Permits you to write the JOIN portion of your query:: @@ -211,8 +223,14 @@ outer, and right outer. $this->db->join('comments', 'comments.id = blogs.id', 'left'); // Produces: LEFT JOIN comments ON comments.id = blogs.id +:returns: The query builder object + +************************* +Looking for Specific Data +************************* + $this->db->where() -================== +------------------ This function enables you to set **WHERE** clauses using one of four methods: @@ -277,9 +295,7 @@ with backticks. $this->db->where('MATCH (field) AGAINST ("value")', NULL, FALSE); - -$this->db->or_where() -===================== +**$this->db->or_where()** This function is identical to the one above, except that multiple instances are joined by OR:: @@ -290,8 +306,10 @@ instances are joined by OR:: .. note:: or_where() was formerly known as orwhere(), which has been removed. +:returns: The query builder object + $this->db->where_in() -===================== +--------------------- Generates a WHERE field IN ('item', 'item') SQL query joined with AND if appropriate @@ -303,8 +321,7 @@ appropriate // Produces: WHERE username IN ('Frank', 'Todd', 'James') -$this->db->or_where_in() -======================== +**$this->db->or_where_in()** Generates a WHERE field IN ('item', 'item') SQL query joined with OR if appropriate @@ -315,9 +332,10 @@ appropriate $this->db->or_where_in('username', $names); // Produces: OR username IN ('Frank', 'Todd', 'James') +:returns: The query builder object $this->db->where_not_in() -========================= +------------------------- Generates a WHERE field NOT IN ('item', 'item') SQL query joined with AND if appropriate @@ -329,8 +347,7 @@ AND if appropriate // Produces: WHERE username NOT IN ('Frank', 'Todd', 'James') -$this->db->or_where_not_in() -============================ +**$this->db->or_where_not_in()** Generates a WHERE field NOT IN ('item', 'item') SQL query joined with OR if appropriate @@ -341,9 +358,15 @@ if appropriate $this->db->or_where_not_in('username', $names); // Produces: OR username NOT IN ('Frank', 'Todd', 'James') +:returns: The query builder object + + +************************ +Looking for Similar Data +************************ $this->db->like() -================= +----------------- This method enables you to generate **LIKE** clauses, useful for doing searches. @@ -383,8 +406,7 @@ searches. // WHERE `title` LIKE '%match%' ESCAPE '!' AND `page1` LIKE '%match%' ESCAPE '!' AND `page2` LIKE '%match%' ESCAPE '!' -$this->db->or_like() -==================== +**$this->db->or_like()** This method is identical to the one above, except that multiple instances are joined by OR:: @@ -394,16 +416,14 @@ instances are joined by OR:: .. note:: ``or_like()`` was formerly known as ``orlike()``, which has been removed. -$this->db->not_like() -===================== +**$this->db->not_like()** This method is identical to ``like()``, except that it generates NOT LIKE statements:: $this->db->not_like('title', 'match'); // WHERE `title` NOT LIKE '%match% ESCAPE '!' -$this->db->or_not_like() -======================== +**$this->db->or_not_like()** This method is identical to ``not_like()``, except that multiple instances are joined by OR:: @@ -412,8 +432,10 @@ instances are joined by OR:: $this->db->or_not_like('body', 'match'); // WHERE `title` LIKE '%match% OR `body` NOT LIKE '%match%' ESCAPE '!' +:returns: The query builder object + $this->db->group_by() -===================== +--------------------- Permits you to write the GROUP BY portion of your query:: @@ -426,8 +448,10 @@ You can also pass an array of multiple values as well:: .. note:: group_by() was formerly known as groupby(), which has been removed. +:returns: The query builder object + $this->db->distinct() -===================== +--------------------- Adds the "DISTINCT" keyword to a query @@ -436,9 +460,10 @@ Adds the "DISTINCT" keyword to a query $this->db->distinct(); $this->db->get('table'); // Produces: SELECT DISTINCT * FROM table +:returns: The query builder object $this->db->having() -=================== +------------------- Permits you to write the HAVING portion of your query. There are 2 possible syntaxes, 1 argument or 2:: @@ -462,13 +487,18 @@ setting it to FALSE. $this->db->having('user_id', 45, FALSE); // Produces: HAVING user_id = 45 -$this->db->or_having() -====================== +**$this->db->or_having()** Identical to having(), only separates multiple clauses with "OR". +:returns: The query builder object + +**************** +Ordering results +**************** + $this->db->order_by() -===================== +--------------------- Lets you set an ORDER BY clause. @@ -512,8 +542,14 @@ be ignored, unless you specify a numeric seed value. .. note:: Random ordering is not currently supported in Oracle and will default to ASC instead. +:returns: The query builder object + +**************************** +Limiting or Counting Results +**************************** + $this->db->limit() -================== +------------------ Lets you limit the number of rows you would like returned by the query:: @@ -525,8 +561,10 @@ The second parameter lets you set a result offset. $this->db->limit(10, 20); // Produces: LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) +:returns: The query builder object + $this->db->count_all_results() -============================== +------------------------------ Permits you to determine the number of rows in a particular Active Record query. Queries will accept Query Builder restrictors such as @@ -537,14 +575,18 @@ where(), or_where(), like(), or_like(), etc. Example:: $this->db->from('my_table'); echo $this->db->count_all_results(); // Produces an integer, like 17 +:returns: Count of all the records returned by a query + $this->db->count_all() -====================== +---------------------- Permits you to determine the number of rows in a particular table. Submit the table name in the first parameter. Example:: echo $this->db->count_all('my_table'); // Produces an integer, like 25 +:returns: Count of all the records in the specified table + ************** Query grouping ************** @@ -568,37 +610,34 @@ you to create queries with complex WHERE clauses. Nested groups are supported. E .. note:: groups need to be balanced, make sure every group_start() is matched by a group_end(). -$this->db->group_start() -======================== +**$this->db->group_start()** Starts a new group by adding an opening parenthesis to the WHERE clause of the query. -$this->db->or_group_start() -=========================== +**$this->db->or_group_start()** Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR'. -$this->db->not_group_start() -============================ +**$this->db->not_group_start()** Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'NOT'. -$this->db->or_not_group_start() -=============================== +**$this->db->or_not_group_start()** Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR NOT'. -$this->db->group_end() -====================== +**$this->db->group_end()** Ends the current group by adding an closing parenthesis to the WHERE clause of the query. +:returns: The query builder object + ************** Inserting Data ************** $this->db->insert() -=================== +------------------- Generates an insert string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the @@ -635,8 +674,11 @@ object. .. note:: All values are escaped automatically producing safer queries. +:returns: DB_Query on success, FALSE on failure + $this->db->get_compiled_insert() -================================ +-------------------------------- + Compiles the insertion query just like `$this->db->insert()`_ but does not *run* the query. This method simply returns the SQL query as a string. @@ -672,8 +714,10 @@ using `$this->db->insert()` which resets values or reset directly using .. note:: This method doesn't work for batched inserts. +:returns: The SQL insert string + $this->db->insert_batch() -========================= +------------------------- Generates an insert string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the @@ -700,8 +744,14 @@ associative array of values. .. note:: All values are escaped automatically producing safer queries. +:returns: Count of the number of records inserted on success, FALSE on failure + +************* +Updating Data +************* + $this->db->replace() -==================== +-------------------- This method executes a REPLACE statement, which is basically the SQL standard for (optional) DELETE + INSERT, using *PRIMARY* and *UNIQUE* @@ -729,8 +779,10 @@ will be deleted with our new row data replacing it. Usage of the ``set()`` method is also allowed and all fields are automatically escaped, just like with ``insert()``. +:returns: DB_query object on success, FALSE on failure + $this->db->set() -================ +---------------- This function enables you to set values for inserts or updates. @@ -788,12 +840,10 @@ Or an object:: $this->db->set($object); $this->db->insert('mytable'); -************* -Updating Data -************* +:returns: The query builder object $this->db->update() -=================== +------------------- Generates an update string and runs the query based on the data you supply. You can pass an **array** or an **object** to the function. Here @@ -839,9 +889,10 @@ Or as an array:: You may also use the $this->db->set() function described above when performing updates. +:returns: DB_query object on success, FALSE on failure $this->db->update_batch() -========================= +------------------------- Generates an update string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the function. @@ -882,8 +933,10 @@ array of values, the third parameter is the where key. due to the very nature of how it works. Instead, ``update_batch()`` returns the number of rows affected. +:returns: Count of the number of records affected on success, FALSE on failure + $this->db->get_compiled_update() -================================ +-------------------------------- This works exactly the same way as ``$this->db->get_compiled_insert()`` except that it produces an UPDATE SQL string instead of an INSERT SQL string. @@ -892,12 +945,14 @@ For more information view documentation for `$this->db->get_compiled_insert()`. .. note:: This method doesn't work for batched updates. +:returns: The SQL update string + ************* Deleting Data ************* $this->db->delete() -=================== +------------------- Generates a delete SQL string and runs the query. @@ -930,17 +985,21 @@ delete data from more than 1 table. If you want to delete all data from a table, you can use the truncate() function, or empty_table(). +:returns: DB_Query on success, FALSE on failure + $this->db->empty_table() -======================== +------------------------ Generates a delete SQL string and runs the query.:: $this->db->empty_table('mytable'); // Produces: DELETE FROM mytable +:returns: DB_Query on success, FALSE on failure + $this->db->truncate() -===================== +--------------------- Generates a truncate SQL string and runs the query. @@ -959,13 +1018,20 @@ Generates a truncate SQL string and runs the query. .. note:: If the TRUNCATE command isn't available, truncate() will execute as "DELETE FROM table". +:returns: DB_Query on success, FALSE on failure + $this->db->get_compiled_delete() -================================ +-------------------------------- + This works exactly the same way as ``$this->db->get_compiled_insert()`` except that it produces a DELETE SQL string instead of an INSERT SQL string. For more information view documentation for `$this->db->get_compiled_insert()`_. +:returns: The SQL delete string + + + *************** Method Chaining *************** @@ -994,23 +1060,25 @@ Cached calls are cumulative. If you make 2 cached select() calls, and then 2 uncached select() calls, this will result in 4 select() calls. There are three Caching functions available: -$this->db->start_cache() -======================== +**$this->db->start_cache()** This function must be called to begin caching. All Query Builder queries of the correct type (see below for supported queries) are stored for later use. -$this->db->stop_cache() -======================= +**$this->db->stop_cache()** This function can be called to stop caching. -$this->db->flush_cache() -======================== +**$this->db->flush_cache()** This function deletes all items from the Query Builder cache. +:returns: void + +An example of caching +--------------------- + Here's a usage example:: $this->db->start_cache(); @@ -1033,8 +1101,12 @@ Here's a usage example:: where, like, group_by, having, order_by, set +*********************** +Resetting Query Builder +*********************** + $this->db->reset_query() -======================== +------------------------ Resetting Query Builder allows you to start fresh with your query without executing it first using a method like $this->db->get() or $this->db->insert(). @@ -1063,4 +1135,6 @@ run the query:: .. note:: Double calls to ``get_compiled_select()`` while you're using the Query Builder Caching functionality and NOT resetting your queries will results in the cache being merged twice. That in turn will - i.e. if you're caching a ``select()`` - select the same field twice.
\ No newline at end of file + i.e. if you're caching a ``select()`` - select the same field twice. + +:returns: void diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index e0a87a851..e06985130 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -4,10 +4,14 @@ Generating Query Results There are several ways to generate query results: +************* +Result Arrays +************* + result() ======== -This function returns the query result as an array of **objects**, or +This method returns the query result as an array of **objects**, or **an empty array** on failure. Typically you'll use this in a foreach loop, like this:: @@ -20,7 +24,7 @@ loop, like this:: echo $row->body; } -The above function is an alias of result_object(). +The above method is an alias of result_object(). If you run queries that might **not** produce a result, you are encouraged to test the result first:: @@ -53,7 +57,7 @@ instantiate for each result object (note: this class must be loaded) result_array() =============== -This function returns the query result as a pure array, or an empty +This method returns the query result as a pure array, or an empty array when no result is produced. Typically you'll use this in a foreach loop, like this:: @@ -66,10 +70,14 @@ loop, like this:: echo $row['body']; } +*********** +Result Rows +*********** + row() ===== -This function returns a single result row. If your query has more than +This method returns a single result row. If your query has more than one row, it returns only the first row. The result is returned as an **object**. Here's a usage example:: @@ -101,7 +109,7 @@ to instantiate the row with:: row_array() =========== -Identical to the above row() function, except it returns an array. +Identical to the above row() method, except it returns an array. Example:: $query = $this->db->query("YOUR QUERY"); @@ -136,7 +144,8 @@ parameter: | **$row = $query->next_row('array')** | **$row = $query->previous_row('array')** -.. note:: all the functions above will load the whole result into memory (prefetching) use unbuffered_row() for processing large result sets. +.. note:: all the methods above will load the whole result into memory + (prefetching) use unbuffered_row() for processing large result sets. unbuffered_row() ================ @@ -163,12 +172,11 @@ the returned value's type:: $query->unbuffered_row('object'); // object $query->unbuffered_row('array'); // associative array -*********************** -Result Helper Functions -*********************** +********************* +Result Helper Methods +********************* -$query->num_rows() -================== +**$query->num_rows()** The number of rows returned by the query. Note: In this example, $query is the variable that the query result object is assigned to:: @@ -181,20 +189,18 @@ is the variable that the query result object is assigned to:: Not all database drivers have a native way of getting the total number of rows for a result set. When this is the case, all of the data is prefetched and count() is manually called on the - resulting array in order to achieve the same functionality. + resulting array in order to achieve the same methodality. -$query->num_fields() -==================== +**$query->num_fields()** The number of FIELDS (columns) returned by the query. Make sure to call -the function using your query result object:: +the method using your query result object:: $query = $this->db->query('SELECT * FROM my_table'); echo $query->num_fields(); -$query->free_result() -===================== +**$query->free_result()** It frees the memory associated with the result and deletes the result resource ID. Normally PHP frees its memory automatically at the end of @@ -217,8 +223,7 @@ Example:: echo $row->name; $query2->free_result(); // The $query2 result object will no longer be available -data_seek() -=========== +**data_seek()** This method sets the internal pointer for the next result row to be fetched. It is only useful in combination with ``unbuffered_row()``. diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index bd40cdadd..d15cef06d 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -5,15 +5,14 @@ Database Utility Class The Database Utility Class contains methods that help you manage your database. -.. contents:: Table of Contents +.. contents:: + :local: + :depth: 2 -****************** -Function Reference -****************** - +****************************** Initializing the Utility Class -============================== +****************************** .. important:: In order to initialize the Utility class, your database driver must already be running, since the utilities class relies on it. @@ -39,7 +38,11 @@ object:: $this->dbutil->some_method() -$this->dbutil->list_databases(); +**************************** +Using the Database Utilities +**************************** + +Retrieve list of database names ================================ Returns an array of database names:: @@ -51,8 +54,9 @@ Returns an array of database names:: echo $db; } -$this->dbutil->database_exists(); -================================= + +Determine If a Database Exists +============================== Sometimes it's helpful to know whether a particular database exists. Returns a boolean TRUE/FALSE. Usage example:: @@ -65,8 +69,8 @@ Returns a boolean TRUE/FALSE. Usage example:: .. note:: Replace *database_name* with the name of the table you are looking for. This method is case sensitive. -$this->dbutil->optimize_table('table_name'); -============================================ +Optimize a Table +================ Permits you to optimize a table using the table name specified in the first parameter. Returns TRUE/FALSE based on success or failure:: @@ -79,8 +83,8 @@ first parameter. Returns TRUE/FALSE based on success or failure:: .. note:: Not all database platforms support table optimization. It is mostly for use with MySQL. -$this->dbutil->repair_table('table_name'); -========================================== +Repair a Table +============== Permits you to repair a table using the table name specified in the first parameter. Returns TRUE/FALSE based on success or failure:: @@ -92,8 +96,8 @@ first parameter. Returns TRUE/FALSE based on success or failure:: .. note:: Not all database platforms support table repairs. -$this->dbutil->optimize_database(); -==================================== +Optimize a Database +=================== Permits you to optimize the database your DB class is currently connected to. Returns an array containing the DB status messages or @@ -111,8 +115,8 @@ FALSE on failure. .. note:: Not all database platforms support table optimization. It it is mostly for use with MySQL. -$this->dbutil->csv_from_result($db_result); -=========================================== +Export a Query Result as a CSV File +=================================== Permits you to generate a CSV file from a query result. The first parameter of the method must contain the result object from your @@ -139,8 +143,8 @@ is used as the enclosure. Example:: simply creates the CSV layout. If you need to write the file use the :doc:`File Helper <../helpers/file_helper>`. -$this->dbutil->xml_from_result($db_result); -=========================================== +Export a Query Result as an XML Document +======================================== Permits you to generate an XML file from a query result. The first parameter expects a query result object, the second may contain an @@ -163,8 +167,12 @@ optional array of config parameters. Example:: simply creates the XML layout. If you need to write the file use the :doc:`File Helper <../helpers/file_helper>`. -$this->dbutil->backup(); -======================== +******************** +Backup Your Database +******************** + +Database Backup Notes +===================== Permits you to backup your full database or individual tables. The backup data can be compressed in either Zip or Gzip format. @@ -182,7 +190,7 @@ backup data can be compressed in either Zip or Gzip format. have root privileges. Usage Example -------------- +============= :: @@ -201,7 +209,7 @@ Usage Example force_download('mybackup.gz', $backup); Setting Backup Preferences --------------------------- +========================== Backup preferences are set by submitting an array of values to the first parameter of the ``backup()`` method. Example:: @@ -219,7 +227,7 @@ parameter of the ``backup()`` method. Example:: $this->dbutil->backup($prefs); Description of Backup Preferences ---------------------------------- +================================= ======================= ======================= ======================= ======================================================================== Preference Default Value Options Description @@ -234,4 +242,72 @@ Preference Default Value Options Descript **add_insert** TRUE TRUE/FALSE Whether to include INSERT statements in your SQL export file. **newline** "\\n" "\\n", "\\r", "\\r\\n" Type of newline to use in your SQL export file. **foreign_key_checks** TRUE TRUE/FALSE Whether output should keep foreign key checks enabled. -======================= ======================= ======================= ========================================================================
\ No newline at end of file +======================= ======================= ======================= ======================================================================== + +*************** +Class Reference +*************** + +.. class:: DB_utility + + .. method:: backup($params) + + :param array $params: associative array of backup preferences + :returns: void + :rtype: void + + Perform a database backup, per user preferences + + .. method:: csv_from_results($query, $delim = ',', $newline = "\n", $enclosure = '"') + + :param object $query: DB_result with data to backup + :param string $delim: Delimniter character for the CSV file, default is ',' + :param string $newline: Character to use for newlines, default is "\n" + :param string $enclosure: Delimiter used for enclosure, default is '"' + :returns: The generated CSV file as a string + :rtype: string + + .. method:: database_exists($database_name) + + :param string $database_name: name of the database to check for + :returns: TRUE if the database exists, FALSE otherwise + :rtype: boolean + + Check for the existence of a database + + .. method:: list_databases() + + :returns: Array of database names found + :rtype: array + + Retrieve all the database names + + .. method:: optimize_database() + + :returns: Array of optimization messages, FALSE on failure + :rtype: array + + Optimizes a database + + .. method:: optimize_table($table_name) + + :param string $table_name: Name of the table to optimize + :returns: Array of optimization messages, FALSE on failure + :rtype: array + + Optimizes a database table + + .. method:: repair_table($table_name) + + :param string $table_name: Name of the table to repair + :returns: Array of repair messages, FALSE on failure + :rtype: array + + Repairs a database table + + .. method:: xml_from_results($query, $params) + + :param object $query: DB_result with data to backup + :param array $params: Associative array of preferences + :returns: The generated XML document as a string + :rtype: string diff --git a/user_guide_src/source/documentation/index.rst b/user_guide_src/source/documentation/index.rst index 38124f7f2..6d4c94bc1 100644 --- a/user_guide_src/source/documentation/index.rst +++ b/user_guide_src/source/documentation/index.rst @@ -5,11 +5,11 @@ Writing CodeIgniter Documentation CodeIgniter uses Sphinx to generate its documentation in a variety of formats, using reStructuredText to handle the formatting. If you are familiar with Markdown or Textile, you will quickly grasp reStructuredText. The focus is -on readability, user friendliness, and an "I've got your hand, baby" feel. +on readability and user friendliness. While they can be quite technical, we always write for humans! -A local table of contents should always be included like the one below. -It is created automatically by inserting the the following: +A local table of contents should always be included, like the one below. +It is created automatically by inserting the following: :: @@ -110,8 +110,8 @@ Method Documentation ******************** When documenting class methods for third party developers, Sphinx provides -directives to assist and keep things simple. For example, consider the following -ReST: +directives to assist and keep things simple. +For example, consider the following ReST: .. code-block:: rst @@ -124,7 +124,7 @@ ReST: parameter. :param int $foo: the foo id to do something in - :param mixed $bar: A data array that must contain aa something and something else + :param mixed $bar: A data array that must contain a something and something else :param bool $bat: whether or not to do something :returns: FALSE on failure, TRUE if successful :rtype: bool @@ -153,7 +153,7 @@ ReST: .. method:: should_do_something() - :returns: Whether or something should be done or not + :returns: Whether or not something should be done :rtype: bool @@ -169,7 +169,7 @@ It creates the following display: parameter. :param int $foo: the foo id to do something in - :param mixed $bar: A data array that must contain aa something and something else + :param mixed $bar: A data array that must contain a something and something else :param bool $bat: whether or not to do something :returns: FALSE on failure, TRUE if successful :rtype: bool @@ -198,5 +198,5 @@ It creates the following display: .. method:: should_do_something() - :returns: Whether or something should be done or not + :returns: Whether or not something should be done :rtype: bool
\ No newline at end of file diff --git a/user_guide_src/source/index.rst b/user_guide_src/source/index.rst index 09bf770fc..d8f60e360 100644 --- a/user_guide_src/source/index.rst +++ b/user_guide_src/source/index.rst @@ -72,14 +72,15 @@ Library Reference libraries/index -**************** -Driver Reference -**************** +****************** +Database Reference +****************** -- :doc:`libraries/caching` -- :doc:`database/index` -- :doc:`libraries/javascript` -- :doc:`libraries/sessions` +.. toctree:: + :glob: + :titlesonly: + + database/index **************** Helper Reference @@ -100,6 +101,7 @@ Contributing to CodeIgniter :titlesonly: contributing/index + documentation/index DCO .. toctree:: @@ -116,6 +118,5 @@ Contributing to CodeIgniter libraries/index helpers/index database/index - documentation/index tutorial/index general/credits 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 |