Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
wiki:first_grid [2010/04/07 02:32]
preichow
wiki:first_grid [2017/12/12 17:10]
admin
Line 3: Line 3:
 For this tutorial, and as an example to refer to throughout this documentation,​ we’re going to create a grid with invoice information. For this tutorial, and as an example to refer to throughout this documentation,​ we’re going to create a grid with invoice information.
  
-You need the following three things in order to use jqGrid: ​+You need the following three things in order to use jqGrid : 
   - A database with some sample data,      - A database with some sample data,   
   - A HTML page to show the data, and      - A HTML page to show the data, and   
Line 34: Line 34:
 ); );
 </​code>​ </​code>​
 +
 +<note tip>If you're using a MySQL administration program, many times there is an area to type in and execute SQL commands. ​ If that's the case, simply copy and paste the code above, then hit the execute button to create the database. ​ Alternatively,​ you can manually create the database and set up the columns one at a time.</​note>​
  
 Then, put some values into it. Then, put some values into it.
 +
 +(Here'​s a spreadsheet with 644 sample records. ​ Feel free to use this or create your own data.  Note that column "​A"​ is blank because it should be an auto-increment field in your database)
 +{{:​wiki:​dataupload.xls|}}
  
 ===== HTML File ===== ===== HTML File =====
  
-Using the file myfirstgrid.html as described in [[wiki:​how_to_install | installation]] ​ we will have:+The HTML page fulfills three purposes: It loads all the files required for jqGrid to work, it contains the grid placement, and it contains the grid configuration instructions. 
 + 
 +Using the file myfirstgrid.html as described in the [[wiki:​how_to_install | installation]] ​section, ​we have the following code:
  
 <code html> <code html>
Line 46: Line 53:
 <​head>​ <​head>​
 <meta http-equiv="​Content-Type"​ content="​text/​html;​ charset=utf-8"​ /> <meta http-equiv="​Content-Type"​ content="​text/​html;​ charset=utf-8"​ />
 +<meta http-equiv="​X-UA-Compatible"​ content="​IE=edge"​ />
 <​title>​My First Grid</​title>​ <​title>​My First Grid</​title>​
   ​   ​
-<link rel="​stylesheet"​ type="​text/​css"​ media="​screen"​ href="​css/​ui-lightness/​jquery-ui-1.7.1.custom.css"​ />+<link rel="​stylesheet"​ type="​text/​css"​ media="​screen"​ href="​css/​ui-lightness/​jquery-ui-1.8.2.custom.css"​ />
 <link rel="​stylesheet"​ type="​text/​css"​ media="​screen"​ href="​css/​ui.jqgrid.css"​ /> <link rel="​stylesheet"​ type="​text/​css"​ media="​screen"​ href="​css/​ui.jqgrid.css"​ />
  
-<​style>​+<​style ​type="​text/​css"​>
 html, body { html, body {
     margin: 0;     margin: 0;
Line 59: Line 67:
 </​style>​ </​style>​
  
-<script src="​js/​jquery-1.3.2.min.js"​ type="​text/​javascript"></​script>​+<script src="​js/​jquery-1.7.2.min.js"​ type="​text/​javascript"></​script>​
 <script src="​js/​i18n/​grid.locale-en.js"​ type="​text/​javascript"></​script>​ <script src="​js/​i18n/​grid.locale-en.js"​ type="​text/​javascript"></​script>​
 <script src="​js/​jquery.jqGrid.min.js"​ type="​text/​javascript"></​script>​ <script src="​js/​jquery.jqGrid.min.js"​ type="​text/​javascript"></​script>​
  
 <script type="​text/​javascript">​ <script type="​text/​javascript">​
-jQuery(document).ready(function(){  +$(function () { 
-  ​jQuery("#​list"​).jqGrid({ +    $("#​list"​).jqGrid({ 
-    url:'example.php'+        url: "example.php"
-    datatype: ​'xml'+        datatype: ​"xml"
-    mtype: ​'GET'+        mtype: ​"GET"
-    colNames:['Inv No','Date''Amount','Tax','Total','Notes'], +        colNames: ["Inv No""Date""Amount""Tax""Total""Notes"], 
-    colModel :[  +        colModel: [ 
-      {name:'invid', index:'​invid'​, width:55},  +            { name: "invid", width: 55 }, 
-      {name:'invdate', index:'​invdate'​, width:90},  +            { name: "invdate", width: 90 }, 
-      {name:'amount', index:'​amount'​, width:80, align:'right'},  +            { name: "amount", width: 80, align: ​"right" ​}, 
-      {name:'tax', index:'​tax'​, width:80, align:'right'},  +            { name: "tax", width: 80, align: ​"right" ​}, 
-      {name:'total', index:'​total'​, width:80, align:'right'},  +            { name: "total", width: 80, align: ​"right" ​}, 
-      {name:'note', index:'​note'​, width:150, sortable:​false}  +            { name: "note", width: 150, sortable: false } 
-    ], +        ], 
-    pager: ​'#pager'+        pager: ​"#pager"
-    rowNum:​10,​ +        rowNum: 10, 
-    rowList:​[10,​20,​30],​ +        rowList: [10, 20, 30], 
-    sortname: ​'invid'+        sortname: ​"invid"
-    sortorder: ​'desc'+        sortorder: ​"desc"
-    viewrecords:​ true, +        viewrecords:​ true, 
-    caption: ​'My first grid' +        ​gridview:​ true, 
-  }); +        autoencode: true, 
 +        ​caption: ​"My first grid" 
 +    }); 
 });  }); 
 </​script>​ </​script>​
Line 91: Line 101:
 </​head>​ </​head>​
 <​body>​ <​body>​
-<table id="​list"></​table>​  +    ​<table id="​list"​><​tr><​td></​td></​tr></​table>​  
-<div id="​pager"></​div> ​+    <div id="​pager"></​div> ​
 </​body>​ </​body>​
 </​html>​ </​html>​
 </​code>​ </​code>​
  
-Between ​the <​body>​ tags you define where you want to place the grid+==== Explanation of Code  ==== 
 + 
 +We use the jQuery $ function to run our script at the appropriate time. For more information on this, refer to the jQuery documentation. 
 + 
 +Required Files: An explanation of the .js and .css files required for jqGrid is provided in the Installation section. 
 + 
 +Grid Placement: The grid can be placed anywhere between ​the <​body>​ tags in the document The definition of the grid is done via the HTML tag <​table>,​ as shown here:
  
 <code html> <code html>
 <​body> ​ <​body> ​
  
-<table id="​list"></​table> ​+<table id="​list"​><​tr><​td></​td></​tr></​table> ​
 <div id="​pager"></​div> ​ <div id="​pager"></​div> ​
  
Line 108: Line 124:
 </​code>​ </​code>​
  
-The definition of the grid is done via the html tag <table>. To make our life easy it is good idea to give the table an id that is unique in this html document. ​ +<note important>The table should have an ID that is unique in the HTML document. ​ In the example aboveit is "#​list"​. ​ This ID is important because you'll need it for grid functions. The elements <​tr><​td></​td></​tr>​ inside of the <​table>​ element ​are needed only to make the document the valid XHTML 1.0 Strict document. The elements will be removed ​by jqGrid ​during ​the jqGrid initialization</​note> ​
-Cellspacingcellpadding and border attributes ​are added by jqGrid ​and shoudl not be included in the definition of your table.+
  
-We want to use paging mechanism too, so we define the navigation layerThis can be done with the commonly-used <div> tag.<​del>​ Giving the class "​scroll"​ of the navigator specifies that we want to use the CSS provided with jqGrid. It is important to note that the navigation layer can be placed arbitrarily any place in the html document. Normally, and in this case, it is under the grid.</​del>​+In many examples throughout this documentation,​ you'll see hash (#) sign before ID names ​jqGrid works with or without ​the hash sign, but it's considered good practice ​to use the hash.
  
-In the current implementation the pager is placed above the grid in all situations instead that they can be somewhere ​in the html document.+Cellspacing,​ cellpadding and border attributes are added by jqGrid and should not be included ​in the definition of your table 
  
-We use the jQuery document.ready function ​to run our script at the appropriate timeFor more information on this, refer to the jQuery documentation.+For many grids, you'll want to have the ability to navigate and page up and down through your data   ​Within jqGrid, ​this is known as the Navigation layer. This feature is enabled by adding the commonly-used <div> tag<​del>​identified by the "#​pager"​ ID in the example above. ​ It's also important ​to use a unique ID for the navigation layer as well.
  
-The syntax for constructing ​the grid is:+The Navigation layer can also be placed anywhere within ​the HTML document. Normally, and in this case, it is under the <​table>​ tags.
  
-<code javascript>​ +The settings and options used in the code are described here A full list of all possible settings and options ​can be found in [[:​wiki:​options | API Methods]] and [[:​wiki:​colmodel_options | colModel API]].
-jQuery('#​grid_selector'​).jqGrid( ​options ​+
-</​code>​+
  
-where: 
-grid_selector is the unique id of the grid table (list using our example above) ​ 
-jqGrid is the plugin, and 
-options is an array, in our example several lines, of the information needed to construct the grid.  
-Let’s begin with the options array, which looks like this: (These options can appear in any order) 
-<code javascript>​ 
-{ 
-  url:'​example.php',​ 
-  datatype: '​xml',​ 
-  mtype: '​GET',​ 
-  colNames:​['​Inv No','​Date',​ '​Amount','​Tax','​Total','​Notes'​],​ 
-  colModel :[  
-    {name:'​invid',​ index:'​invid',​ width:​55}, ​ 
-    {name:'​invdate',​ index:'​invdate',​ width:​90}, ​ 
-    {name:'​amount',​ index:'​amount',​ width:80, align:'​right'​}, ​ 
-    {name:'​tax',​ index:'​tax',​ width:80, align:'​right'​}, ​ 
-    {name:'​total',​ index:'​total',​ width:​80,​align:'​right'​}, ​ 
-    {name:'​note',​ index:'​note',​ width:150, sortable:​false} ], 
-  pager: jQuery('#​pager'​),​ 
-  rowNum:10, 
-  rowList:​[10,​20,​30],​ 
-  sortname: '​invid',​ 
-  sortorder: '​desc',​ 
-  viewrecords:​ true, 
-  caption: 'My first grid' 
-} 
-</​code>​ 
  
-The settings and options used above are described here; listings ​of all settings and options ​can be found in [[:wiki:options | API Methods]] and [[:wiki:colmodel_options ​colModel API]].+^Property ^Description ^ 
 +| url | Tells us where to get the data. Typically this is a server-side function with a connection to a database which returns the appropriate information to be filled into the Body layer in the grid | 
 +| datatype | This tells jqGrid the type of information being returned so it can construct the grid. In this case, we tell the grid that we expect XML data to be returned from the server, but other formats are possible. For a list of all available datatypes refer to API Methods | 
 +| mtype | Tells us how to make the Ajax call: either '​GET'​ or '​POST'​. In this case, we will use the GET method to retrieve data from the server | 
 +| colNames |An array in which we place the names of the columns. This is the text that appears in the head of the grid (Header layer). ​The names are separated with commas | 
 +| colModel |An array that describes the model of the columns. This is the most important part of the grid. Here I explain only the options used above. For the complete list of options ​see colModel API \\ **name**: The name of the column. This name does not have to be the name from the database table, but later we will see how we can use this when we have different data formats. \\ **index**The name passed to the server on which to sort the data (note that we could pass column numbers instead). Typically this is the name (or names) from the database -- this is server-side sorting, so what you pass depends on what your server expects to receive. ​ \\ **width**The width of the column, in pixels. \\ **align**The alignment of the column. \\ **sortable**Specifies if the data in the grid can be sorted on this column; if false, clicking on the header has no effect.| 
 +|pager|Defines that we want to use a pager bar to navigate through the recordsThis must be a valid HTML element; in our example we gave the div the id of "​pager",​ but any name is acceptable. Note that the Navigation layer (the "​pager"​ div) can be positioned anywhere you want, determined by your HTML; in our example we specified that the pager will appear after the Body layer.| 
 +|rowNum|Sets how many records we want to view in the grid. This parameter is passed to the URL for use by the server routine retrieving the data| 
 +| rowList|An array to construct a select box element in the pager in which we can change the number of the visible rows. When changed during the execution, this parameter replaces the rowNum parameter that is passed to the url| 
 +|sortname|Sets the initial sorting column. Can be a name or number. This parameter is added to the URL for use by the server routine| 
 +|viewrecords|Defines whether we want to display the number of total records from the query in the pager bar| 
 +|caption|Sets the caption for the grid. If this parameter is not set the Caption layer will be not visible|
  
 +Having done this, we have now done half the work. The next step is to construct the server-side manipulation -- which is done in the file pointed to by the "​url"​ parameter in the grid.
  
-^Property ^Description ^ +===== Behind ​the ScenesGrid Data  =====
-| url | tells us where to get the data. Typically this is a server-side function with a connection to a database which returns the appropriate information to be filled into the Body layer in the grid | +
-| datatype | this tells jqGrid the type of information being returned so it can construct the grid. In this case we tell the grid that we expect xml data to be returned from the server, but other formats are possible. For a list of all available datatypes refer to API Methods | +
-| mtype | tells us how to make the ajax calleither '​GET'​ or '​POST'​. In this case we will use the GET method to retrieve data from the server | +
-| colNames |an array in which we place the names of the columns. This is the text that appears in the head of the grid (Header layer). The names are separated with commas | +
-| colModel |an array that describes the model of the columns. This is the most important part of the grid. Here I explain only the options used above. ​ an array that describes the model of the columns. This is the most important part of the grid. Here I explain only the options used above. For the complete list of options see colModel API \\ **name** the name of the column. This name does not have to be the name from database table, but later we will see how we can use this when we have different data formats \\ **index** the name passed to the server on which to sort the data (note that we could pass column numbers instead). Typically this is the name (or names) from database -- this is server-side sorting, so what you pass depends on what your server expects to receive ​ \\ **width** the width of the column, in pixels \\ **align** the alignment of the column \\ **sortable** pecifies if the data in the grid can be sorted on this column; if false, clicking on the header has no effect| +
-|pager|defines that we want to use a pager bar to navigate through the records. This must be a valid html element; in our example we gave the div the id of "​pager",​ but any name is acceptable. Note that the Navigation layer (the "​pager"​ div) can be positioned anywhere you want, determined by your html; in our example we specified that the pager will appear after the Body layer.| +
-|rowNum|sets how many records we want to view in the grid. This parameter is passed to the url for use by the server routine retrieving the data| +
-| rowList|an array to construct a select box element in the pager in which we can change the number of the visible rows. When changed during the execution, this parameter replaces the rowNum parameter that is passed to the url| +
-|sortname|sets the initial sorting column. Can be a name or number. This parameter is added to the url for use by the server routine| +
-|viewrecords|defines whether we want to display the number of total records from the query in the pager bar| +
-|caption|sets the caption for the grid. If this parameter is not set the Caption layer will be not visible|+
  
-Having done thiswe have now done half the work. The next step is to construct the server-side manipulation -- in the file pointed ​to in the url parameter in the grid.+When using jqGridit will run a file (identified by the URL setting explained above) that will request data from the server (unless you're using static data) The server ​will return ​the data to jqGrid ​in a format it understands.
  
-===== The Server-side File =====+JqGrid can construct a grid using data from a number of formats, but the default is XML data with the structure in the example below. ​ Later in the documentation,​ we'll see how to use XML data in other structures and data in other formats.
  
-jqGrid can construct a grid from data in any of several formats, but the default is xml data with the following structure. Later we'll see how to use xml data in other structures ​and data in other formats.+This data interchange happens behind ​the scenes; and the user only sees the completed grid, and not the raw data itself.
  
-Default ​xml Data Structure+Default ​XML Data Structure:
  
 <code xml> <code xml>
Line 213: Line 200:
 <​note>​If you are using a content-free primary key to identify your data rows, then do not include this value in the grid as a visible cell; instead, include it in the query and pass it as the row id attribute. It will always be available for jqGrid and even jQuery operations but not be visible on the page. <​note>​If you are using a content-free primary key to identify your data rows, then do not include this value in the grid as a visible cell; instead, include it in the query and pass it as the row id attribute. It will always be available for jqGrid and even jQuery operations but not be visible on the page.
 </​note>​ </​note>​
-Now it is time to construct ​our file. + 
 +Now it'​s ​time to construct ​the server side file that will facilitate the requests for data from jqGrid.
  
 ===== PHP and MySQL example file ===== ===== PHP and MySQL example file =====
 +
 +The PHP file below is called when jqGrid requests data from the server. ​ The file queries the MySQL database and returns the data to jqGrid in the XML format explained above.
 +
 +Note that this file is set up to only read data from the server. ​ If you want to write data to the server, that requires a separate file that would be called by the "​EditURL"​ property, as explained on the Options page.
 +
 +
 +
 +
 <code php> <code php>
 <?​php ​ <?​php ​
Line 289: Line 285:
 // be sure to put text data in CDATA // be sure to put text data in CDATA
 while($row = mysql_fetch_array($result,​MYSQL_ASSOC)) { while($row = mysql_fetch_array($result,​MYSQL_ASSOC)) {
-    $s .= "<​row id='"​. $row[invid]."'>"; ​            +    $s .= "<​row id='"​. $row['invid']."'>"; ​            
-    $s .= "<​cell>"​. $row[invid]."</​cell>";​ +    $s .= "<​cell>"​. $row['invid']."</​cell>";​ 
-    $s .= "<​cell>"​. $row[invdate]."</​cell>";​ +    $s .= "<​cell>"​. $row['invdate']."</​cell>";​ 
-    $s .= "<​cell>"​. $row[amount]."</​cell>";​ +    $s .= "<​cell>"​. $row['amount']."</​cell>";​ 
-    $s .= "<​cell>"​. $row[tax]."</​cell>";​ +    $s .= "<​cell>"​. $row['tax']."</​cell>";​ 
-    $s .= "<​cell>"​. $row[total]."</​cell>";​ +    $s .= "<​cell>"​. $row['total']."</​cell>";​ 
-    $s .= "<​cell><​![CDATA["​. $row[note]."​]]></​cell>";​+    $s .= "<​cell><​![CDATA["​. $row['note']."​]]></​cell>";​
     $s .= "</​row>";​     $s .= "</​row>";​
 } }
Line 304: Line 300:
 </​code>​ </​code>​
  
-That is all. Save the file with name example.php and place it in myproject directory ​and your first grid is done. +Save this file with name example.php and place it in myproject directory.  You're now ready to create ​your first grid!
  
  

QR Code
QR Code wiki:first_grid (generated for current page)