<?xml version="1.0" encoding="utf-8"?>
<KScriptSetting>
  <Name>Table</Name>
  <Description>The kScript database table object</Description>
  <Example><![CDATA[
    <script engine="kscript">
    var table = k.database.getTable("tablename");
    var obj = {fieldone: "value one", fieldtwo: "value two"};
    table.add(obj);  
    </script>
    ]]></Example>
  <Props />
  <Methods>
    <Method>
      <Name>add</Name>
      <Description>Add an object into database table. If the table does not have the field, the table schema will be automatically updated with that column. </Description>
      <Example><![CDATA[
        <script engine="kscript">
        var table = k.database.getTable("tablename");
        var obj = {fieldone: "value one", fieldtwo: "value two"};
        var returnid = table.add(obj);
        </script>
		]]></Example>
      <Params>
        <Param>
          <Name>value</Name>
          <Description>value</Description>
          <Type>object</Type>
        </Param>
      </Params>
      <ReturnType>object</ReturnType>
    </Method>
    <Method>
      <Name>append</Name>
      <Description>Append an object to database table. This is the same as "add" except that it will not update table schema when the object contains fields not defined in the table schema.</Description>
      <Example>
        var table = k.database.getTable("tablename");
        var obj = {fieldone: "value one", fieldtwo: "value two"};
        var returnid = table.append(obj);
      </Example>
      <Params>
        <Param>
          <Name>value</Name>
          <Description>value</Description>
          <Type>object</Type>
        </Param>
      </Params>
      <ReturnType>object</ReturnType>
    </Method>
    <Method>
      <Name>delete</Name>
      <Description>Delete an item from database based on id or primary key</Description>
      <Example>

        var table = k.database.getTable("tablename");
		var key = "key";
        table.delete(key);

      </Example>
      <Params>
        <Param>
          <Name>id</Name>
          <Description>id</Description>
          <Type>object</Type>
        </Param>
      </Params>
    </Method>
    <Method>
      <Name>find</Name>
      <Description>find the first item that field equal the match value</Description>
      <Example><![CDATA[
        <script engine="kscript">
        var table = k.database.getTable("tablename");

        // find equal value match.
        var item = table.find("fieldname", "matchvalue");

        // this is identifical as below query.
        var item = table.find("name=='matchedvalue'");

        /// syntax of condition: fieldname operator value;
        // all available operators: ==,  >=,  >,  <,  <=, contains, startwith
        </script>
		]]></Example>
      <Params>
        <Param>
          <Name>field</Name>
          <Description>field</Description>
          <Type>string</Type>
        </Param>
        <Param>
          <Name>value</Name>
          <Description>value</Description>
          <Type>object</Type>
        </Param>
      </Params>
      <ReturnType>object</ReturnType>
    </Method>
    <Method>
      <Name>findAll</Name>
      <Description>Return the all items that matches the condition</Description>
      <Example><![CDATA[
        <script engine="kscript">
        var table = k.database.getTable("tablename");

        // findAll equal value match.
        var item = table.findAll("fieldname", "matchvalue");

        // this is identifical as below query.
        var item = table.findAll("name=='matchedvalue'");

        /// syntax of condition: fieldname operator value;
        // all available operators: ==,  >=,  >,  <,  <=, contains, startwith
        </script>
		]]></Example>
      <Params>
        <Param>
          <Name>field</Name>
          <Description>field</Description>
          <Type>string</Type>
        </Param>
        <Param>
          <Name>value</Name>
          <Description>value</Description>
          <Type>object</Type>
        </Param>
      </Params>
      <ReturnType>array</ReturnType>
    </Method>
    <Method>
      <Name>findAll</Name>
      <Description>Return the all items that matches the condition</Description>
      <Example><![CDATA[
        <script engine="kscript">

        var table = k.database.getTable("tablename");

        // findAll  condition text can be one of the followings.
        // find item with field "name" value of "matchedvalue".
        var item = table.findAll("name=='matchedvalue'");

        // find item with field "number" bigger than or equal to 123.
        var item = table.findAll("number>=123");

        // find item with field "name" value contains "matchedvalue".
        var item = table.findAll("name contains 'matchedvalue'");

        // find item with field "name" value startwith "matchedvalue".
        var item = table.findAll("name startwith 'matchedvalue'");

        /// syntax of condition: fieldname operator value;
        // all available operators: ==,  >=,  >,  <,  <=, contains, startwith

        </script>
		]]></Example>
      <Params>
        <Param>
          <Name>condition</Name>
          <Description>condition</Description>
          <Type>Query</Type>
        </Param>
      </Params>
      <ReturnType>array</ReturnType>
    </Method>
    <Method>
      <Name>get</Name>
      <Description>get an item based on Id or primary key</Description>
      <Example>
        var table = k.database.getTable("tablename");
		var IdOrKey = "IdOrKey";
        var item = table.get(IdOrKey);
      </Example>
      <Params>
        <Param>
          <Name>id</Name>
          <Description>id</Description>
          <Type>object</Type>
        </Param>
      </Params>
      <ReturnType>object</ReturnType>
    </Method>
    <Method>
      <Name>update</Name>
      <Description>update an item, key must be the system default Guid key or the key value of primary key field. you can set one field as the primary key.</Description>
      <Example><![CDATA[
        <script engine="kscript">
        var table = k.database.getTable("tablename");
        var obj = {fieldone: "value one", fieldtwo: "value two"};
        var returnid = table.add(obj);
        obj.fieldone = "new name";
        table.update(returnid, obj);
        </script>
		]]></Example>
      <Params>
        <Param>
          <Name>id</Name>
          <Description>id</Description>
          <Type>object</Type>
        </Param>
        <Param>
          <Name>newvalue</Name>
          <Description>newvalue</Description>
          <Type>object</Type>
        </Param>
      </Params>
    </Method>
    <Method>
      <Name>createIndex</Name>
      <Description>Create an additional index.</Description>
      <Example><![CDATA[
        <script engine="kscript">
        
        var table = k.database.getTable("tablename");
        var obj = {fieldone: "value one", fieldtwo: "value two"};
        table.add(obj); 
        table.createIndex("name"); 
        
        </script>
		]]></Example>
      <Params>
        <Param>
          <Name>fieldname</Name>
          <Description>fieldname</Description>
          <Type>string</Type>
        </Param>
      </Params>
    </Method>
    <Method>
      <Name>all</Name>
      <Description>all</Description>
      <Example>all</Example>
      <Params />
      <ReturnType>Array</ReturnType>
    </Method>

    <Method>
      <Name>query</Name>
      <Description>Query table data with paging.</Description>
      <Example><![CDATA[
        <script engine="kscript">
        var table = k.database.getTable("mytablename");
        var obj = {name: "myname", number: 124};
        table.add(obj);
        var obj2 = {name: "myname", number: 125};
        table.add(obj2);

        // query table
        var values = table.query("number>=123").orderBy("number").skip(1).take(10);
        // or the same
        var values = table.query().where("number>=123").orderBy("number").skip(1).take(10);

        /// syntax of searchCondition: fieldname operator value;
        // all available operators: ==,  >=,  >,  <,  <=, contains, startwith

        </script>
        
        
        <div k-foreach="item values">
        <p k-content="item.name">name value</p>
        <p k-content="item.number">number</p>
        </div>
        ]]></Example>
      <Params>
        <Param>
          <Name>searchCondition</Name>
          <Description>the same search condition as in the table.find method.</Description>
          <Type>Query</Type>
        </Param>
      </Params>
      <ReturnType>TableQuery</ReturnType>
    </Method>
    <Method>
      <Name>find</Name>
      <Description>Return the first item that matches the condition</Description>
      <Example><![CDATA[
        <script engine="kscript">

        var table = k.database.getTable("tablename");

        // Find  condition text can be one of the followings.
        // find item with field "name" value of "matchedvalue".
        var item = table.find("name=='matchedvalue'");

        // find item with field "number" bigger than or equal to 123.
        var item = table.find("number>=123");

        // find item with field "name" value contains "matchedvalue".
        var item = table.find("name contains 'matchedvalue'");

        // find item with field "name" value startwith "matchedvalue".
        var item = table.find("name startwith 'matchedvalue'");
        
        // &amp;&amp; can be used to combine multiple query...
        var item = table.find("name contains na &amp;&amp; number>=123");

        /// syntax of condition: fieldname operator value;
        // all available operators: ==,  >=,  >,  <,  <=, contains, startwith

        </script>
		]]></Example>
      <Params>
        <Param>
          <Name>searchCondition</Name>
          <Description>searchCondition</Description>
          <Type>Query</Type>
        </Param>
      </Params>
      <ReturnType>object</ReturnType>
    </Method>
  </Methods>
</KScriptSetting>