RecipeManagerTutorial

    containment = (
      'org.innoscript.recipemanager.schema.RecipeContainer?',
      'org.innoscript.recipemanager.schema.CookingRecipe?')

"porcupine.systemObjects.Container" class). The "containment" class attribute is a tuple of strings, containing all the types of the Porcupine objects that this container type can accept. In this case, the specified container can either accept new containers of the same type or new recipes.

    isRequired = True

    isRequired = True

    isRequired = True

    "The recipe object"

    def __init__(self):
        systemObjects.Item.__init__(self)

        self.categories = properties.Categories()

        self.rating = datatypes.Integer()
        self.rating.value = 5
        self.preparationTime = datatypes.Integer()
        self.preparationTime.value = 30
        self.servings = Servings()
        self.servings.value = 4
        self.ingredients = Ingredients()
        self.instructions = Instructions()

The name of the "categories" attribute is obligatory. This is because we have a two-way many-to-many relationship between the "CookingRecipe" and "Category" objects. To clarify this, we need to examine the "Category" content type defined in the "org/innoscript/desktop/schema/common.py" file.

...
class Category(system.Container):
  ...
  def __init__(self):
    ...
    self.category_objects = properties.CategoryObjects()

The objects' references that belong in a specified category are stored inside the "category_objects" attribute. The data type of this attribute is the "CategoryObjects" class.

Now let's take a closer look at the "CategoryObjects" data type:

class CategoryObjects?(RelatorN?):

  ...
  relCc = (
    'org.innoscript.desktop.schema.common.Document',
    'org.innoscript.desktop.schema.collab.Contact',
    'org.innoscript.recipemanager.schema.CookingRecipe?',
  )

  relAttr = 'categories'

temporarily edit the containment of the "RootFolder" content class, located inside "org/innoscript/desktop/schema/common.py".

Restart the server and login using an administrative account (admin/admin). Open the root folder (marked as Porcupine Server), right click on the list view and select "Create". Notice that the "RecipeContainer" type is added to the list of the allowed types:

Before proceeding further, please install the project as described in Installation page. Linux users can take a look to the InstallationLinux page.

Download the Recipe Manager Porcupine package file

Download the Recipe Manager Porcupine package file

"porcupine.systemObjects.Container" class). The "containment" class attribute is a tuple of strings, containing all the types of the Porcupine objects that this container type can accept. In this case, the specified container can either accept new containers of the same type or new recipes. It is worth mentioning that the special class attribute "__slots__" should not be omitted from any custom content class or data type, since instances of such types consume considerably less memory.

The "Categories" data type class is already defined; it is used for the categorization of the documents. Thus, we just need to import the following module:

The name of the "categories" attribute is obligatory. This is because we have a two-way many-to-many relationship between the "CookingRecipe" and "Category" objects. To clarify this, we need to examine the "Category" content type defined in the "org/innoscript/desktop/schema/common.py" file.

The objects' references that belong in a specified category are stored inside the "category_objects" attribute. The data type of this attribute is the "CategoryObjects" class.

Now let's take a closer look at the "CategoryObjects" data type:

should have an attribute named "categories". If the "categories" attribute is a subclass of "Relator1", then we have established an one-to-many relationship. On the other hand, if the

temporarily edit the containment of the "RootFolder" content class, located inside "common.py".

"porcupine.systemObjects.Container" content class has some

Therefore, we have to create a new recipe form using a new Web method. We start by creating the

It is recommended to maintain a separate Python file for the Web methods of each content type.

folder. The following imports are required:

As you probably already have guessed, the server formats the contents of the quix file defined in the

This Web method is invoked only when the user needs to create a new recipe. This is achieved by the use

If not then the framework invokes the aforementioned base container's "new" Web method.

This form also uses a custom widget used for editing "RelatorN" data types. This custom widget is contained inside the "org/innoscript/desktop/widgets.js" JavaScript file. The "depends" attribute defines the dependencies required by the custom widgets contained in this file. This value contains the indices of the QuiX's modules as these are defined in the QuiX.modules array in the "quix/compat.js" file.

The form's "action" parameter is the URL where the form data get posted. This is usually the HTTP address of a Porcupine object whose type has a remote Web method with the same name as this defined in the "method" form attribute (visit http://wiki.innoscript.org/index.php/Articles/RequestProcessingPipeline to see how each object is accessible over HTTP).

Respectively, when editing an existing recipe, we call the "update" Web method of the "Item" content type as defined in the "org/innoscript/desktop/webmethods/baseitem.py".

Do not forget to replace the tree node's ID with the ID of the "Recipes" folder given by the system.

The "recipemanager.loadrecipes" handler is called once whenever the user presses the "Refresh" button. This handler loads the recipes from the selected container and displays them in the list view. The "getParentByType" QuiX widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The "Window" class is defined inside the "quix/windows.js" QuiX module.

The first event handler is called whenever the context menu is displayed. The parent widget of every context menu is the desktop. Thus, there must be a way to get the menu's enclosing widget. The enclosing widget is accessible through the "owner" menu property.

Let’s see the contents of these scripts. Create a new Python script file inside the "PKG" directory named "postinstall.py". Open the file and add the following lines:

The objects’ references that belong in a specified category are stored inside the "category_objects" attribute. The data type of this attribute is the "org.innoscript.desktop.schema.properties.CategoryObjects" class. It is not considered a good practice to assign the same name to the attribute name and the data type class.

      <spinbutton name="preparationTime" top="55" left="110" width="50" max="240"
        value="$PREPARATION_TIME" editable="true" />

      <spinbutton name="servings" top="55" left="250" width="40" max="12"
        editable="true" value="$SERVINGS" />

      <spinbutton name="rating" top="55" left="360" width="40" max="10" editable="true"
        value="$RATING" />

              <treenode id="[Put here the ID of the Recipes Porcupine folder]"
                haschildren="true" img="desktop/images/folder.gif" caption="Recipes"/>

            <column width="140" caption="Recipe title" name="displayName"
              bgcolor="#EFEFEF" sortable="true"/>
            <column width="60" caption="Servings" type="int" name="servings"
              sortable="true"/>
            <column width="100" caption="Preparation time" type="int"
              name="preparationTime" sortable="true"/>

            <column width="160" caption="Date modified" type="date"
              name="modified" sortable="true"/>

    <dlgbutton onclick="generic.submitForm" width="70" height="22"

    <dlgbutton onclick="__closeDialog__" width="70" height="22"

</dialog>

The "recipemanager.loadrecipes" handler is called once whenever the user presses the "Refresh" button. This handler loads the recipes from the selected container and displays them in the list view. The "getParentByType" QuiX widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The "Window" class is defined inside the "quix/windows.js" QuiX module.

The "codegen" module provides an essential API for runtime manipulation of the Porcupine objects and data types. This script modifies an existing data type (the "CategoryObjects" class). To be precise, it adds the "org.innoscript.recipemanager.schema.CookingRecipe" content class to the list of types that can be categorized (i.e. to the "relCc" class attribute of the data type).

version=0.0.5

The first section of the package definition file has information about the package (its name and its version).

The fourth section contains the published directories that are usually contain all the files required by our application. In this case, we published the "org/innoscript/recipemanager" directory. This directory also contains all of our applications files. So, by including this section, the package will contain all the files that need to be distributed.

recipe_categories_folder=[Put here the ID of the "/Categories/Recipe categories" folder]

ce.relCc.append('org.innoscript.recipemanager.schema.CookingRecipe?')

The "codegen" module provides an essential API for runtime manipulation of the Porcupine objects and data types. This script modifies an existing data type (the "CategoryObjects" class). To be precise, it adds the "org.innoscript.recipemanager.schema.CookingRecipe?" content class to the list of types that can be categorized (i.e. to the "relCc" class attribute of the data type).

ce.relCc.remove('org.innoscript.recipemanager.schema.CookingRecipe?')

The Porcupine package file (RecipeManager-0.0.5.ppf) is created inside the Porcupine installation directory. The application can be installed on another Porcupine installation using the following command:

 $ python pakager.py –i –p RecipeManager-0.0.5.ppf

1. The porcupine.webmethods.quixui decorator is used for serving QuiX markup files defined using the "template" argument. This kind of web method is invoked over HTTP using the URL "http://SERVER_NAME/porcupine.py/OBJECT_ID?cmd=METHOD_NAME"
2. The porcupine.webmethods.remotemethod decorator is used for serving RPC requests. The method is incorporated in the request body and these kind of methods are invoked by POSTing to "http://SERVER_NAME/porcupine.py/OBJECT_ID".

of the request contains the string "cc=org.innoscript.recipemanager.schema.CookingRecipe".

This form also uses a custom widget used for editing "RelatorN" data types. This custom widget is contained inside the "org/innoscript/desktop/widgets.js" JavaScript file. The "depends" attribute defines the dependencies required for the custom widgets contained in this file. This value contains the indices of the QuiX's modules as these are defined in the QuiX.modules array in the "quix/compat.js" file.

The "CATEGORIES" key of the dictionary returned contains a semicolon delimited string of "image;id;name" triplets; this format is required by the "RelatorN" editor custom widget.

Then edit the "org/innoscript/recipemanager/webmethods/__init__.py" file:

In this section we explored two different kinds of web methods:

1. The porcupine.webmethods.quixui decorator is used for serving QuiX markup files defined using the "template" argument. This kind of web method is invoked over HTTP using the URL "http://SERVER_NAME/porcupine.py/OBJECT_ID?cmd=METHOD_NAME"
2. The porcupine.webmethods.remotemethod decorator is used for serving RPC requests. Since the name of the method is incorporated in the request body these kind of methods are invoked by POSTing? to "http://SERVER_NAME/porcupine.py/OBJECT_ID".

<?xml version="1.0" encoding="UTF-8"?> <window xmlns="http://www.innoscript.org/quix" title="Recipe manager" resizable="true"

    close="true" minimize="true" maximize="true" width="640" height="480"
    left="center" top="center">
  <script name="Recipe manager Script" src="recipemanager/recipemanager.js"/>
  <wbody>
    <box width="100%" height="100%" orientation="v" spacing="0">
      <toolbar id="toolbar" height="28">
        <tbbutton caption="Create recipe folder" width="120" disabled="true">
          <prop name="cc" value="org.innoscript.recipemanager.schema.RecipeContainer?"/>
        </tbbutton>
        <tbbutton caption="Create recipe" width="80" disabled="true">
          <prop name="cc" value="org.innoscript.recipemanager.schema.CookingRecipe?"/>
        </tbbutton>
        <tbsep/>
        <tbbutton caption="Refresh" width="60"/>
      </toolbar>
      <splitter>
        <outlookbar width="200">
          <tool caption="Recipes" bgcolor="white">

            <foldertree id="tree" method="getSubtree" padding="4,4,4,4">
              <treenode id="[Put here the ID of the Recipes Porcupine folder]" haschildren="true" img="desktop/images/folder.gif" caption="Recipes"/>
            </foldertree>

          </tool>
          <tool caption="Search" bgcolor="white">
            <label caption="Recipe title contains:"/>
            <field id="title" left="5" top="20" width="160"/>

            <label top="50" caption="Preparation time is less than"/>
            <field id="preparationTime" left="5" top="70" width="30"/>
            <label top="72" left="40" caption="min."/>

            <label top="100" caption="The recipe's rating is greater than"/>
            <spinbutton top="120" left="5" width="40" max="10" value="0" id="rating"/>

            <label top="150" caption="Recipe ingredients contain:"/>
            <field id="ingredients" top="170" left="5" width="160"/>
            <label top="190" caption="(comma separated list)" style="font-style:italic"/>

            <button top="220" left="center" width="60" height="28" caption="Search"/>
          </tool>
        </outlookbar>

        <listview id="list">

          <listheader>
            <column width="140" caption="Recipe title" name="displayName" bgcolor="#EFEFEF" sortable="true"/>
            <column width="60" caption="Servings" type="int" name="servings" sortable="true"/>
            <column width="100" caption="Preparation time" type="int" name="preparationTime" sortable="true"/>
            <column width="40" caption="Rating" type="int" name="rating" sortable="true"/>
            <column width="160" caption="Date modified" type="date" name="modified" sortable="true"/>
          </listheader>
        </listview>
      </splitter>
    </box>
  </wbody>

</window>

Let's start by adding some event handlers for the toolbar's buttons:

<toolbar id="toolbar" height="28">

  <tbbutton caption="Create recipe folder" width="120" disabled="true"

  </tbbutton>
  <tbbutton caption="Create recipe" width="80" disabled="true"

  </tbbutton>
  <tbsep />
  <tbbutton caption="Refresh" width="60"

</toolbar>

Insert the following functions inside the empty "recipemanager.js" file:

function recipemanager() {}

recipemanager.createItem = function(evt, w) {

  var oWin = w.getParentByType(Window);
  var oTree = oWin.getWidgetById('tree');

  var sCC = w.attributes.cc;

  var id = oTree.getSelection().getId();

  oWin.showWindow(id + '?cmd=new&cc=' + sCC,
    function(dlg) {
      dlg.attachEvent("onclose", recipemanager.dialogClose);
    }
  );

  var selection = oTree.getSelection();
  if (selection) {
    var id = selection.getId();
    var listView = appWin.getWidgetById('list');
    var sOql = "select id, displayName, servings, preparationTime, rating, " +
               "modified from '" + id + "' where contentclass = " +
               "'org.innoscript.recipemanager.schema.Recipe' order by displayName asc";

    var xmlrpc = new XMLRPCRequest?(QuiX?.root);
    xmlrpc.oncomplete = recipemanager.updateList;
    xmlrpc.callback_info = listView;

    xmlrpc.callmethod('executeOqlCommand', sOql);
  }

The "recipemanager.createItem" handler displays the appropriate form based on the type of the object selected by the user. This is detected by the "cc" custom attribute assigned to the toolbar buttons using the "prop" nodes. The location of the new object is determined by the current tree selection. The "showWindow" method loads an XML UI definition for a new window or dialog from a specified URL, and opens it as a child window. The second argument of this method is a function called when the interface is loaded. The first argument of this function is the dialog created. In this event, the root widget - the form dialog - will be added to the child windows of our application's main window.

The "recipemanager.loadrecipes" handler is called once whenever the user presses the "Refresh" button. This handler loads the recipes from the selected container and displays them in the list view. The "getParentByType" QuiX? widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The "Window" class is defined inside the "quix/windows.js" QuiX module.

contained inside the selected tree container. Inside this function we send a new XML-RPC request to the root folder. The "oncomplete" attribute of the request is the callback function to call when the query has completed. This callback function is always called having the request object as the first argument.

Finally, the "recipemanager.updateList" callback function updates the "dataSet" attribute of the list view and then refreshes it. The "dataSet" attribute is an array of arbitrary objects. Such an array is directly returned from the XML-RPC call.

Afterwards, we must synchronize the tree with the list view. For each new tree

<foldertree id="tree" method="getSubtree" padding="4,4,4,4"

</foldertree>

<button top="220" left="center" width="60" height="28" caption="Search"

<listview id="list"

The final enhancement is the addition of a context menu. Add the following lines to the interface definition inside the list view widget:

<listview id="list" ondblclick="recipemanager.loadItem">

  <contextmenu onshow="recipemanager.contextmenu_onshow">
    <menuoption caption="Open" onclick="recipemanager.openRecipe" />
    <menuoption caption="Delete" onclick="recipemanager.deleteRecipe" />
  </contextmenu>

   ...
 </listview>

  var oList = menu.owner;

  var oList = w.parent.owner;

  var oList = w.parent.owner;

The "document.desktop.msgbox" is used for displaying message boxes. The arguments accepted by this

from org.innoscript.desktop.schema import properties @]

In order to define the relation both ways, we have to somehow add the "CookingRecipe" object type to the list of object types that can be categorized. This is accomplished by editing the "properties.py" file inside the "org/innoscript/desktop/schema" folder. The highlighted line should be added:

[@

 $ python pakager.py –c –d PKG/recipemanager.ini

 $ python pakager.py –i –p RecipeManager-0.0.3.ppf

 python pakager.py –i –p RecipeManager?-0.0.3.ppf

    'org.innoscript.recipemanager.schema.CookingRecipe?'

In order to define the relation both ways, we have to somehow add the "CookingRecipe" object type to the list of object types that can be categorized. This is accomplished by editing the "properties.py" file inside the "org/innoscript/desktop/schema" folder. The highlighted line should be added:

      'org.innoscript.recipemanager.schema.CookingRecipe?',

Having defined all of our required data types, we proceed to the "CookingRecipe" content class definition:

class CookingRecipe?(systemObjects.Item):

The name of the "categories" attribute is obligatory. This is because we have a two-way many-to-many relationship between the "CookingRecipe" and "Category" objects. To clarify this, we need to examine the "Category" content type defined in the "org/innoscript/desktop/schema/common.py" file.

    'org.innoscript.recipemanager.schema.CookingRecipe?',

Select the "RecipeContainer" type and create a new object named "Recipes".

Finally, we also need to create the recipe categories container. Double click the "Categories" folder and create a new category folder named "Recipe categories". Please note that in case your session has expired, you just have to login again.

Before restarting the server, you can safely delete the "RecipeContainer" entry from the containment list of the "RootFolder" content type.

4. Designing a new recipe form

The current implementation of the "new" web method bound to the base container ("porcupine.systemObjects.Container") content class has some limitations that force us to design a new form for the "CookingRecipe" content type. Looking at the form that is automatically generated by the specific web method as defined in the "org/innoscript/desktop/webmethods/basecontainer.py" file, we notice the absence of the integer data types. This is happening because the web method, in its current state, ignores the numeric data types (a QuiX numeric input control, other than the spin button, is in the wish list).

Therefore, we have to create a new recipe form using a new web method. We start by creating the Python package that will host our application's web methods. Create a new folder named "webmethods" inside the "org/innoscript/recipemanager" folder and then add an empty "__init__.py" file in order to make it a Python package. It is recommended to maintain a separate Python file for the web methods of each content type.

Consequently, we create and edit a new Python file named "recipecontainer.py" inside the "webmethods" package. The following imports are required:

from porcupine import webmethods from porcupine import HttpContext?

from org.innoscript.recipemanager.schema import CookingRecipe? from org.innoscript.recipemanager.schema import RecipeContainer?

In order to overwrite the default form generated, when creating a new recipe, we must create a new web method as shown below:

@webmethods.quixui(of_type=RecipeContainer?,

                   qs="cc=org.innoscript.recipemanager.schema.CookingRecipe?",
                   template='ui.RecipeForm?.quix',
                   max_age=1200)

def new(self):

    oRecipe = CookingRecipe?()
    return {
        'URI': HttpContext?.current().request.SCRIPT_NAME + '/' + self.id,
        'METHOD': 'create',
        'TITLE': 'Create new recipe',
        'HIDDEN': '<field name="CC" type="hidden" value="org.innoscript.recipemanager.schema.CookingRecipe?" />',
        'DISPLAYNAME': oRecipe.displayName.value,
        'DESCRIPTION': oRecipe.description.value,
        'RATING': oRecipe.rating.value,
        'PREPARATION_TIME': oRecipe.preparationTime.value,
        'SERVINGS': oRecipe.servings.value,
        'INGREDIENTS': oRecipe.ingredients.value,
        'INSTRUCTIONS': oRecipe.instructions.value,
        'CATEGORIES': '',
        'ICON': oRecipe.__image__,
        'ACTION': 'Create',
    }

As you propably already have guessed, the server formats the contents of the quix file defined in the "template" argument using the dictionary returned along with the Python's built-in "string.Template" module.

This web method is invoked only when the user needs to create a new recipe. This is achieved by the use of the "qs" argument. This argument ensures that this web method is called only when the query string of the request contains the string "cc=org.innoscript.recipemanager.schema.CookingRecipe?". If not then the framework invokes the aforementioned base container's "new" web method.

The QuiX XML definition of the form is a new file named "ui.RecipeForm.quix" inside the "org/innoscript/recipemanager/webmethods" folder.

<?xml version="1.0" ?> <dialog xmlns="http://www.innoscript.org/quix" title="$TITLE" img="$ICON"

	close="true" width="480" height="380" left="30%" top="10%">
  <script name="Desktop Generic Functions" src="desktop/generic.js" /> 
  <module name="Desktop Widgets" src="desktop/widgets.js" depends="10,14,15" />
  <wbody>

    <form action="%(URI)s" method="%(METHOD)s" padding="4,4,4,4">

      $HIDDEN 
      <label caption="Recipe name:" />
      <field left="80" width="380" name="displayName" value="$DISPLAYNAME" />
      <label caption="Description:" top="25" />
      <field left="80" top="24" width="380" name="description" value="$DESCRIPTION" />
      <hr top="50" width="100%" />
      <label top="58" caption="Preparation time (min):" />
      <spinbutton name="preparationTime" top="55" left="110" width="50" max="240" value="$PREPARATION_TIME" editable="true" />
      <label top="58" left="200" caption="Servings:" />
      <spinbutton name="servings" top="55" left="250" width="40" max="12" editable="true" value="$SERVINGS" />
      <label top="58" left="320" caption="Rating:" />
      <spinbutton name="rating" top="55" left="360" width="40" max="10" editable="true" value="$RATING" />
      <tabpane top="90" width="100%" height="220">
        <tab caption="Ingredients">
          <field type="textarea" name="ingredients" width="100%" height="100%">$INGREDIENTS</field>
        </tab>
        <tab caption="Instructions">
          <field type="textarea" name="instructions" width="100%" height="100%">$INSTRUCTIONS</field>
        </tab>
        <tab caption="Categories">

          <custom classname="ReferenceN?" width="100%" height="100%"
            root="Categories/Recipe categories"
            cc="org.innoscript.desktop.schema.common.Category"
            name="categories"
            value="$CATEGORIES"/>

        </tab>
      </tabpane>
    </form>
  </wbody>

    <a:dlgbutton onclick="generic.submitForm" width="70" height="22"

      caption="$ACTION" default="true" />
    <a:dlgbutton onclick="__closeDialog__" width="70" height="22"
      caption="Cancel" />

</a:dialog>

Initially, this form imports "generic.js"; one of the desktop's JavaScript files. From this script ("org/innoscript/desktop/generic.js") we reuse the "generic.submitForm" function. This function simply submits the first QuiX form found inside the current dialog.

... generic.submitForm = function(evt, w) {

  var oDialog = w.getParentByType(Dialog);
  var oForm = oDialog.getWidgetsByType(Form)[0];
  oForm.submit(__closeDialog__);

} ...

The "submit" method of a QuiX form takes one optional argument; the function to call asynchronously, once the browser has the submission response. In this case the dialog is simply closed.

This form also uses a custom widget used for editing "RelatorN?" data types. This custom widget is contained inside the "org/innoscript/desktop/widgets.js" JavaScript file. The "depends" attribute defines the dependencies required for the custom widgets contained in this file. This value contains the indexes of the QuiX's modules as these are defined in the QuiX.modules array in the "quix/compat.js" file.

The form's "action" parameter is the URL where the form data get posted. This is usually the HTTP address of a Porcupine object whose type has a remote web method with the same name as this defined in the "method" form attribute (visit http://wiki.innoscript.org/index.php/Articles/RequestProcessingPipeline to see how each object is accessible over HTTP).

Since this template will be used both for creating and editing recipes the name of the method is diferrent in each aspect. When creating a new recipe we call the "create" web method bound the "porcupine.systemObjects.Container" base class. This method can be found in the "org/innoscript/desktop/webmethods/basecontainer.py" file:

...

@webmethods.remotemethod(of_type=Container) def create(self, data):

    "Creates a new item"
    context = HttpContext?.current()

    oNewItem = misc.getClassByName(data.pop('CC'))()

    # get user role
    iUserRole = objectAccess.getAccess(self, context.session.user)
    if data.has_key('__rolesinherited') and iUserRole == objectAccess.COORDINATOR:
        oNewItem.inheritRoles = data.pop('__rolesinherited')
        if not oNewItem.inheritRoles:
            acl = data.pop('__acl')
            if acl:
                security = {}
                for descriptor in acl:
                    security[descriptor['id']] = int(descriptor['role'])
                oNewItem.security = security

    # set props
    for prop in data:
        oAttr = getattr(oNewItem, prop)
        if isinstance(oAttr, datatypes.File):
            if data[prop]['tempfile']:
                oAttr.filename = data[prop]['filename']
                sPath = context.server.temp_folder + '/' + data[prop]['tempfile']
                oAttr.loadFromFile(sPath)
                os.remove(sPath)
        elif isinstance(oAttr, datatypes.Date):
            oAttr.value = data[prop].value
        elif isinstance(oAttr, datatypes.Integer):
            oAttr.value = int(data[prop])
        else:
            oAttr.value = data[prop]

    txn = db.getTransaction()
    oNewItem.appendTo(self, txn)
    txn.commit()

    return oNewItem.id

...

The "data" argument contains the form data. It is a Python dictionary containing the field names and values.

This method requires an additional field posted named "CC". This field contains the type of the object that is going to be appended to the calling container. Each XML-RPC method should always return a value. This remote method returns the ID of the newly created object.

Apart from creating recipes we should also be able to edit them. In order to override the default edit form, we need to override the "properties" web method of the "CookingRecipe" content class. Create a new Python module named "cookingrecipe.py" inside the "org/innoscript/recipemanager/webmethods" folder and add the following code:

from porcupine import webmethods from porcupine import HttpContext?

from org.innoscript.recipemanager.schema import CookingRecipe?

@webmethods.quixui(of_type=CookingRecipe?,

                   template='ui.RecipeForm?.quix')

def properties(self):

    categories = []
    # build the categories
    for category in self.categories.getItems():
        categories.extend([category.__image__, category.id, category.displayName.value])
    return {
      'URI': HttpContext?.current().request.SCRIPT_NAME + '/' + self.id,
      'METHOD': 'update',
      'TITLE': 'Recipe properties',
      'HIDDEN': '',
      'DISPLAYNAME': self.displayName.value,
      'DESCRIPTION': self.description.value,
      'RATING': self.rating.value,
      'PREPARATION_TIME': self.preparationTime.value,
      'SERVINGS': self.servings.value,
      'INGREDIENTS': self.ingredients.value,
      'INSTRUCTIONS': self.instructions.value,
      'CATEGORIES': ';'.join(categories),
      'ICON': self.__image__,
      'ACTION': 'Update',
    }

Respectively, when editing an existing recipe, we call the "update" method of the "porcupine.systemObjects.Item" content type as defined in the "org/innoscript/desktop/webmethods/baseitem.py".

The "CATEGORIES" key of the dictionary returned contains a semicolon delimited string of "image;id;name" triplets; this format is required by the "RelatorN?" editor custom widget.

Before restarting the server we need to import our newly created web methods for these to take effect. First edit the "org/innoscript/recipemanager/__init__.py" file by adding the following import:

from org.innoscript.recipemanager.webmethods import *

The edit the "org/innoscript/recipemanager/webmethods/__init__.py" file:

__all__ = ['cookingrecipe', 'recipecontainer']

Restart the server. If everything is in place, you should see the following form when choosing to create a new recipe:

5. The Recipe Manager application

Apart from the custom forms and the custom content types, we will also need a custom UI for our application tailored to the given requirements. This is accomplished by creating a new application object. The Porcupine desktop provides generic interfaces and almost in every case, will not meet the requirements analysis.

Before creating our application object we must publish the "org/innoscript/recipemanager" direcotry. This directory will contain our applications XML UI definition and the required JavaScript functions. Edit the "conf/pubdir.xml" configuration file by adding the highlighted node:

<config>

	<dirs>
		<dir name="__quix" path="quix"/>
		<dir name="desktop" path="org/innoscript/desktop"/>
		<dir name="hypersearch" path="org/innoscript/hypersearch"/>
		<dir name="usermgmnt" path="org/innoscript/usermgmnt"/>
		<dir name="queryperformer" path="org/innoscript/queryperformer"/>

		<dir name="recipemanager" path="org/innoscript/recipemanager"/>

	</dirs>

</config>

Each published directory must contain a file called "config.xml". This file keeps track of the files accesible over HTTP. This file should be:

<config>

	<context path="recipemanager.quix"
		method="GET"
		client=".*"
		lang=".*"
		action="recipemanager.quix"/>
	<context path="recipemanager.js"
		method="GET"
		client=".*"
		lang=".*"
		action="recipemanager.js"/>

</config>

To create a new application, login to Porcupine as an administrator and navigate to the "Administrative Tools/Applications" folder. Inside the "Launch URL" input box type "recipemanager/recipemanager.quix". Press the "Create" button to create the application object.

Next, create a new text file named "recipemanager.quix" inside the "recipemanager" folder we just published.

Do not forget to replace the tree node’s ID with the ID of the “Recipes” folder given by the system. The contents of this file are:

<?xml version="1.0" encoding="UTF-8"?> <a:window xmlns:a="http://www.innoscript.org/quix" title="Recipe manager" resizable="true" close="true" minimize="true" maximize="true" img="" width="640" height="480" left="center" top="center">

  <a:script name="Recipe manager Script" src="recipemanager/recipemanager.js"/>
  <a:wbody>
    <a:box width="100%" height="100%" orientation="v" spacing="0">
      <a:toolbar height="28">
        <a:tbbutton caption="Create recipe folder" width="120">
          <a:prop name="cc" value="org.innoscript.recipemanager.schema.RecipeContainer?"/>
        </a:tbbutton>
        <a:tbbutton caption="Create recipe" width="80">
          <a:prop name="cc" value="org.innoscript.recipemanager.schema.Recipe"/>
        </a:tbbutton>
        <a:tbsep/>
        <a:tbbutton caption="Refresh" width="60"/>
      </a:toolbar>
      <a:splitter height="-1" orientation="v" interactive="true">
        <a:pane length="200">
          <a:outlookbar width="100%" height="100%">
            <a:tool caption="Recipes">

              <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4">
                <a:treenode id="[Put here the ID of the Recipes Porcupine folder]" haschildren="true"
                img="desktop/images/folder.gif" caption="Recipes"/>

              </a:foldertree>
            </a:tool>
            <a:tool caption="Search" bgcolor="gray">
              <a:label caption="Recipe title contains:"/>
              <a:field id="title" left="5" top="20" width="160"/>

              <a:label top="50" caption="Preparation time is less than"/>
              <a:field id="preparationTime" left="5" top="70" width="30"/>
              <a:label top="72" left="40" caption="min."/>

              <a:label top="100" caption="The recipe's rating is greater than"/>
              <a:spinbutton top="120" left="5" width="40" max="10" value="0" id="rating"/>

              <a:label top="150" caption="Recipe ingredients contain:"/>
              <a:field id="ingredients" top="170" left="5" width="160"/>
              <a:label top="190" caption="(comma separated list)" style="font-style:italic"/>

              <a:button top="220" left="center" width="60" height="28" caption="Search"/>
            </a:tool>
          </a:outlookbar>
        </a:pane>
        <a:pane length="-1">

          <a:listview width="100%" height="100%" id="list">

            <a:listheader>
              <a:column width="140" caption="Recipe title" name="displayName" bgcolor="#EFEFEF" sortable="true"/>
              <a:column width="60" caption="Servings" type="int" name="servings" sortable="true"/>
              <a:column width="100" caption="Preparation time" type="int" name="preparationTime" sortable="true"/>
              <a:column width="40" caption="Rating" type="int" name="rating" sortable="true"/>
              <a:column width="160" caption="Date modified" type="date" name="modified" sortable="true"/>
            </a:listheader>
          </a:listview>
        </a:pane>
      </a:splitter>
    </a:box>
  </a:wbody>

</a:window>

The folder tree widget and the list view have been given an ID for them to become easily accessible from our scripts. The "method" attribute is the XML-RPC method to call whenever the user expands a tree node. Notice that the interface includes a JavaScript file with a "script" node right after the window's opening tag. Thus, create an empty JavaScript file named "recipemanager.js" inside the application folder.

Let's start by adding some event handlers.

<a:toolbar width="100" height="100">

  <a:tbbutton caption="Create recipe folder" width="120"

    onclick="recipemanager.createItem">

    ...
  </a:tbbutton>
  <a:tbbutton caption="Create recipe" width="80"

    onclick="recipemanager.createItem">

    ...
  </a:tbbutton>
  <a:tbsep />
  <a:tbbutton caption="Refresh" width="60"

    onclick="recipemanager.refresh_onclick" />

</a:toolbar> ... <a:listview id="list" multiple="true" width="100" height="100"

  onload="recipemanager.loadRecipes">

  ...

Insert the following functions inside the empty "recipemanager.js" file:

function recipemanager() {}

recipemanager.createItem = function(evt, w) {

  var oWin = w.getParentByType(Window);
  var oTree = oWin.getWidgetById('tree');

  var sCC = w.attributes.cc;

  var id = oTree.getSelection().getId();

  oWin.showWindow(id + '?cmd=new&cc=' + sCC,
    function(dlg) {
      dlg.attachEvent("onclose", recipemanager.dialogClose);
    }
  );

}

recipemanager.dialogClose = function(dlg) {

  if (dlg.buttonIndex == 0) {
    recipemanager.refreshList(dlg.opener);
  }

}

recipemanager.refresh_onclick = function(evt, w) {

  recipemanager.loadRecipes(w);

}

recipemanager.loadRecipes = function(w) {

  var appWin = w.getParentByType(Window);
  recipemanager.refreshList(appWin);

}

recipemanager.refreshList = function(appWin) {

  var oTree = appWin.getWidgetById('tree');
  var id = oTree.getSelection().getId();
  var listView = appWin.getWidgetById('list');
  var sOql = "select id, displayName, servings, preparationTime, rating, " +
             "modified from '" + id + "' where contentclass = " +
             "'org.innoscript.recipemanager.schema.Recipe' order by displayName asc";

  var xmlrpc = new XMLRPCRequest?(QuiX?.root);
  xmlrpc.oncomplete = recipemanager.updateList;
  xmlrpc.callback_info = listView;

  xmlrpc.callmethod('executeOqlCommand', sOql);

}

recipemanager.updateList = function(req) {

  req.callback_info.dataSet = req.response;
  req.callback_info.refresh();

}

The "recipemanager.createItem" handler displays the appropriate form based on the type of the object selected by the user. This is detected by the "cc" custom attribute assigned to the toolbar buttons using the "a:prop" nodes. The location of the new object is determined by the current tree selection. The "showWindow" method loads an XML UI definition for a new window or dialog from a specified URL, and opens it as a child window. The second argument of this method is a function called when the interface is loaded. The first argument of this function is the dialog created. In this event, the root widget - the form dialog - will be added to the child windows of our application's main window.

The "recipemanager.loadrecipes" handler is called once when the list view is loaded. This handler loads the recipes from the selected container and displays them in the list view. The "onload" event handler, unlike the other events, does not accept the two common event handler arguments, the event object and the widget, but instead accepts only the widget that fires the event. The "getParentByType" QuiX? widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The "Window" class is defined inside the "quix/windows.js" QuiX module.

The "recipemanager.refreshList" function executes the OQL query that returns the recipes contained inside the selected tree container. Inside this function we send a new XMLRPC request to the root folder. The "oncomplete" attribute of the request is the callback function to call when the query has completed. This function is always called having the request object as the first argument. The "callback_info" attribute is a placeholder for anything we would like to access inside the callback function. In this case, the "callback_info" is a reference to the list view widget.

Finally, the "recipemanager.updateList" callback function updates the "dataSet" attribute of the list view and then refreshes it. The "dataSet" attribute is an array of arbitrary objects. Such an array is directly returned from the XMLRPC call.

Afterwards, we must synchronize the tree with the list view. This means that for each new tree selection we should update the list view accordingly. This is accomplished by adding the following event handler:

... <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4"

  onselect="recipemanager.loadRecipes">

  ...

</a:foldertree> ...

Next, we implement the search functionality. We start by adding a new "onclick" event handler on the search button:

... <a:button top="220" left="center" width="60" height="28" caption="Search"

  onclick="recipemanager.search" />

...

Add the following function inside the "recipemanager.js" file:

recipemanager.search = function(evt, w) {

  var displayName = w.parent.getWidgetById('title').getValue();
  var preparationTime = w.parent.getWidgetById('preparationTime').getValue();
  var rating = w.parent.getWidgetById('rating').getValue
  var ingredients = w.parent.getWidgetById('ingredients').getValue();
  var sOql = "select id, displayName, servings, preparationTime, rating, " +

             "modified from deep('/Recipes')";

  var listView = w.getParentByType(Window).getWidgetById('list');
  var conditions = ["contentclass='schemas.org.innoscript.recipemanager.Recipe'"];
  if (displayName!='') {
    conditions.push("'" + displayName + "' in displayName");
  }
  if (preparationTime!='') {
    conditions.push("preparationTime < " + preparationTime);
  }
  if (rating>0) {
    conditions.push("rating > " + rating);
  }
  if (ingredients!='') {
    var arrIng = ingredients.split(',');
    for (var i=0; i<arrIng.length; i++) {
      conditions.push("'" + arrIng[i] + "' in ingredients");
    }
  }
  if (conditions.length > 0) {
    sOql += ' where ' + conditions.join(' and ');
    var xmlrpc = new XMLRPCRequest?(QuiX?.root);
    xmlrpc.oncomplete = recipemanager.updateList;
    xmlrpc.callback_info = listView;
    xmlrpc.callmethod('executeOqlCommand', sOql);
  }

The above function forms the OQL query according to the criteria set by the user on the search form. Notice that we search all the recipes, by using the "deep" operator at the select scope. Also when the user double clicks on the list view, the selected recipe dialog should open:

<a:listview multiple="true" width="100" height="100" id="list"

  onload="recipemanager.loadRecipes"

  ondblclick="recipemanager.loadItem">

The following event handler should be added to the script of the application:

recipemanager.loadItem = function(evt, w, recipe) {

  var oWin = w.getParentByType(Window);
  oWin.showWindow(recipe.id + "?cmd=properties",
    function(dlg) {
      dlg.attachEvent("onclose", recipemanager.dialogClose);
    }
  );

}

This handler opens the recipe form when a recipe item is double clicked on the list. It also attaches an "onclose" handler to the recipe form. In case of the recipe being updated this handler reloads the list items.

The final enhancement is the addition of a context menu. Open the application object and add the following lines to the interface definition:

<a:pane length="-1">

  <a:contextmenu onshow="recipemanager.contextmenu_onshow">
    <a:menuoption caption="Open" onclick="recipemanager.openRecipe" />
    <a:menuoption caption="Delete" onclick="recipemanager.deleteRecipe" />
  </a:contextmenu>

  <a:listview width="100" height="100" id="list"
    onload="recipemanager.loadRecipes" ondblclick="recipemanager.loadItem">
    ...
  </a:listview>

</a:pane>

Add the following handlers to the application’s script:

recipemanager.contextmenu_onshow = function(menu) {

  var oList = menu.owner.getWidgetById('list');

  menu.options[0].disabled = (oList.selection.length == 0); //open
  menu.options[1].disabled = (oList.selection.length == 0); //properties

}

recipemanager.openRecipe = function(evt, w) {

  var oList = w.parent.owner.getWidgetById('list');
  var oWin = oList.getParentByType(Window);
  var selectedRecipe = oList.getSelection();
  oWin.showWindow(selectedRecipe.id + "?cmd=properties",
    function(dlg) {
      dlg.attachEvent("onclose", recipemanager.dialogClose);
    }
  );

}

recipemanager.deleteRecipe = function(evt, w) {

  var oList = w.parent.owner.getWidgetById('list');
  var selectedRecipe = oList.getSelection();
  var desktop = document.desktop;
  var _deleteItem = function(evt, w) {
    var oMsgBox = w.getParentByType(Dialog);
    var xmlrpc = new XMLRPCRequest?(QuiX?.root + selectedRecipe.id);
    xmlrpc.oncomplete = function(req) {
      oMsgBox.close();
      recipemanager.loadRecipes(oList);
    }
    xmlrpc.onerror = function(req) { oMsgBox.close(); }
    xmlrpc.callmethod('delete');
  }

  desktop.msgbox(w.getCaption(),

    "Are you sure you want to delete this recipe?",
    [
      [desktop.attributes['YES'], 60, _deleteItem],
      [desktop.attributes['NO'], 60]
    ],
    'desktop/images/messagebox_warning.gif', 'center', 'center', 260, 112);

}

The first event handler is called whenever the context menu is displayed. The parent widget of every context menu is the desktop. Thus, there must be a way to get the menu’s enclosing widget. The enclosing widget is accessible through the "owner" menu property.

The "desktop.msgbox" is used for displaying message boxes. The arguments accepted by this method are:

1. The title of the message box.
2. The message displayed in the message box.
3. An array of the buttons. Each button is also an array of three elements. The first element is the caption of the button, the second is the width of the button, and the third is the function to call once the button is clicked. If omitted the button closes the message box.
4. The image displayed inside the message box.
5. The x-coordinate of the message box.
6. The y-coordinate of the message box.
7. The width of the message box.
8. The height of the message box.

Next, log off and log on again. Launch the recipe manager application. If you see the following window, then congratulations, you have just created your first Porcupine application!

6. Packaging your application

Using the "pakager" utility we will consolidate all of the application’s pieces into a single distributable file. This procedure requires at least one package definition file. Create a new folder named "PKG" inside the porcupine installation directory. Inside this folder create a new file named "recipemanager.ini". Edit the contents of this file and add the following sections:

[package] name=RecipeManager? version=0.0.4

The first section of the package definition file has information about the package (its name and its version). Please notice that the name of the package and the value of the name attribute of the package node in the "store.xml" configuration file must be identical.

[files]

The second section contains the relative paths to any files that need to be included in the package. Leave this section blank.

[dirs]

This section adds directories to the package.

[pubdir] 1=recipemanager

The fourth section contains the published directories (usually containing external JavaScript files and images) that are required by the application. In this case, we published the "org/innoscript/recipemanager" directory. This directory also contains all of our applications files. So, by including this section, the package will contain all the files that need to be distributed.

[items] application=[Put here the ID of the Recipe Manager application] recipes_folder=[Put here the ID of the "/Recipes" folder] recipe_categories_folder=[Put here the ID of the "/Categories/Recipe categories" folder]

In this section we include all the Porcupine objects to export in the package, including the application object itself. Replace the highlighted portions with the object IDs printed on their properties dialog.

[scripts] postinstall=PKG/postinstall.py uninstall=PKG/uninstall.py

The "scripts" section contains Python script files included in the package. The "postinstall" executes immediately after the installation finishes. The "uninstall" script executes when the application is uninstalled.

Let’s see the contents of these scripts. Create a new Python script file inside the “PKG” directory named "postinstall.py". Open the file and add the following lines:

1. RecipeManager? post installation script

from porcupine.administration import codegen ce = codegen.DatatypeEditor?('org.innoscript.desktop.schema.properties.CategoryObjects?')

ce.relCc.append('org.innoscript.recipemanager.schema.Recipe')

ce.commitChanges()

The "codegen" module provides an essential API for runtime manipulation of the Porcupine objects and data types. This script modifies an existing data type (the "CategoryObjects" class). To be precise, it adds the "org.innoscript.recipemanager.schema.Recipe" content class to the list of types that can be categorized (i.e. to the "relCc" class attribute of the data type). Similarly, inside the "PKG" folder create a new Python script named "uninstall.py". Open the file and add the following lines:

1. RecipeManager? uninstallation script

from porcupine.administration import codegen ce = codegen.DatatypeEditor?('org.innoscript.desktop.schema.properties.CategoryObjects?')

ce.relCc.remove('org.innoscript.recipemanager.schema.Recipe')

ce.commitChanges()

Initially, this form imports "generic.js"; one of the QuiX desktop's JavaScript files. From this script (org/innoscript/desktop/generic.js) we reuse the "generic.submitForm" function. This function simply submits the first QuiX form found inside the current dialog.

Now let’s take a closer look at the “CategoryObjects” data type:

The "codegen" module provides an essential API for runtime manipulation of the Porcupine objects and data types. This script modifies an existing data type (the "CategoryObjects" class). To be precise, it adds the "org.innoscript.recipemanager.schema.Recipe" content class to the list of types that can be categorized (i.e. to the "relCc" class attribute of the data type).

browser GETs on a "RecipeContainer" object with the "cmd" query parameter set to "new" and the query string contains the string "org.innoscript.recipemanager.schema.RecipeContainer" (this is the

browser GETs on a "RecipeContainer" object with the "cmd" query parameter set to "new" but this

module. First, we import the "XULServlet" class and the content classes’ module we just created:

recipe, we must create two new registrations. One for each type accepted by the "RecipeContainer" type (recipe containers and recipes). For the recipe container, we will use the desktop's "Frm_Auto" servlet, but for the recipe items we will use our own servlet which outputs our custom QuiX form. This is shown below:

Before proceeding to the recipe form itself, we must modify the "store.xml" configuration file by adding – modifying the highlighted lines:

<package name="RecipeManager?">

  <reg cc="org.innoscript.recipemanager.schema.RecipeContainer?"
    method="POST"
    param=""
    client="vcXMLRPC"
    lang=".*"
    action="org.innoscript.desktop.XMLRPC.ContainerGeneric?"/>

  <reg cc="org.innoscript.recipemanager.schema.RecipeContainer?"
    qs="org.innoscript.recipemanager.schema.RecipeContainer?"
    client="(MSIE [6-7])|(Mozilla/5.0.+rv:1.[7-9])"
    lang=".*"
    method="GET"
    param="new"
    action="org.innoscript.desktop.ui.Frm_AutoNew">
      <filter type="porcupine.filters.postProcessing.multilingual.Multilingual"
	      using="org.innoscript.desktop.strings.resources"/>
  </reg>
  <reg cc="org.innoscript.recipemanager.schema.RecipeContainer?"
     qs="org.innoscript.recipemanager.schema.Recipe"
     client="(MSIE [6-7])|(Mozilla/5.0.+rv:1.[7-9])"
     lang=".*"
     method="GET"
     param="new"
     action="org.innoscript.recipemanager.ui.RecipeForm?"/>
  <reg cc="org.innoscript.recipemanager.schema.Recipe$"
    method="GET"
    param="properties"
    client="(MSIE [6-7])|(Mozilla/5.0.+rv:1.[7-9])"
    lang=".*"
    action="org.innoscript.recipemanager.ui.RecipeForm?"/>

<package>

The first highlighted registration assigns the "Frm_AutoNew" as the servlet to be executed when the browser GETs? on a "RecipeContainer" object with the "cmd" query parameter set to "new" and the query string contains the string "org.innoscript.recipemanager.schema.RecipeContainer?" (this is the new "qs" parameter).

The second highlighted registration assigns the "RecipeForm" as the servlet to be executed when the browser GETs? on a "RecipeContainer" object with the "cmd" query parameter set to "new" but this time when the query string contains the string "org.innoscript.recipemanager.schema.Recipe".

The last registration is for for the "Recipe" type, and renders the recipe form whenever a compatible browser GETs? on an object of this type with the parameter set to "properties".

Now let's write the "RecipeForm" servlet:

class RecipeForm?(XULServlet?):

  def setParams(self):
    sCC = self.item.contentclass
    sCategories = ''
    sHiddenField = ''
    if sCC == 'org.innoscript.recipemanager.schema.RecipeContainer?':
      # we create a new recipe
      sTitle = 'Create new recipe'
      oRecipe = schema.Recipe()
      # in this case we need an extra hidden field with the type of
      # object we are about to create
      sHiddenField = '<a:field name="CC" type="hidden" ' +         'value="schemas.org.innoscript.recipemanager.Recipe" />'
      sMethod = 'create'
      sAction = 'Create'
    elif sCC == 'org.innoscript.recipemanager.schema.Recipe':
      # we editing an existing one
      oRecipe = self.item
      sMethod = 'update'
      sTitle = 'Recipe properties'
      sAction = 'Update'
    # build the categories options list
    for category in oRecipe.categories.getItems():
      sCategories += '<a:option caption="s" img="%s" />' %
        (category.displayName.value, category.id, category.__image__)
    self.params = {
      'URI': self.request.serverVariables['SCRIPT_NAME'] + '/' + self.item.id,
      'METHOD': sMethod,
      'TITLE': sTitle,
      'HIDDEN': sHiddenField,
      'DISPLAYNAME': oRecipe.displayName.value,
      'DESCRIPTION': oRecipe.description.value,
      'RATING': oRecipe.rating.value,
      'PREPARATION_TIME': oRecipe.preparationTime.value,
      'SERVINGS': oRecipe.servings.value,
      'INGREDIENTS': oRecipe.ingredients.value,
      'INSTRUCTIONS': oRecipe.instructions.value,
      'CATEGORIES': sCategories,
      'ICON': oRecipe.__image__,
      'ACTION': sAction,
    }

This servlet is called either when the user needs to create a new recipe, or when the user wants to display the properties of an existing recipe. In the first case, the type of the object "called" is the "RecipeContainer" unlike the second case, in which the type of the object is the "Recipe" type.

The QuiX XML definition of the form is a new file named "ui.RecipeForm.quix" inside the "org/innoscript/recipemanager" folder.

<?xml version="1.0" ?> <a:dialog xmlns:a="http://www.innoscript.org/quix" title="%(TITLE)s" img="%(ICON)s" close="true" width="480" height="380" left="30" top="10">

    <a:script name="Generic Functions" src="desktop/generic.js" />
    <a:wbody>

        <a:form action="%(URI)s" method="%(METHOD)s" padding="4,4,4,4">

            %(HIDDEN)s
            <a:label caption="Recipe name:"/>
            <a:field left="80" width="380" name="displayName"
              value="%(DISPLAYNAME)s" />
            <a:label caption="Description:" top="25" />
            <a:field left="80" top="24" width="380" name="description"
              value="%(DESCRIPTION)s" />
            <a:hr top="50" width="100" />
            <a:label top="58" caption="Preparation time (min):" />
            <a:spinbutton name="preparationTime" top="55" left="110" width="50" 
              max="240" value="%(PREPARATION_TIME)d" editable="true" />
            <a:label top="58" left="200" caption="Servings:" />
            <a:spinbutton name="servings" top="55" left="250" width="40" max="12"
              editable="true" value="%(SERVINGS)d" />
            <a:label top="58" left="320" caption="Rating:" />
            <a:spinbutton name="rating" top="55" left="360" width="40" max="10"
              editable="true" value="%(RATING)d" />
            <a:tabpane top="90" width="100" height="220">
                <a:tab caption="Ingredients">
                    <a:field type="textarea" name="ingredients" width="100"
                      height="100">%(INGREDIENTS)s</a:field>
                </a:tab>
                <a:tab caption="Instructions">
                    <a:field type="textarea" name="instructions" width="100"
                      height="100">%(INSTRUCTIONS)s</a:field>
                </a:tab>
                <a:tab caption="Categories">
                    <a:box width="100" height="100" orientation="v">
                        <a:selectlist name="categories" multiple="true" posts="all" height="-1">
                            <a:prop name="SelectFrom?" value="Categories/Recipe categories"></a:prop>
                            <a:prop name="RelatedCC?" value="org.innoscript.desktop.schema.common.Category"/>
                            %(CATEGORIES)s
                        </a:selectlist>
                        <a:rect height="24">
                            <a:flatbutton width="70" height="22" caption="Add"

                              onclick="generic.selectItems"></a:flatbutton>

                            <a:flatbutton left="80" width="70" height="22" caption="Remove"

                              onclick="generic.removeSelectedItems"></a:flatbutton>

                        </a:rect>
                    </a:box>

            </a:tabpane>
        </a:form>
    </a:wbody>

    <a:dlgbutton onclick="generic.submitForm" width="70" height="22"

      caption="%(ACTION)s" default="true" />
    <a:dlgbutton onclick="__closeDialog__" width="70" height="22"
      caption="Cancel" />

</a:dialog>

Initially, this form imports one of the QuiX desktop JavaScript files. One of the functions we reuse from this script (org/innoscript/desktop/generic.js) is the "generic.submitForm" function. This function simply submits the first QuiX form found inside the current dialog.

... generic.submitForm = function(evt, w) {

	var oDialog = w.getParentByType(Dialog);
	var oForm = oDialog.getWidgetsByType(Form)[0];
	oForm.submit(__closeDialog__);

} ...

The "submit" method of a QuiX form takes one argument; the function to call asynchronously, once the browser has the submission response. In this case the dialog is simply closed.

The form's "action" parameter is the URL where the form data get posted. This is usually the HTTP address of a Porcupine object whose type has an XMLRPC servlet registered in the "store.xml" configuration file (visit http://wiki.innoscript.org/index.php/Articles/RequestProcessingPipeline to see how each object is accessible over HTTP).

The form's "method" parameter is the name of the method of the XMLRPC servlet to call. Since this form is used for both creating and editing recipes the name of the method is diferrent in each aspect. When creating a new recipe we call the "create" method of the "org.innoscript.desktop.XMLRPC.ContainerGeneric" XMLRPC servlet.

...

class ContainerGeneric?(ItemGeneric?):

  def create(self, data):

    # create new item

    oNewItem = misc.getClassByName(data.pop('CC'))()

    # get user role
    iUserRole = objectAccess.getAccess(self.item, self.session.user)
    if data.has_key('__rolesinherited') and iUserRole ==     objectAccess.COORDINATOR:
      oNewItem.inheritRoles = data.pop('__rolesinherited')
      if not oNewItem.inheritRoles:
        acl = data.pop('__acl')
        if acl:
          security = {}
          for descriptor in acl:
            security[descriptor['id']] = int(descriptor['role'])
          oNewItem.security = security
    # set props
    for prop in data:
      oAttr = getattr(oNewItem, prop)
      if isinstance(oAttr, datatypes.File):
        if data[prop]['tempfile']:
          oAttr.filename = data[prop]['filename']
          sPath = self.server.temp_folder + '/' + data[prop]['tempfile']
          oAttr.loadFromFile(sPath)
          os.remove(sPath)
      elif isinstance(oAttr, datatypes.Date):
        oAttr.value = data[prop].value
      else:
        oAttr.value = data[prop]

    txn = self.server.store.getTransaction()
    oNewItem.appendTo(self.item.id, txn)
    txn.commit()

    return True

...

The "data" argument contains the form data. It is a Python dictionary containing the field names and values.

This method requires an additional field posted named "CC". This field contains the type of the object that is going to be appended to the calling container. Each XML-RPC method should always return a value. This method simply returns "True" only if the object is created and appended to the container successfully. This way, the browser knows that the request has been succefully completed.

Also notice, that the "ContainerGeneric" servlet is a subclass of the "ItemGeneric" servlet. Besides the container specific methods defined, a container can also be updated, copied or renamed just like any other Porcupine object.

Respectively, when editing an existing recipe, we call the "update" method of the "org.innoscript.desktop.XMLRPC.ItemGeneric" XMLRPC servlet.

From the "generic.js" file we also reuse two JavaScript functions named "generic.selectItems" and "generic.removeSelectedItems".

generic.selectItems = function(evt, w) {

  var oDialog = w.getParentByType(Dialog);
  var oTarget = w.parent.parent.getWidgetsByType(SelectList?)[0];
  var sFolderURI = oTarget.attributes.SelectFrom?;
  var sCC = oTarget.attributes.RelatedCC?;

  generic.selectObjects(oDialog, oTarget, generic.addSelectionToList,
    sFolderURI, sCC, 'true');

} ... generic.selectObjects = function(win, target, select_func, startFrom, contentclass, multiple) {

  ...

} ... generic.removeSelectedItems = function(evt, w) {

  var oSelectList = w.parent.parent.getWidgetsByType(SelectList?)[0];
  oSelectList.removeSelected();

} ...

The "generic.selectItems" function displays the object select dialog by calling the "generic.selectObjects" function. The auto-generated form servlet uses this function for "ReferenceN" or "RelatorN" data types. The arguments given to the "generic.selectObjects" function are:

• win: the opener
• target: the target widget (in this case, the select list included in the recipe form)
• select_func: the function to call when the user presses the "Select" button
• startFrom: The ID of the root node of the tree (in this case, the "SelectFrom" custom attribute of the select list on the recipe form)
• contentclass: The type of the Porcupine objects that we can select
• multiple: "true" if multiple selection is allowed, else "false"

Restart the server. If everything is in place, you should see the following form when choosing to create a new recipe:

5. The Recipe Manager application

Apart from the custom forms and the custom content types, we will also need a custom UI for our application tailored to the given requirements. This is accomplished by creating a new application object. The Porcupine desktop provides generic interfaces and almost in every case, will not meet the requirements analysis.

Before creating our application object we must publish the "org/innoscript/recipemanager" direcotry. This directory will contain our applications XML UI definition and the required JavaScript functions. Edit the "conf/pubdir.xml" configuration file by adding the highlighted node:

<config>

	<dirs>
		<dir name="__quix" path="quix"/>
		<dir name="desktop" path="org/innoscript/desktop"/>
		<dir name="hypersearch" path="org/innoscript/hypersearch"/>
		<dir name="usermgmnt" path="org/innoscript/usermgmnt"/>
		<dir name="queryperformer" path="org/innoscript/queryperformer"/>

		<dir name="recipemanager" path="org/innoscript/recipemanager"/>

	</dirs>

</config>

Each published directory must contain a file called "config.xml". This file keeps track of the files accesible over HTTP. This file should be:

<config>

	<context path="recipemanager.quix"
			 method="GET"
			 client=".*"
			 lang=".*"
			 action="recipemanager.quix"/>
	<context path="recipemanager.js"
			 method="GET"
			 client=".*"
			 lang=".*"
			 action="recipemanager.js"/>

</config>

To create a new application, login to Porcupine as an administrator and navigate to the "Administrative Tools/Applications" folder. Inside the "Launch URL" input box type "recipemanager/recipemanager.quix". Press the "Create" button to create the application object.

Next, create a new text file named "recipemanager.quix" inside the "recipemanager" folder we just published.

Do not forget to replace the tree node’s ID with the ID of the “Recipes” folder given by the system. The contents of this file are:

<?xml version="1.0" encoding="UTF-8"?> <a:window xmlns:a="http://www.innoscript.org/quix" title="Recipe manager" resizable="true" close="true" minimize="true" maximize="true" img="" width="640" height="480" left="center" top="center">

  <a:script name="Recipe manager Script" src="recipemanager/recipemanager.js"/>
  <a:wbody>
    <a:box width="100%" height="100%" orientation="v" spacing="0">
      <a:toolbar height="28">
        <a:tbbutton caption="Create recipe folder" width="120">
          <a:prop name="cc" value="org.innoscript.recipemanager.schema.RecipeContainer?"/>
        </a:tbbutton>
        <a:tbbutton caption="Create recipe" width="80">
          <a:prop name="cc" value="org.innoscript.recipemanager.schema.Recipe"/>
        </a:tbbutton>
        <a:tbsep/>
        <a:tbbutton caption="Refresh" width="60"/>
      </a:toolbar>
      <a:splitter height="-1" orientation="v" interactive="true">
        <a:pane length="200">
          <a:outlookbar width="100%" height="100%">
            <a:tool caption="Recipes">

              <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4">
                <a:treenode id="[Put here the ID of the Recipes Porcupine folder]" haschildren="true"
                img="desktop/images/folder.gif" caption="Recipes"/>

              </a:foldertree>
            </a:tool>
            <a:tool caption="Search" bgcolor="gray">
              <a:label caption="Recipe title contains:"/>
              <a:field id="title" left="5" top="20" width="160"/>

              <a:label top="50" caption="Preparation time is less than"/>
              <a:field id="preparationTime" left="5" top="70" width="30"/>
              <a:label top="72" left="40" caption="min."/>

              <a:label top="100" caption="The recipe's rating is greater than"/>
              <a:spinbutton top="120" left="5" width="40" max="10" value="0" id="rating"/>

              <a:label top="150" caption="Recipe ingredients contain:"/>
              <a:field id="ingredients" top="170" left="5" width="160"/>
              <a:label top="190" caption="(comma separated list)" style="font-style:italic"/>

              <a:button top="220" left="center" width="60" height="28" caption="Search"/>
            </a:tool>
          </a:outlookbar>
        </a:pane>
        <a:pane length="-1">

          <a:listview width="100%" height="100%" id="list">

            <a:listheader>
              <a:column width="140" caption="Recipe title" name="displayName" bgcolor="#EFEFEF" sortable="true"/>
              <a:column width="60" caption="Servings" type="int" name="servings" sortable="true"/>
              <a:column width="100" caption="Preparation time" type="int" name="preparationTime" sortable="true"/>
              <a:column width="40" caption="Rating" type="int" name="rating" sortable="true"/>
              <a:column width="160" caption="Date modified" type="date" name="modified" sortable="true"/>
            </a:listheader>
          </a:listview>
        </a:pane>
      </a:splitter>
    </a:box>
  </a:wbody>

</a:window>

The folder tree widget and the list view have been given an ID for them to become easily accessible from our scripts. The "method" attribute is the XML-RPC method to call whenever the user expands a tree node. Notice that the interface includes a JavaScript file with a "script" node right after the window's opening tag. Thus, create an empty JavaScript file named "recipemanager.js" inside the application folder.

Let's start by adding some event handlers.

... <a:toolbar width="100" height="100">

  <a:tbbutton caption="Create recipe folder" width="120"

    onclick="recipemanager.createItem">

    ...
  </a:tbbutton>
  <a:tbbutton caption="Create recipe" width="80"

    onclick="recipemanager.createItem">

    ...
  </a:tbbutton>
  <a:tbsep />
  <a:tbbutton caption="Refresh" width="60"

    onclick="recipemanager.refresh_onclick" />

</a:toolbar> ... <a:listview id="list" multiple="true" width="100" height="100"

  onload="recipemanager.loadRecipes">

  ...

Insert the following functions inside the empty "recipemanager.js" file:

function recipemanager() {}

recipemanager.createItem = function(evt, w) {

  var oWin = w.getParentByType(Window);
  var oTree = oWin.getWidgetById('tree');

  var sCC = w.attributes.cc;

  var id = oTree.getSelection().getId();

  oWin.showWindow(id + '?cmd=new&cc=' + sCC,
    function(dlg) {
      dlg.attachEvent("onclose", recipemanager.dialogClose);
    }
  );

}

recipemanager.dialogClose = function(dlg) {

  if (dlg.buttonIndex == 0) {
    recipemanager.refreshList(dlg.opener);
  }

}

recipemanager.refresh_onclick = function(evt, w) {

  recipemanager.loadRecipes(w);

}

recipemanager.loadRecipes = function(w) {

  var appWin = w.getParentByType(Window);
  recipemanager.refreshList(appWin);

}

recipemanager.refreshList = function(appWin) {

  var oTree = appWin.getWidgetById('tree');
  var id = oTree.getSelection().getId();
  var listView = appWin.getWidgetById('list');
  var sOql = "select id, displayName, servings, preparationTime, rating, " +
             "modified from '" + id + "' where contentclass = " +
             "'org.innoscript.recipemanager.schema.Recipe' order by displayName asc";

  var xmlrpc = new XMLRPCRequest?(QuiX?.root);
  xmlrpc.oncomplete = recipemanager.updateList;
  xmlrpc.callback_info = listView;

  xmlrpc.callmethod('executeOqlCommand', sOql);

}

recipemanager.updateList = function(req) {

  req.callback_info.dataSet = req.response;
  req.callback_info.refresh();

}

The "recipemanager.createItem" handler displays the appropriate form based on the type of the object selected by the user. This is detected by the "cc" custom attribute assigned to the toolbar buttons using the "a:prop" nodes. The location of the new object is determined by the current tree selection. The "showWindow" method loads an XML UI definition for a new window or dialog from a specified URL, and opens it as a child window. The second argument of this method is a function called when the interface is loaded. The first argument of this function is the dialog created. In this event, the root widget - the form dialog - will be added to the child windows of our application's main window.

The "recipemanager.loadrecipes" handler is called once when the list view is loaded. This handler loads the recipes from the selected container and displays them in the list view. The "onload" event handler, unlike the other events, does not accept the two common event handler arguments, the event object and the widget, but instead accepts only the widget that fires the event. The "getParentByType" QuiX? widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The "Window" class is defined inside the "quix/windows.js" QuiX module.

The "recipemanager.refreshList" function executes the OQL query that returns the recipes contained inside the selected tree container. Inside this function we send a new XMLRPC request to the root folder. The "oncomplete" attribute of the request is the callback function to call when the query has completed. This function is always called having the request object as the first argument. The "callback_info" attribute is a placeholder for anything we would like to access inside the callback function. In this case, the "callback_info" is a reference to the list view widget.

Finally, the "recipemanager.updateList" callback function updates the "dataSet" attribute of the list view and then refreshes it. The "dataSet" attribute is an array of arbitrary objects. Such an array is directly returned from the XMLRPC call.

Afterwards, we must synchronize the tree with the list view. This means that for each new tree selection we should update the list view accordingly. This is accomplished by adding the following event handler:

... <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4"

  onselect="recipemanager.loadRecipes">

  ...

</a:foldertree> ...

Next, we implement the search functionality. We start by adding a new "onclick" event handler on the search button:

... <a:button top="220" left="center" width="60" height="28" caption="Search"

  onclick="recipemanager.search" />

...

Add the following function inside the "recipemanager.js" file:

recipemanager.search = function(evt, w) {

  var displayName = w.parent.getWidgetById('title').getValue();
  var preparationTime = w.parent.getWidgetById('preparationTime').getValue();
  var rating = w.parent.getWidgetById('rating').getValue
  var ingredients = w.parent.getWidgetById('ingredients').getValue();
  var sOql = "select id, displayName, servings, preparationTime, rating, " +

             "modified from deep('/Recipes')";

  var listView = w.getParentByType(Window).getWidgetById('list');
  var conditions = ["contentclass='schemas.org.innoscript.recipemanager.Recipe'"];
  if (displayName!='') {
    conditions.push("'" + displayName + "' in displayName");
  }
  if (preparationTime!='') {
    conditions.push("preparationTime < " + preparationTime);
  }
  if (rating>0) {
    conditions.push("rating > " + rating);
  }
  if (ingredients!='') {
    var arrIng = ingredients.split(',');
    for (var i=0; i<arrIng.length; i++) {
      conditions.push("'" + arrIng[i] + "' in ingredients");
    }
  }
  if (conditions.length > 0) {
    sOql += ' where ' + conditions.join(' and ');
    var xmlrpc = new XMLRPCRequest?(QuiX?.root);
    xmlrpc.oncomplete = recipemanager.updateList;
    xmlrpc.callback_info = listView;
    xmlrpc.callmethod('executeOqlCommand', sOql);
  }

}

The above function forms the OQL query according to the criteria set by the user on the search form. Notice that we search all the recipes, by using the "deep" operator at the select scope. Also when the user double clicks on the list view, the selected recipe dialog should open:

<a:listview multiple="true" width="100" height="100" id="list"

  onload="recipemanager.loadRecipes"

  ondblclick="recipemanager.loadItem">

The following event handler should be added to the script of the application:

recipemanager.loadItem = function(evt, w, recipe) {

  var oWin = w.getParentByType(Window);
  oWin.showWindow(recipe.id + "?cmd=properties",
    function(dlg) {
      dlg.attachEvent("onclose", recipemanager.dialogClose);
    }
  );

}

This handler opens the recipe form when a recipe item is double clicked on the list. It also attaches an "onclose" handler to the recipe form. In case of the recipe being updated this handler reloads the list items.

The final enhancement is the addition of a context menu. Open the application object and add the following lines to the interface definition:

<a:pane length="-1">

  <a:contextmenu onshow="recipemanager.contextmenu_onshow">
    <a:menuoption caption="Open" onclick="recipemanager.openRecipe" />
    <a:menuoption caption="Delete" onclick="recipemanager.deleteRecipe" />
  </a:contextmenu>

  <a:listview width="100" height="100" id="list"
    onload="recipemanager.loadRecipes" ondblclick="recipemanager.loadItem">
    ...
  </a:listview>

</a:pane>

Add the following handlers to the application’s script:

recipemanager.contextmenu_onshow = function(menu) {

  var oList = menu.owner.getWidgetById('list');

  menu.options[0].disabled = (oList.selection.length == 0); //open
  menu.options[1].disabled = (oList.selection.length == 0); //properties

recipemanager.openRecipe = function(evt, w) {

  var oList = w.parent.owner.getWidgetById('list');
  var oWin = oList.getParentByType(Window);
  var selectedRecipe = oList.getSelection();
  oWin.showWindow(selectedRecipe.id + "?cmd=properties",
    function(dlg) {
      dlg.attachEvent("onclose", recipemanager.dialogClose);
    }
  );

}

recipemanager.deleteRecipe = function(evt, w) {

  var oList = w.parent.owner.getWidgetById('list');
  var selectedRecipe = oList.getSelection();
  var desktop = document.desktop;
  var _deleteItem = function(evt, w) {
    var oMsgBox = w.getParentByType(Dialog);
    var xmlrpc = new XMLRPCRequest?(QuiX?.root + selectedRecipe.id);
    xmlrpc.oncomplete = function(req) {
      oMsgBox.close();
      recipemanager.loadRecipes(oList);
    }
    xmlrpc.onerror = function(req) { oMsgBox.close(); }
    xmlrpc.callmethod('delete');
  }

  desktop.msgbox(w.getCaption(),

    "Are you sure you want to delete this recipe?",
    [
      [desktop.attributes['YES'], 60, _deleteItem],
      [desktop.attributes['NO'], 60]
    ],
    'desktop/images/messagebox_warning.gif', 'center', 'center', 260, 112);

}

The first event handler is called whenever the context menu is displayed. The parent widget of every context menu is the desktop. Thus, there must be a way to get the menu’s enclosing widget. The enclosing widget is accessible through the "owner" menu property.

The "desktop.msgbox" is used for displaying message boxes. The arguments accepted by this method are:

1. The title of the message box.
2. The message displayed in the message box.
3. An array of the buttons. Each button is also an array of three elements. The first element is the caption of the button, the second is the width of the button, and the third is the function to call once the button is clicked. If omitted the button closes the message box.
4. The image displayed inside the message box.
5. The x-coordinate of the message box.
6. The y-coordinate of the message box.
7. The width of the message box.
8. The height of the message box.

Next, log off and log on again. Launch the recipe manager application. If you see the following window, then congratulations, you have just created your first Porcupine application!

6. Packaging your application

Using the "pakager" utility we will consolidate all of the application’s pieces into a single distributable file. This procedure requires at least one package definition file. Create a new folder named "PKG" inside the porcupine installation directory. Inside this folder create a new file named "recipemanager.ini". Edit the contents of this file and add the following sections:

[package] name=RecipeManager? version=0.0.4

The first section of the package definition file has information about the package (its name and its version). Please notice that the name of the package and the value of the name attribute of the package node in the "store.xml" configuration file must be identical.

[files]

The second section contains the relative paths to any files that need to be included in the package. Leave this section blank.

[dirs]

This section adds directories to the package.

[pubdir] 1=recipemanager

The fourth section contains the published directories (usually containing external JavaScript files and images) that are required by the application. In this case, we published the "org/innoscript/recipemanager" directory. This directory also contains all of our applications files. So, by including this section, the package will contain all the files that need to be distributed.

[items] application=[Put here the ID of the Recipe Manager application] recipes_folder=[Put here the ID of the "/Recipes" folder] recipe_categories_folder=[Put here the ID of the "/Categories/Recipe categories" folder]

In this section we include all the Porcupine objects to export in the package, including the application object itself. Replace the highlighted portions with the object IDs printed on their properties dialog.

[scripts] postinstall=PKG/postinstall.py uninstall=PKG/uninstall.py

The "scripts" section contains Python script files included in the package. The "postinstall" executes immediately after the installation finishes. The "uninstall" script executes when the application is uninstalled.

Let’s see the contents of these scripts. Create a new Python script file inside the “PKG” directory named "postinstall.py". Open the file and add the following lines:

1. RecipeManager? post installation script

from porcupine.administration import codegen ce = codegen.DatatypeEditor?('org.innoscript.desktop.schema.properties.CategoryObjects?')

ce.relCc.append('org.innoscript.recipemanager.schema.Recipe')

ce.commitChanges()

The "codegen" module provides an essential API for runtime manipulation of the Porcupine objects and data types. This script modifies an existing data type (the "CategoryObjects?" class). To be precise, it adds the "org.innoscript.recipemanager.schema.Recipe" content class to the list of types that can be categorized (i.e. to the "relCc" class attribute of the data type). Similarly, inside the "PKG" folder create a new Python script named "uninstall.py". Open the file and add the following lines:

1. RecipeManager? uninstallation script

from porcupine.administration import codegen ce = codegen.DatatypeEditor?('org.innoscript.desktop.schema.properties.CategoryObjects?')

ce.relCc.remove('org.innoscript.recipemanager.schema.Recipe')

ce.commitChanges()

The Porcupine package file (RecipeManager-0.0.3.ppf) is created inside the Porcupine installation directory. The application can be installed on another Porcupine installation using the following command:

python pakager.py –i –p RecipeManager-0.0.3.ppf

version=0.0.3

The code sections that begin with three dots ("...") contain existing code, and they are mainly

                            <a:prop name="RelatedCC?" value="org.innoscript.desktop.schema.common.Category"/>

<a:dialog xmlns:a="http://www.innoscript.org/quix" title="%(TITLE)s" img="%(ICON)s" close="true" width="480" height="380" left="30" top="10">

        <a:form action="%(URI)s" method="%(METHOD)s" padding="4,4,4,4">

            %(HIDDEN)s
            <a:label caption="Recipe name:"/>
            <a:field left="80" width="380" name="displayName"
              value="%(DISPLAYNAME)s" />
            <a:label caption="Description:" top="25" />
            <a:field left="80" top="24" width="380" name="description"
              value="%(DESCRIPTION)s" />
            <a:hr top="50" width="100" />
            <a:label top="58" caption="Preparation time (min):" />
            <a:spinbutton name="preparationTime" top="55" left="110" width="50" 
              max="240" value="%(PREPARATION_TIME)d" editable="true" />
            <a:label top="58" left="200" caption="Servings:" />
            <a:spinbutton name="servings" top="55" left="250" width="40" max="12"
              editable="true" value="%(SERVINGS)d" />
            <a:label top="58" left="320" caption="Rating:" />
            <a:spinbutton name="rating" top="55" left="360" width="40" max="10"
              editable="true" value="%(RATING)d" />
            <a:tabpane top="90" width="100" height="220">
                <a:tab caption="Ingredients">
                    <a:field type="textarea" name="ingredients" width="100"
                      height="100">%(INGREDIENTS)s</a:field>
                </a:tab>
                <a:tab caption="Instructions">
                    <a:field type="textarea" name="instructions" width="100"
                      height="100">%(INSTRUCTIONS)s</a:field>
                </a:tab>
                <a:tab caption="Categories">
                    <a:box width="100" height="100" orientation="v">
                        <a:selectlist name="categories" multiple="true" posts="all" height="-1">
                            <a:prop name="SelectFrom?" value="Categories/Recipe categories"></a:prop>
                            <a:prop name="RelatedCC?" value="schemas.org.innoscript.common.Category"/>
                            %(CATEGORIES)s
                        </a:selectlist>
                        <a:rect height="24">
                            <a:flatbutton width="70" height="22" caption="Add"

                              onclick="generic.selectItems"></a:flatbutton>

                            <a:flatbutton left="80" width="70" height="22" caption="Remove"

                              onclick="generic.removeSelectedItems"></a:flatbutton>

                        </a:rect>
                    </a:box>
                </a:tab>
            </a:tabpane>
        </a:form>

</a:dialog>

    'desktop/images/messagebox_warning.gif', 'center', 'center', 260, 112);

  desktop.msgbox(w.getCaption(),

        if (sCC=='org.innoscript.recipemanager.schema.Recipe')

             "'org.innoscript.recipemanager.schema.Recipe' order by displayName asc";

      oRecipe = schema.Recipe()

    client="(MSIE [6-7])|(Mozilla/5.0.+rv:1.[7-9])"

    client="(MSIE [6-7])|(Mozilla/5.0.+rv:1.[7-9])"

    client="(MSIE [6-7])|(Mozilla/5.0.+rv:1.[7-9])"

    <a:box width="100%" height="100%" orientation="v" spacing="0">

                img="desktop/images/folder.gif" caption="Recipes"/>

The "categories" attribute is of type "RelatorN" since each recipe can be attributed to more than one category (French cuisine, desert etc.). For reasons of simplicity, we will not create a new content class for the categorization of the recipes. Instead, we will use the existing "Category" content class.

Create a new folder named "recipemanager" inside the "org/innoscript" folder. Add an empty "__init__.py" file to make it a Python package. Inside this folder create a new python script named "schema.py". This file will host our custom content classes.

Open the blank "schema.py" with your favourite Pyhton editor. First, we need to import the primary Porcupine content classes and the primary data types:

Next, we create the recipes' container content class:

"systemObjects.Container" class). The "containment" class attribute is a tuple of strings, containing all the types of the Porcupine objects that this container type can accept. In this case, the specified container can either accept new containers of the same type or new recipes. It is worth mentioning that the special class attribute "__slots__" should not be omitted from any custom content class or data type, since instances of such types consume considerably less memory.

The "categories" attribute is of type "RelatorN" since each recipe can be attributed to more than one category (French cuisine, desert etc.). For reasons of simplicity, we will not create a new content class for the categorization of the recipes. Instead, we will use the existing "[[http://www.innoscript.org/api/org.innoscript.desktop.schema.common.Category-class.html | Category" content class.

The "Categories" data type class is already defined; it is used for the categorization of the

In order to define the relation both ways, we have to somehow add the "Recipe" object to the list of objects that can be categorized. This is accomplished by editing the "properties.py" file inside the "org/innoscript/desktop/schema" folder. The highlighted line should be added:

Having defined all of our required data types, we proceed to the "Recipe" content class definition:

The "__props__" class attribute is a special attribute used by the framework. It should be defined only in each new content class that has additional data type attributes. This attribute is a tuple of strings containing the names of all such attributes, including those of the super classes.

The name of the "categories" attribute is obligatory. This is because we have a two-way many-to-many relationship between the "Recipe" and "Category" objects. To clarify this, we need to examine the "Category" content type defined in the "common.py" file.

The objects’ references that belong in a specified category are stored inside the "category_objects" attribute. The data type of this attribute is the "CategoryObjects?" class. It is not considered a good practice to assign the same name to the attribute name and the data type class.

should have an attribute named "categories". If the "categories"attribute is a subclass of "Relator1", then we have established an one-to-many relationship. On the other hand, if the "categories" attribute is a subclass of "RelatorN", then the relationship is considered to be many-to-many.

temporarily edit the containment of the "RootFolder" content class, located inside "common.py".

list view and select "New". Notice that the "RecipeContainer" type is added to the list of the

Select the "RecipeContainer" type and create a new object named "Recipes". If you double click on

"RecipeContainer" content class. Hence, we have to edit the "store.xml" file inside the "conf"

inside a new package node. Locate the "packages" node at the top of the afore-mentioned file and

As you can see, the first registration takes care of the XMLRPC methods exposed by the "RecipeContainer" content type. For the time being, we need no special behavior; the "RecipeContainer" type exposes the same methods as any other container. Also, notice that the client parameter is set to "vcXMLRPC". This should be true for every XMLRPC servlet we publish.

object inside a "RecipeContainer" folder. Because the "org.innoscript.desktop.ui.Frm_AutoNew" is a

Finally, we also need to create the recipe categories container. Double click the "Categories" folder and create a new category folder named "Recipe categories". Please note that in case your session

Before restarting the server, you can safely delete the "RecipeContainer" entry from the containment of the "RootFolder" content type.

The current implementation of the "org.innoscript.desktop.ui.Frm_AutoNew" servlet has some limitations that force us to design a new form for the "Recipe" content type. Looking at the form

It is recommended to maintain the QuiX servlets and the XMLRPC servlets in separate Python files named "ui.py" and "XMLRPC.py" respectively.

Consequently, we create and edit a new Python file named "ui.py" inside the "recipemanager" module. First, we import the "XULServlet" class, the server’s desktop "ui" module and the content classes’

"RecipeContainer" type accepts both new recipe containers and recipes. When creating a new recipe container, the splitter must get the XML definition output from the "Frm_Auto" servlet, whereas

In order for the servlet to execute successfully, a file named "ui.RecipeContainerSplitter.quix" must

"params" attribute of the servlet. Before proceeding to the recipe form itself, we must modify the "store.xml" configuration file by

The first modification assigns the "RecipeContainerSplitter" as the servlet to be executed when the browser GETs? on a "RecipeContainer" object with the "cmd" query parameter set to "new". The second modification is simply a new servlet registration for the "Recipe" type, which renders the recipe form whenever a compatible browser GETs? on an object of this type with the parameter set to "properties". Now it’s time to write the "RecipeForm" servlet:

display the properties of an existing recipe. In the first case, the type of the object "called" is the "RecipeContainer" unlike the second case, in which the type of the object is the "Recipe" type.

The QuiX XML definition of the form is a new file named "ui.RecipeForm.quix" inside the "org/innoscript/recipemanager" folder.

Initially, this form imports two QuiX desktop JavaScript files. The first script is the one used by the forms generated automatically by the "Frm_Auto" servlet. The function we reuse from this script (org/innoscript/desktop/ui.Frm_Auto.js) is the "autoform.submit" function. This function simply submits the first QuiX form found inside the current dialog.

The "submit" method of a QuiX form takes one argument; the function to call asynchronously, once the browser has the submission response. In this case the dialog has a custom attribute which is actually the function to call for refreshing the opener’s list view. After calling this function, the dialog is closed.

The form's "action" parameter is the URL where the form data get posted. This is usually the HTTP address of a Porcupine object whose type has an XMLRPC servlet registered in the "store.xml" configuration file (visit http://wiki.innoscript.org/index.php/Articles/RequestProcessingPipeline to see how each object is accessible over HTTP).

The form's "method" parameter is the name of the method of the XMLRPC servlet to call. Since this form is used for both creating and editing recipes the name of the method is diferrent in each aspect. When creating a new recipe we call the "create" method of the "org.innoscript.desktop.XMLRPC.ContainerGeneric" XMLRPC servlet.

The "data" argument contains the form data. It is a Python dictionary containing the field names and values.

This method requires an additional field posted named "CC". This field contains the type of the object that is going to be appended to the calling container. Each XML-RPC method should always return a value. This method simply returns "True" only if the object is created and appended to the container successfully. This way, the browser knows that the request has been succefully completed.

Also notice, that the "ContainerGeneric" servlet is a subclass of the "ItemGeneric" servlet. Besides the container specific methods defined, a container can also be updated, copied or renamed just like any other Porcupine object.

Respectively, when editing an existing recipe, we call the "update" method of the "org.innoscript.desktop.XMLRPC.ItemGeneric" XMLRPC servlet.

The recipe form also includes the "org/innoscript/desktop/generic.js" JavaScript file. From this file we reuse two JavaScript functions named "generic.selectItems" and "generic.removeSelectedItems".

The "generic.selectItems" function displays the object select dialog by calling the "generic.selectObjects" function. The auto-generated form servlet uses this function for "ReferenceN" or "RelatorN" data types. The arguments given to the "generic.selectObjects" function are:

• select_func: the function to call when the user presses the "Select" button
• startFrom: The ID of the root node of the tree (in this case, the "SelectFrom" custom attribute of the select list on the recipe form)

• multiple: "true" if multiple selection is allowed, else "false"

Before creating our application object we must publish the "org/innoscript/recipemanager" direcotry. This directory will contain our applications XML UI definition and the required JavaScript functions. Edit the "conf/pubdir.xml" configuration file by adding the highlighted node:

Each published directory must contain a file called "config.xml". This file keeps track of the files accesible over HTTP. This file should be:

"Administrative Tools/Applications" folder. Inside the "Launch URL" input box type "recipemanager/recipemanager.quix". Press the "Create" button to create the application object.

Next, create a new text file named "recipemanager.quix" inside the "recipemanager" folder we just published.

The folder tree widget and the list view have been given an ID for them to become easily accessible from our scripts. The "method" attribute is the XML-RPC method to call whenever the user expands a tree node. Notice that the interface includes a JavaScript file with a "script" node right after the window's opening tag. Thus, create an empty JavaScript file named "recipemanager.js" inside the application folder.

Insert the following functions inside the empty "recipemanager.js" file:

The "recipemanager.createItem" handler displays the appropriate form based on the type of the object selected by the user. This is detected by the "cc" custom attribute assigned to the toolbar buttons using the "a:prop" nodes. The location of the new object is determined by the current tree selection. The "parseFromUrl" QuiX widget method loads an XML UI definition from a specified URL, inside the referring widget. The second argument of this method is a function called when the interface is loaded. The first argument of this function is the root widget created. In this event, the root widget - the form dialog - will be appended to the desktop ("document.desktop" is the desktop widget).

The "recipemanager.loadrecipes" handler is called once when the list view is loaded. This handler loads the recipes from the selected container and displays them in the list view. The "onload" event handler, unlike the other events, does not accept the two common event handler arguments, the event object and the widget, but instead accepts only the widget that fires the event. The "getParentByType" QuiX? widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The "Window" class is defined inside the "quix/windows.js" QuiX module.

The "recipemanager.refreshList" function executes the OQL query that returns the recipes

the root folder. The "oncomplete" attribute of the request is the callback function to call when the query has completed. This function is always called having the request object as the first argument. The "callback_info" attribute is a placeholder for anything we would like to access inside the callback function. In this case, the "callback_info" is a reference to the list view widget.

Finally, the "recipemanager.updateList" callback function updates the "dataSet" attribute of the list view and then refreshes it. The "dataSet" attribute is an array of arbitrary objects. Such an array is directly returned from the XMLRPC call.

Next, we implement the search functionality. We start by adding a new "onclick" event handler on the search button:

Add the following function inside the "recipemanager.js" file:

The above function forms the OQL query according to the criteria set by the user on the search form. Notice that we search all the recipes, by using the "deep" operator at the select scope.

This event handler reuses the "generic.showObjectProperties" function. The function given as an argument is called when the user updates the item and the list view of the opener must be updated.

The first event handler is called whenever the context menu is displayed. The parent widget of every context menu is the desktop. Thus, there must be a way to get the menu’s enclosing widget. The enclosing widget is accessible through the "owner" menu property.

The "desktop.msgbox" is used for displaying message boxes. The arguments accepted by this

Using the "pakager" utility we will consolidate all of the application’s pieces into a single distributable file. This procedure requires at least one package definition file. Create a new folder named "PKG" inside the porcupine installation directory. Inside this folder create a new file named "recipemanager.ini". Edit the contents of this file and add the following sections:

The first section of the package definition file has information about the package (its name and its version). Please notice that the name of the package and the value of the name attribute of the package node in the "store.xml" configuration file must be identical.

The fourth section contains the published directories (usually containing external JavaScript files and images) that are required by the application. In this case, we published the "org/innoscript/recipemanager" directory. This directory also contains all of our applications files. So, by including this section, the package will contain all the files that need to be distributed.

recipes_folder=[Put here the ID of the "/Recipes" folder] recipe_categories_folder=[Put here the ID of the "/Categories/Recipe categories" folder]

application object itself. Replace the highlighted portions with the object IDs printed on their properties dialog.

The "scripts" section contains Python script files included in the package. The "postinstall" executes immediately after the installation finishes. The "uninstall" script executes when the application is uninstalled.

Let’s see the contents of these scripts. Create a new Python script file inside the “PKG” directory named "postinstall.py". Open the file and add the following lines:

The "codegen" module provides an essential API for runtime manipulation of the Porcupine objects and data types. This script modifies an existing data type (the "CategoryObjects?" class). To be precise, it adds the "org.innoscript.recipemanager.schema.Recipe" content class to the list of types that can be categorized (i.e. to the "relCc" class attribute of the data type). Similarly, inside the "PKG" folder create a new Python script named "uninstall.py". Open the file and add the following lines:

Before proceeding to the creation of the package, stop the Porcupine service. Afterwards, run the "pakager" utility as follows:

        <a:tbbutton caption="Create recipe folder" width="120">

        <a:tbbutton caption="Create recipe" width="80">

        <a:tbbutton caption="Refresh" width="60"/>

              <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4">
                <a:treenode id="[Put here the ID of the Recipes Porcupine folder]" haschildren="true"

              <a:button top="220" left="center" width="60" height="28" caption="Search"/>

          <a:listview width="100%" height="100%" id="list">

Notice that the interface includes a JavaScript file with a "script" node right after the window's opening tag. Thus, create an empty JavaScript file named "recipemanager.js" inside the application folder.

Insert the following functions inside the empty ""recipemanager.js"" file:

The “recipemanager.loadrecipes” handler is called once when the list view is loaded. This handler loads the recipes from the selected container and displays them in the list view. The “onload” event handler, unlike the other events, does not accept the two common event handler arguments, the event object and the widget, but instead accepts only the widget that fires the event. The “getParentByType” QuiX? widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The “Window” class is defined inside the “quix/windows.js” QuiX? module.

Finally, the “recipemanager.updateList” callback function updates the “dataSet” attribute of the list view and then refreshes it. The “dataSet” attribute is an array of arbitrary objects. Such an array is directly returned from the XMLRPC call.

Add the following function inside the “recipemanager.js" file:

distributable file. This procedure requires at least one package definition file. Create a new folder named “PKG” inside the porcupine installation directory. Inside this folder create a new file named “recipemanager.ini”. Edit the contents of this file and add the following sections:

The second section contains the relative paths to any files that need to be included in the package. Leave this section blank.

This section adds directories to the package.

1=recipemanager

The fourth section contains the published directories (usually containing external JavaScript files and images) that are required by the application. In this case, we published the "org/innoscript/recipemanager" directory. This directory also contains all of our applications files. So, by including this section the package will contain all the files that need to be destributed.

ce = codegen.DatatypeEditor?('org.innoscript.desktop.schema.properties.CategoryObjects?')

ce.relCc.append('org.innoscript.recipemanager.schema.Recipe')

ce = codegen.DatatypeEditor?('org.innoscript.desktop.schema.properties.CategoryObjects?')

ce.relCc.remove('org.innoscript.recipemanager.schema.Recipe')

Press the “Create” button to create the application object. Next, create a new text file named "recipemanager.quix" inside the "recipemanager" folder we just published.

<?xml version="1.0" encoding="UTF-8"?> <a:window xmlns:a="http://www.innoscript.org/quix" title="Recipe manager" resizable="true" close="true" minimize="true" maximize="true" img="" width="640" height="480" left="center" top="center">

  <a:script name="Recipe manager Script" src="recipemanager/recipemanager.js"/>
  <a:wbody>
    <a:box width="100%" height="100%" orientation="h">
      <a:toolbar height="28">
        <a:tbbutton caption="Create recipe folder" width="120" onclick="recipemanager.createItem">
          <a:prop name="cc" value="org.innoscript.recipemanager.schema.RecipeContainer?"/>
        </a:tbbutton>
        <a:tbbutton caption="Create recipe" width="80" onclick="recipemanager.createItem">
          <a:prop name="cc" value="org.innoscript.recipemanager.schema.Recipe"/>
        </a:tbbutton>
        <a:tbsep/>
        <a:tbbutton caption="Refresh" width="60" onclick="recipemanager.refresh_onclick"/>
      </a:toolbar>
      <a:splitter height="-1" orientation="v" interactive="true">
        <a:pane length="200">
          <a:outlookbar width="100%" height="100%">
            <a:tool caption="Recipes">

              <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4" onselect="recipemanager.loadRecipes">
                <a:treenode id="[Put here the ID of the Recipes Porcupine Object]" haschildren="true"
                img="images/folder.gif" caption="Recipes"/>

              </a:foldertree>
            </a:tool>
            <a:tool caption="Search" bgcolor="gray">
              <a:label caption="Recipe title contains:"/>
              <a:field id="title" left="5" top="20" width="160"/>

              <a:label top="50" caption="Preparation time is less than"/>
              <a:field id="preparationTime" left="5" top="70" width="30"/>
              <a:label top="72" left="40" caption="min."/>

              <a:label top="100" caption="The recipe's rating is greater than"/>
              <a:spinbutton top="120" left="5" width="40" max="10" value="0" id="rating"/>

              <a:label top="150" caption="Recipe ingredients contain:"/>
              <a:field id="ingredients" top="170" left="5" width="160"/>
              <a:label top="190" caption="(comma separated list)" style="font-style:italic"/>

              <a:button top="220" left="center" width="60" height="28" caption="Search" onclick="recipemanager.search"/>
            </a:tool>
          </a:outlookbar>
        </a:pane>
        <a:pane length="-1">
          <a:contextmenu onshow="recipemanager.contextmenu_onshow">
            <a:menuoption caption="Open" onclick="recipemanager.openRecipe"/>
            <a:menuoption caption="Delete" onclick="recipemanager.deleteRecipe"/>
          </a:contextmenu>

          <a:listview width="100%" height="100%" id="list" onload="recipemanager.loadRecipes"
          ondblclick="recipemanager.loadItem">

            <a:listheader>
              <a:column width="140" caption="Recipe title" name="displayName" bgcolor="#EFEFEF" sortable="true"/>
              <a:column width="60" caption="Servings" type="int" name="servings" sortable="true"/>
              <a:column width="100" caption="Preparation time" type="int" name="preparationTime" sortable="true"/>
              <a:column width="40" caption="Rating" type="int" name="rating" sortable="true"/>
              <a:column width="160" caption="Date modified" type="date" name="modified" sortable="true"/>
            </a:listheader>
          </a:listview>
        </a:pane>
      </a:splitter>
    </a:box>
  </a:wbody>

</a:window>

Therefore, we have to create a new recipe form using a new QuiX servlet. We start by creating the

It is recommended to maintain the QuiX servlets and the XML-RPC servlets in separate Python files

Remember that every QuiX servlet (an instance of the XULServlet class) must always be accompanied with a quix file in the same directory. This file usually contains the XML definition of the interface,

The QuiX XML definition of the form is a new file named “ui.RecipeForm.quix” inside the

Initially, this form imports two QuiX desktop JavaScript files. The first script is the one used by the forms generated automatically by the “Frm_Auto” servlet. The function we reuse from this script (org/innoscript/desktop/ui.Frm_Auto.js) is the “autoform.submit” function. This function simply submits the first QuiX form found inside the current dialog.

The recipe form also includes the “org/innoscript/desktop/generic.js” JavaScript file. From this file we reuse two JavaScript functions named “generic.selectItems” and “generic.removeSelectedItems”.

The “generic.selectItems” function displays the object select dialog by calling the “generic.selectObjects” function. The auto-generated form servlet uses this function for “ReferenceN” or “RelatorN” data types. The arguments given to the “generic.selectObjects” function are:

Apart from the custom forms and the custom content types, we will also need a custom UI for our application tailored

Before creating our application object we must publish the "org/innoscript/recipemanager" direcotry. This directory will contain our applications XML UI definition and the required JavaScript functions. Edit the "conf/pubdir.xml" configuration file by adding the highlighted node:

<config>

	<dirs>
		<dir name="__quix" path="quix"/>
		<dir name="desktop" path="org/innoscript/desktop"/>
		<dir name="hypersearch" path="org/innoscript/hypersearch"/>
		<dir name="usermgmnt" path="org/innoscript/usermgmnt"/>
		<dir name="queryperformer" path="org/innoscript/queryperformer"/>

		<dir name="recipemanager" path="org/innoscript/recipemanager"/>

	</dirs>

</config>

Each published directory must contain a file called "config.xml". This file keeps track of the files accesible over HTTP. This file should be:

<config>

	<context path="recipemanager.quix"
			 method="GET"
			 client=".*"
			 lang=".*"
			 action="recipemanager.quix"/>
	<context path="recipemanager.js"
			 method="GET"
			 client=".*"
			 lang=".*"
			 action="recipemanager.js"/>

</config>

To create a new application, login to Porcupine as an administrator and navigate to the “Administrative Tools/Applications” folder. Inside the "Launch URL" input box type "recipemanager/recipemanager.quix". Create a new text file named "recipemanager.quix" inside the "recipemanager" folder we just published. Do not forget to replace the tree node’s ID with the ID of the “Recipes” folder given by the system. The contents of this file are:

<a:splitter width="100" height="100" orientation="h" spacing="0">

  <a:pane length="28">
    <a:toolbar width="100" height="100">
      <a:tbbutton caption="Create recipe folder" width="120">
        <a:prop name="cc" value="schemas.org.innoscript.recipemanager.RecipeContainer?"/>
      </a:tbbutton>
      <a:tbbutton caption="Create recipe" width="80">
        <a:prop name="cc" value="schemas.org.innoscript.recipemanager.Recipe"/>
      </a:tbbutton>
      <a:tbsep/>
      <a:tbbutton caption="Refresh" width="60" />
    </a:toolbar>

  <a:pane length="-1" bgcolor="white">
    <a:splitter width="100" height="100" orientation="v"
      interactive="true">
      <a:pane length="200">
        <a:outlookbar width="100" height="100">
          <a:tool caption="Recipes">

            <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4">
              <a:treenode id="[Put here the ID of the Recipes folder]" haschildren="true"

                img="images/folder.gif" caption="Recipes">
              </a:treenode>
            </a:foldertree>
          </a:tool>
          <a:tool caption="Search" bgcolor="gray">
            <a:label caption="Recipe title contains:" />
            <a:field id="title" left="5" top="20" width="160" />
            <a:label top="50" caption="Preparation time is less than" />
            <a:field id="preparationTime" left="5" top="70" width="30" />
            <a:label top="72" left="40" caption="min." />
            <a:label top="100" caption="The recipe's rating is greater than" />
            <a:spinbutton top="120" left="5" width="40" max="10" value="0"
              id="rating"/>
            <a:label top="150" caption="Recipe ingredients contain:" />
            <a:field id="ingredients" top="170" left="5" width="160" />
            <a:label top="190" caption="(comma separated list)"
              style="font-style:italic" />
            <a:button top="220" left="center" width="60" height="28"
              caption="Search" />
          </a:tool>
        </a:outlookbar>
      </a:pane>
      <a:pane length="-1">

        <a:listview id="list" width="100" height="100">

          <a:listheader>
            <a:column width="140" caption="Recipe title" name="displayName"
              bgcolor="#EFEFEF" sortable="true"></a:column>
            <a:column width="60" caption="Servings" type="int" name="servings"
              sortable="true"></a:column>
            <a:column width="100" caption="Preparation time" type="int"
              name="preparationTime" sortable="true"></a:column>
            <a:column width="40" caption="Rating" type="int" name="rating"
              sortable="true"></a:column>
            <a:column width="160" caption="Date modified" type="date"
              name="modified" sortable="true"></a:column>
          </a:listheader>
        </a:listview>
      </a:pane>
    </a:splitter>
  </a:pane>

</a:splitter>

Press the “Create” button to create the application object. The above interface contains no functionality. We have just created a “dummy” application.

The folder tree widget and the list view have been given an ID for them to become easily accessible from our scripts. The “method” attribute is the XML-RPC method to call whenever the user expands a tree node.

Let's start by adding some event handlers.

... <a:toolbar width="100" height="100">

  <a:tbbutton caption="Create recipe folder" width="120"

    onclick="recipemanager.createItem">

    ...
  </a:tbbutton>
  <a:tbbutton caption="Create recipe" width="80"

    onclick="recipemanager.createItem">

    ...
  </a:tbbutton>
  <a:tbsep />
  <a:tbbutton caption="Refresh" width="60"

    onclick="recipemanager.refresh_onclick" />

</a:toolbar> ... <a:listview id="list" multiple="true" width="100" height="100"

  onload="recipemanager.loadRecipes">

  ...

In the application's script tab insert the following code:

function recipemanager() {}

recipemanager.createItem = function(evt, w) {

  var oWin = w.getParentByType(Window);
  var oTree = oWin.getWidgetById('tree');

  var sCC = w.attributes.cc;

  document.desktop.parseFromUrl(id + '?cmd=new&cc=' + sCC,
    function(w) {
      w.attributes.refreshlist = function() {
        if (sCC=='schemas.org.innoscript.recipemanager.Recipe')
          recipemanager.refreshList(oWin);
      }
    }
  );

recipemanager.refresh_onclick = function(evt, w) {

  recipemanager.loadRecipes(w);

}

recipemanager.loadRecipes = function(w) {

  var appWin = w.getParentByType(Window);
  recipemanager.refreshList(appWin);

recipemanager.refreshList = function(appWin) {

  var oTree = appWin.getWidgetById('tree');
  var id = oTree.getSelection().getId();
  var listView = appWin.getWidgetById('list');
  var sOql = "select id, displayName, servings, preparationTime, rating, " +
             "modified from '" + id + "' where contentclass = " +
             "'schemas.org.innoscript.recipemanager.Recipe' order by displayName asc";

  var xmlrpc = new XMLRPCRequest?(QuiX?.root);
  xmlrpc.oncomplete = recipemanager.updateList;
  xmlrpc.callback_info = listView;

  xmlrpc.callmethod('executeOqlCommand', sOql);

}

recipemanager.updateList = function(req) {

  req.callback_info.dataSet = req.response;
  req.callback_info.refresh();

}

The “recipemanager.createItem” handler displays the appropriate form based on the type of the object selected by the user. This is detected by the “cc” custom attribute assigned to the toolbar buttons using the “a:prop” nodes. The location of the new object is determined by the current tree selection. The “parseFromUrl” QuiX? widget method loads an XML UI definition from a specified URL, inside the referring widget. The second argument of this method is a function called when the interface is loaded. The first argument of this function is the root widget created. In this event, the root widget - the form dialog - will be appended to the desktop (“document.desktop” is the desktop widget).

The “recipemanager.loadrecipes” handler is called once when the list view is loaded. This handler loads the recipes from the selected container and displays them in the list view. The “onload” event handler, unlike the other events, does not accept the two common event handler arguments, the event object and the widget, but instead accepts only the widget that fires the event. The “getParentByType” QuiX? widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The “Window” class is defined inside the “pubdir/__xul/windows.js” QuiX? module.

The “recipemanager.refreshList” function executes the OQL query that returns the recipes contained inside the selected tree container. Inside this function we send a new XMLRPC request to the root folder. The “oncomplete” attribute of the request is the callback function to call when the query has completed. This function is always called having the request object as the first argument. The “callback_info” attribute is a placeholder for anything we would like to access inside the callback function. In this case, the “callback_info” is a reference to the list view widget.

Finally, the “recipemanager.updateList” callback function updates the “dataSet” attribute of the list view and then refreshes it. The “dataSet” attribute is an array of arbitrary objects. Such an array is directly returned from the XML-RPC call.

Afterwards, we must synchronize the tree with the list view. This means that for each new tree selection we should update the list view accordingly. This is accomplished by adding the following event handler:

... <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4"

  onselect="recipemanager.loadRecipes">

  ...

</a:foldertree> ...

Next, we implement the search functionality. We start by adding a new “onclick” event handler on the search button:

... <a:button top="220" left="center" width="60" height="28" caption="Search"

  onclick="recipemanager.search" />

@]

...

Add the following function to the “Script” tab of the application dialog:

recipemanager.search = function(evt, w) {
  var displayName = w.parent.getWidgetById('title').getValue();
  var preparationTime = w.parent.getWidgetById('preparationTime').getValue();
  var rating = w.parent.getWidgetById('rating').getValue
  var ingredients = w.parent.getWidgetById('ingredients').getValue();
  var sOql = "select id, displayName, servings, preparationTime, rating, " +

             "modified from deep('/Recipes')";

[@

The “generic.selectItems” function displays the object select dialog by calling the “generic.selectObjects” function. The auto-generated form servlet uses this function for “ReferenceN?” or “RelatorN?” data types. The arguments given to the “generic.selectObjects” function are:

The current implementation of the “org.innoscript.desktop.ui.Frm_AutoNew” servlet has some

happening because the servlet, in its current state, ignores the numeric data types (a QuiX numeric

Python module that will host our application servlets.

module. First, we import the “XULServlet” class, the server’s desktop “ui” module and the content classes’

from org.innoscript.desktop import ui from org.innoscript.recipemanager import schema

recipe, we must register a new QuiX servlet that acts as a splitter. This is because the

    if sCC == 'org.innoscript.recipemanager.schema.RecipeContainer?':

    elif sCC == 'org.innoscript.recipemanager.schema.Recipe':

Remember that every QuiX servlet (an instance of the XULServlet class) must always be accompanied

[Name of Python file].[Name of the servlet class name].quix

In order for the servlet to execute successfully, a file named “ui.RecipeContainerSplitter.quix” must be created in the same directory. The specific servlet acts as a wrapper; the content of the quix file is

As you propably already have guessed, the server formats the contents of the quix file using the

  <reg cc="org.innoscript.recipemanager.schema.RecipeContainer?"

    action="org.innoscript.desktop.XMLRPC.ContainerGeneric?"/>
  <reg cc="org.innoscript.recipemanager.schema.RecipeContainer?"

    action="org.innoscript.recipemanager.ui.RecipeContainerSplitter?"/>
  <reg cc="org.innoscript.recipemanager.schema.Recipe$"

    action="org.innoscript.recipemanager.ui.RecipeForm?"/>

    if sCC == 'org.innoscript.recipemanager.schema.RecipeContainer?':

    elif sCC == 'org.innoscript.recipemanager.schema.Recipe':

      'URI': self.request.serverVariables['SCRIPT_NAME'] + '/' + self.item.id,

The QuiX? XML definition of the form is a new file named “ui.RecipeForm.quix” inside the “org/innoscript/recipemanager” folder.

    <a:script name="Generic Form Script" src="desktop/ui.Frm_Auto.js" />
    <a:script name="Generic Functions" src="desktop/generic.js" />

Initially, this form imports two QuiX desktop JavaScript? files. The first script is the one used by the forms generated automatically by the “Frm_Auto” servlet. The function we reuse from this script(“org/innoscript/desktop/ui.Frm_Auto.js”) is the “autoform.submit” function. This function simply submits the first QuiX form found inside the current dialog.

The “submit” method of a QuiX form takes one argument; the function to call asynchronously, once the browser has the submission response. In this case the dialog has a custom attribute which is actually the function to call for refreshing the opener’s list view. After calling this function, the dialog is closed.

this form is used for both creating and editing recipes the name of the method is diferrent in each aspect. When creating a new recipe we call the “create” method of the “org.innoscript.desktop.XMLRPC.ContainerGeneric” XML-RPC servlet.

Respectively, when editing an existing recipe, we call the “update” method of the “org.innoscript.desktop.XMLRPC.ItemGeneric” XML-RPC servlet.

The recipe form also includes the “org/innoscript/desktop/generic.js” JavaScript file. From this file we reuse two JavaScript? functions named “generic.selectItems” and “generic.removeSelectedItems”.

object inside a “RecipeContainer” folder. Because the “org.innoscript.desktop.ui.Frm_AutoNew” is a

    'org.innoscript.recipemanager.schema.RecipeContainer?',

  <reg cc="org.innoscript.recipemanager.schema.RecipeContainer?"

    action="org.innoscript.desktop.XMLRPC.ContainerGeneric?"/>

  <reg cc="org.innoscript.recipemanager.schema.RecipeContainer?"

    action="org.innoscript.desktop.ui.Frm_AutoNew"/>

Create a new folder named "recipemanager" inside the "org/innoscript'" folder. Add an empty "__init__.py" file to make it a Python package. Inside this folder create a new python script named "schema.py''". This file will host our custom content classes.

The “categories” attribute is of type “RelatorN” since each recipe can be attributed to more than one category (French cuisine, desert etc.). For reasons of simplicity, we will not create a new content class for the categorization of the recipes. Instead, we will use the existing “org.innoscript.desktop.schema.common.Category” content class.

The “Categories” data type class is already defined; it is used for the categorization of the

from org.innoscript.desktop.schema import properties

In order to define the relation both ways, we have to somehow add the “Recipe” object to the list of objects that can be categorized. This is accomplished by editing the “properties.py” file inside the “org/innoscript/desktop/schema” folder. The highlighted line should be added:

  class CategoryObjects?(RelatorN?):

      'org.innoscript.desktop.schema.common.Document',
      'org.innoscript.desktop.schema.collab.Contact',

      'org.innoscript.recipemanager.schema.Recipe',

    self.categories = properties.Categories()

    self.category_objects = properties.CategoryObjects?()@]

Now let’s take a closer look at the “CategoryObjects?” data type:

class CategoryObjects?(RelatorN?):

    'org.innoscript.desktop.schema.common.Document',
    'org.innoscript.desktop.schema.collab.Contact',
    'org.innoscript.recipemanager.schema.Recipe',

Create a new folder named "recipemanager" inside the "org/innoscript'" folder. Add an empty "__init__.py" file to make it a Python package. Inside this folder create a new python script named "schema.py''". This file will host our custom content classes. In the case of our sample application, the recipe manager, we will initially need two new content classes. The first content class is a container capable of keeping recipes and the second content class is the recipe itself. Open the blank "schema.py" with your favourite Pyhton editor. First, we need to import the primary Porcupine content classes and the primary data types:

    'org.innoscript.recipemanager.schema.RecipeContainer?',
    'org.innoscript.recipemanager.schema.Recipe'

This tutorial is valid only for Porcupine 0.0.7. We are currently in the process of updating this tutorial to comply with the new 0.0.8 release.

Download the Recipe Manager Porcupine package file

  var id = oTree.getSelection().getId();

  var id = oTree.getSelection().getId();

inside the “resources” folder. To make it a Python module, add an empty “__init__.py” file.

“resources/recipemanager” folder.

1=resources/recipemanager

    action="resources.system.XMLRPC.ContainerGeneric?"/>

    action="resources.system.ui.Frm_AutoNew"/>

object inside a “RecipeContainer” folder. Because the “resources.system.ui.Frm_AutoNew” is a

The current implementation of the “resources.system.ui.Frm_AutoNew” servlet has some

from resources.system import ui

    action="resources.system.XMLRPC.ContainerGeneric?"/>

    action="resources.recipemanager.ui.RecipeContainerSplitter?"/>

    action="resources.recipemanager.ui.RecipeForm?"/>

this form is used for both creating and editing recipes the name of the method is diferrent in each aspect. When creating a new recipe we call the “create” method of the “resources.system.XMLRPC.ContainerGeneric” XML-RPC servlet.

Respectively, when editing an existing recipe, we call the “update” method of the “resources.system.XMLRPC.ItemGeneric” XML-RPC servlet.

The form's “action” parameter is the URL where the form data get posted. This is usually the HTTP address of a Porcupine object whose type has an XML-RPC servlet registered in the “store.xml” configuration file (visit http://wiki.innoscript.org/index.php/Articles/RequestProcessingPipeline to see how each object is accessible over HTTP).

Download this tutorial in PDF format\\

Download the Recipe Manager Porcupine package file

simple recipe manager, used for storing and retrieving cooking recipes. The purpose of this tutorial is to teach you the steps required for building a Porcupine – QuiX application. The skills required to complete this tutorial are good knowledge of Python and JavaScript.

simple recipe manager, used for storing and retrieving cooking recipes. The purpose of this tutorial is to teach you the steps required for building a Porcupine – QuiX? application. The skills required to complete this tutorial are good knowledge of Python and JavaScript.

module. First, we import the “XULServlet” class, the server’s “ui” module and the content classes’

QuiX? servlet (instance of XULServlet), we should always check for browser compatibility by

module. First, we import the “XULServlet?” class, the server’s “ui” module and the content classes’

python pakager.py –i –p RecipeManager-0.0.1.ppf

<<<<<<< QuiX? servlet (instance of XULServlet), we should always check for browser compatibility by allowing this servlet to run only on the supported browsers. What this servlet actually does is to =======

>>>>>>>

Before restarting the server, you can safely delete the “RecipeContainer” entry from the containment

module. First, we import the “XULServlet” class, the server’s “ui” module and the content classes’

Remember that every QuiX? servlet (instance of the XULServlet class) must always be accompanied

python pakager.py –i –p RecipeManager-0.0.1.ppf

QuiX? servlet (instance of XULServlet), we should always check for browser compatibility by

As you can see, the first registration takes care of the XML-RPC methods exposed by the

As you can see, the first registration takes care of the XML-RPC methods exposed by the

developers (intermediate) Download this tutorial in PDF format

Download PDF

Developers (intermediate)

Download tutorial in PDF

“systemObjects.Container” class). The “containment” class attribute is a tuple of strings, containing all the types of the Porcupine objects that this container type can accept. In this case, the specified container can either accept new containers of the same type or new recipes. It is worth mentioning that the special class attribute “__slots__” should not be omitted from any custom content class or data type, since instances of such types consume considerably less memory.

(:title The Recipe Manager tutorial:)

Table of contents

1. Introduction
2. Creating the content classes
3. Creating the initial content
4. Designing a new recipe form
5. The Recipe Manager application
6. Packaging your application

1. Introduction

In this tutorial we will create a simple Porcupine application from scratch. This application is a simple recipe manager, used for storing and retrieving cooking recipes. The purpose of this tutorial is to teach you the steps required for building a Porcupine – QuiX? application. The skills required to complete this tutorial are good knowledge of Python and JavaScript?. The code sections that begin with three dots (“...”) contain existing code, and they are mainly included for explanatory purposes. All the paths referred in this tutorial are relative to the Porcupine installation folder.

2. Creating the content classes

The first step is to design your business objects. In the case of our sample application, the recipe manager, we will initially need two new content classes. The first content class is a container capable of keeping recipes and the second content class is the recipe itself. The content classes are Python classes defined inside the “schemas” package. Therefore, we create a new Python file named “recipemanager.py” inside the “schemas/org/innoscript” folder. First, we need to import the primary Porcupine content classes and the primary data types:

from porcupine import systemObjects
from porcupine import datatypes

Next, we create the recipes container:

class RecipeContainer(systemObjects.Container):
  __slots__ = ()
  containment = (
    'schemas.org.innoscript.recipemanager.RecipeContainer',
    'schemas.org.innoscript.recipemanager.Recipe'
  )

To define a new container type we need to subclass the system container (the “systemObjects.Container” class). The “containment” class attribute is a tuple of strings, containing all the types of the Porcupine objects that this container type can accept. In this case, the specified container can either accept new containers of the same type or new recipes. It is worth mentioning that the special class attribute “'_{_slots_}'” should not be omitted from any custom content class or data type, since instances of such types consume considerably less memory.

The recipe object must have the following attributes:

The “categories” attribute is of type “RelatorN” since each recipe can be attributed to more than onencategory (French cuisine, desert etc.). For reasons of simplicity, we will not create a new content class for the categorization of the recipes. Instead, we will use the existing “schemas.org.innoscript.common.Category” content class.

The “categories” data type class is already defined; it is used for the categorization of the documents. Thus, we just need to import the following module:

from schemas.org.innoscript import properties

In order to define the relation both ways, we have to somehow add the “Recipe” object to the list of objects that can be categorized. This is accomplished by editing the “properties.py” file inside the “schemas/org/innoscript” folder. The highlighted line should be added:

...
  class category_objects(RelatorN):
    ...
    relCc = (
      'schemas.org.innoscript.common.Document',
      'schemas.org.innoscript.collab.Contact',

      'schemas.org.innoscript.recipemanager.Recipe',

    )
    ...
...

By default the primary data types are not mandatory. So we must create three new data type classes which subclass the primary data types.

class Servings(datatypes.Integer):
  __slots__ = ()
  isRequired = True
class Ingredients(datatypes.Text):
  __slots__ = ()
  isRequired = True
class Instructions(datatypes.Text):
  __slots__ = ()
  isRequired = True

Having defined all of our required data types, we proceed to the “Recipe” content class definition:

class Recipe(systemObjects.Item):
  "The recipe object"
  __slots__ = (
    'categories','rating','preparationTime',
    'servings','ingredients','instructions'
  )

  __props__ = systemObjects.Item.__props__ + __slots__

  def __init__(self):
    systemObjects.Item.__init__(self)

    self.categories = properties.categories()

    self.rating = datatypes.Integer()
    self.rating.value = 5
    self.preparationTime = datatypes.Integer()
    self.preparationTime.value = 30
    self.servings = Servings()
    self.servings.value = 4
    self.ingredients = Ingredients()
    self.instructions = Instructions()

The “'_{_props_}'” class attribute is a special attribute used by the framework. It should be defined only in each new content class that has additional data type attributes. This attribute is a tuple of strings containing the names of all such attributes, including those of the super classes.

The name of the “categories” attribute is obligatory. This is because we have a two-way many-to-many relationship between the “Recipe” and “Category” objects. To clarify this, we need to examine the “Category” content type defined in the “common.py” file.

...
class Category(system.Container):
  ...
  def __init__(self):
    ...
    self.category_objects = properties.category_objects()

The objects’ references that belong in a specified category are stored inside the “category_objects” attribute. The data type of this attribute is the “category_objects” class. It is not considered a good practice to assign the same name to the attribute name and the data type class. In this case this is happening because of a limitation that has been waived since the release of the 0.0.4 version.

Now let’s take a closer look at the “category_objects” data type:

class category_objects(RelatorN):
  ...
  relCc = (
    'schemas.org.innoscript.common.Document',
    'schemas.org.innoscript.collab.Contact',
    'schemas.org.innoscript.recipemanager.Recipe',
  )

  relAttr = 'categories'

The highlighted section simply indicates that each Porcupine object that needs to be categorized should have an attribute named “categories”. If the “categories” attribute is a subclass of “Relator1”, then we have established an one-to-many relationship. On the other hand, if the “categories” attribute is a subclass of “RelatorN”, then the relationship is considered to be many-to-many.

3. Creating the initial content

The next step outlines the creation of the initial content required for our application to start. First, we will need a container where we can append our recipes. In order to achieve this, we need to temporarily edit the containment of the “RootFolder” content class, located inside “common.py”.

class RootFolder(system.Container):
  ...
  containment = (
    'schemas.org.innoscript.common.Folder',
    'schemas.org.innoscript.collab.ContactsFolder',

    'schemas.org.innoscript.recipemanager.RecipeContainer',

  )

Restart the server and login using an administrative account. Open the root folder, right click on the list view and select “New”. Notice that the “RecipeContainer” type is added to the list of the allowed types:

Select the “RecipeContainer” type and create a new object named “Recipes”. If you double click on the new folder you should get the following error:

This is because we have not yet defined a valid registration (servlet binding) for the “RecipeContainer” content class. Hence, we have to edit the “store.xml” file inside the “conf” folder. Since these are the first servlet registrations we create for our application, we must enclose it inside a new package node. Locate the “packages” node at the top of the afore-mentioned file and append the following nodes:

<package name="RecipeManager">
  <reg cc="schemas.org.innoscript.recipemanager.RecipeContainer"
    method="POST"
    param=""

    client="vcXMLRPC"

    lang=".*"

    action="resources.servlets.XMLRPC.ContainerGeneric"/>

  <reg cc="schemas.org.innoscript.recipemanager.RecipeContainer"
    method="GET"
    param="new"

    client="(MSIE 6)|(Mozilla/5.0.+rv:1.[7-9])"

    lang=".*"

    action="resources.servlets.ui.Frm_AutoNew"/>

</package>

As you can see, the first registration takes care of the XML-RPC methods exposed by the “RecipeContainer” content type. For the time being, we need no special behavior; the “RecipeContainer” type exposes the same methods as any other container. Also, notice that the client parameter is set to “vcXMLRPC”. This should be true for every XML-RPC servlet we publish. The second registration defines the servlet to be executed when the user chooses to create a new object inside a “RecipeContainer” folder. Because the “resources.servlets.ui.Frm_AutoNew” is a QuiX? servlet (instance of XULServlet?), we should always check for browser compatibility by allowing this servlet to run only on the supported browsers. What this servlet actually does is to render a generic form based on the attributes of the new Porcupine object we are about to create. Finally, we also need to create the recipe categories container. Double click the “Categories” folder and create a new category folder named “Recipe categories”. Please note that in case your session has expired, you just have to login again. Before restarting the server, you can safely delete the “RecipeContainer?” entry from the containment of the “RootFolder” content type.

4. Designing a new recipe form

The current implementation of the “resources.servlets.ui.Frm_AutoNew” servlet has some limitations that force us to design a new form for the “Recipe” content type. Looking at the form that is automatically generated by the servlet, we notice the absence of the integer data types. This is happening because the servlet, in its current state, ignores the numeric data types (a QuiX? numeric input control, other than the spin button, is in the wish list).

Therefore, we have to create a new recipe form using a new QuiX? servlet. We start by creating the Python module that will host our application servlets. Create a new folder named “recipemanager” inside the “resources/servlets” folder. To make it a Python module, add an empty “__init__.py” file. It is recommended to maintain the QuiX? servlets and the XML-RPC servlets in separate Python files named “ui.py” and “XMLRPC.py” respectively.

Consequently, we create and edit a new Python file named “ui.py” inside the “recipemanager” module. First, we import the “XULServlet?” class, the server’s “ui” module and the content classes’ module we just created:

from porcupine.core.servlet import XULServlet
from resources.servlets import ui
from schemas.org.innoscript import recipemanager

Now comes the tricky part. In order to overwrite the default form generated, when creating a new recipe, we must register a new QuiX? servlet that acts as a splitter. This is because the “RecipeContainer” type accepts both new recipe containers and recipes. When creating a new recipe container, the splitter must get the XML definition output from the “Frm_Auto” servlet, whereas when creating a new recipe the splitter should return the XML definition output from our custom servlet. This is shown below:

class RecipeContainerSplitter(XULServlet):
  def setParams(self):
    sCC = self.request.queryString['cc'][0]

    self.params['FORM'] = ''

    if sCC == 'schemas.org.innoscript.recipemanager.RecipeContainer':
      servlet = ui.Frm_AutoNew(self.server, self.session, self.request)
      self.params['FORM'] = servlet.execute()
    elif sCC == 'schemas.org.innoscript.recipemanager.Recipe':
      servlet = RecipeForm(self.server, self.session, self.request)
      self.params['FORM'] = servlet.execute()

Remember that every QuiX? servlet (instance of the XULServlet? class) must always be accompanied with a xul file in the same directory. This file usually contains the XML definition of the interface, which abides to the Python string formatting rules. The file name of this file is of the following form:

[Name of Python file].[Name of the servlet class name].xul

In order for the servlet to execute successfully, a file named “ui.RecipeContainerSplitter.xul” must be created in the same directory. The specific servlet acts as a wrapper; the content of the xul file is simply:

%(FORM)s

As you propably already have guessed, the server formats the contents of the xul file using the “params” attribute of the servlet. Before proceeding to the recipe form itself, we must modify the “store.xml” configuration file by adding – modifying the highlighted lines:

<package name="RecipeManager">
  <reg cc="schemas.org.innoscript.recipemanager.RecipeContainer"
    method="POST"
    param=""
    client="vcXMLRPC"
    lang=".*"
    action="resources.servlets.XMLRPC.ContainerGeneric"/>
  <reg cc="schemas.org.innoscript.recipemanager.RecipeContainer"
    method="GET"
    param="new"
    client="(MSIE 6)|(Mozilla/5.0.+rv:1.[7-9])"
    lang=".*"

    action="resources.servlets.recipemanager.ui.RecipeContainerSplitter"/>
  <reg cc="schemas.org.innoscript.recipemanager.Recipe$"
    method="GET"
    param="properties"
    client="(MSIE 6)|(Mozilla/5.0.+rv:1.[7-9])"
    lang=".*"
    action="resources.servlets.recipemanager.ui.RecipeForm"/>

<package>

The first modification assigns the “RecipeContainerSplitter” as the servlet to be executed when the browser GETs? a “RecipeContainer” object with the “cmd” parameter set to “new”. The second modification is simply a new servlet registration for the “Recipe” type, which renders the recipe form whenever a compatible browser GETs? an object of this type with the parameter set to “properties”. Now it’s time to write the “RecipeForm” servlet:

class RecipeForm(XULServlet):
  def setParams(self):
    sCC = self.item.contentclass
    sCategories = ''
    sHiddenField = ''
    if sCC == 'schemas.org.innoscript.recipemanager.RecipeContainer':
      # we create a new recipe
      sTitle = 'Create new recipe'
      oRecipe = recipemanager.Recipe()
      # in this case we need an extra hidden field with the type of
      # object we are about to create
      sHiddenField = '<a:field name="CC" type="hidden" ' + \
        'value="schemas.org.innoscript.recipemanager.Recipe" />'
      sMethod = 'create'
      sAction = 'Create'
    elif sCC == 'schemas.org.innoscript.recipemanager.Recipe':
      # we editing an existing one
      oRecipe = self.item
      sMethod = 'update'
      sTitle = 'Recipe properties'
      sAction = 'Update'
    # build the categories options list
    for category in oRecipe.categories.getItems():
      sCategories += '<a:option caption="%s" value="%s" img="%s" />' %
        (category.displayName.value, category.id, category.__image__)
    self.params = {
      'URI': self.request.serverVariables['SCRIPT_NAME'] + '/' + self.item.
      'METHOD': sMethod,
      'TITLE': sTitle,
      'HIDDEN': sHiddenField,
      'DISPLAYNAME': oRecipe.displayName.value,
      'DESCRIPTION': oRecipe.description.value,
      'RATING': oRecipe.rating.value,
      'PREPARATION_TIME': oRecipe.preparationTime.value,
      'SERVINGS': oRecipe.servings.value,
      'INGREDIENTS': oRecipe.ingredients.value,
      'INSTRUCTIONS': oRecipe.instructions.value,
      'CATEGORIES': sCategories,
      'ICON': oRecipe.__image__,
      'ACTION': sAction,
    }

This servlet is called either when the user needs to create a new recipe, or when the user wants to display the properties of an existing recipe. In the first case, the type of the object “called” is the “RecipeContainer” unlike the second case, in which the type of the object is the “Recipe” type.

The QuiX? XML definition of the form is a new file named “ui.RecipeForm.xul” inside the “resources/servlets/recipemanager” folder.

<?xml version="1.0" ?>
  <a:dialog xmlns:a="http://www.innoscript.org/quix" title="%(TITLE)s"
    img="%(ICON)s" close="true" width="480" height="380" left="30%%" top="10%%">
    <a:script name="Generic Form Script" src="scripts/form_auto.js" />
    <a:script name="Generic Functions" src="scripts/generic.js" />
    <a:wbody>

      <a:form action="%(URI)s" method="%(METHOD)s" padding="4,4,4,4">

        %(HIDDEN)s
        <a:label caption="Recipe name:"/>
        <a:field left="80" width="380" name="displayName"
          value="%(DISPLAYNAME)s" />
        <a:label caption="Description:" top="25" />
        <a:field left="80" top="24" width="380" name="description"
          value="%(DESCRIPTION)s" />
        <a:hr top="50" width="100%%" />
        <a:label top="58" caption="Preparation time (min):" />
        <a:spinbutton name="preparationTime" top="55" left="110" width="50" 
          max="240" value="%(PREPARATION_TIME)d" editable="true" />
        <a:label top="58" left="200" caption="Servings:" />
        <a:spinbutton name="servings" top="55" left="250" width="40" max="12"
          editable="true" value="%(SERVINGS)d" />
        <a:label top="58" left="320" caption="Rating:" />
        <a:spinbutton name="rating" top="55" left="360" width="40" max="10"
          editable="true" value="%(RATING)d" />
        <a:tabpane top="90" width="100%%" height="220">
          <a:tab caption="Ingredients">
            <a:field type="textarea" name="ingredients" width="100%%"
              height="100%%">%(INGREDIENTS)s</a:field>
            </a:tab>
            <a:tab caption="Instructions">
              <a:field type="textarea" name="instructions" width="100%%"
                height="100%%">%(INSTRUCTIONS)s</a:field>
            </a:tab>
            <a:tab caption="Categories">
            <a:splitter width="100%%" height="100%%" orientation="h">
              <a:pane length="-1">
                <a:selectlist name="categories" multiple="true" posts="all"
                  width="100%%" height="100%%">
                  <a:prop name="SelectFrom"
                    value="Categories/Recipe categories"></a:prop>
                  <a:prop name="RelatedCC" 
                    value="schemas.org.innoscript.common.Category"></a:prop>
                  %(CATEGORIES)s
                </a:selectlist>
              </a:pane>
              <a:pane length="24">
                <a:flatbutton width="70" height="22" caption="Add"

                  onclick="generic.selectItems"></a:flatbutton>

                <a:flatbutton left="80" width="70" height="22" caption="Remove"

                  onclick="generic.removeSelectedItems"></a:flatbutton>

              </a:pane>
            </a:splitter>
          </a:tab>
        </a:tabpane>
      </a:form>
    </a:wbody>

    <a:dlgbutton onclick="autoform.submit" width="70" height="22"

      caption="%(ACTION)s" default="true" />
    <a:dlgbutton onclick="__closeDialog__" width="70" height="22"
      caption="Cancel" />
  </a:dialog>

Initially, this form imports two QuiX? desktop JavaScript? files. The first script is the one used by the forms generated automatically by the “Frm_Auto” servlet. The function we reuse from this script(“pubdir/scripts/form_auto.js”) is the “autoform.submit” function. This function simply submits the first QuiX? form found inside the current dialog.

...
autoform.submit = function(evt, w) {
  var oForm = w.getParentByType(Dialog).getWidgetsByType(Form)[0];

  oForm.submit(autoform.update);

}
autoform.update = function(response, form) {
  var dlg = form.getParentByType(Dialog);

  dlg.attributes.refreshlist();

  dlg.close();
}
...

The “submit” method of a QuiX? form takes one argument; the function to call asynchronously, once the browser has the submission response. In this case the dialog has a custom attribute which is actually the function to call for refreshing the opener’s list view. After calling this function, the dialog is closed.

The form's “action” parameter is the URL where the form data get posted. This is usually the HTTP address of a Porcupine object whose type has an XML-RPC servlet registered in the “store.xml” configuration file (visit http://www.innoscript.org/content/view/35/41/ to see how each object is accessible over HTTP).

The form's “method” parameter is the name of the method of the XML-RPC servlet to call. Since this form is used for both creating and editing recipes the name of the method is diferrent in each aspect. When creating a new recipe we call the “create” method of the “resources.servlets.XMLRPC.ContainerGeneric” XML-RPC servlet.

...

class ContainerGeneric(ItemGeneric):
  def create(self, data):

    # create new item

    oNewItem = misc.getClassByName(data.pop('CC'))()

    # get user role
    iUserRole = objectAccess.getAccess(self.item, self.session.user)
    if data.has_key('__rolesinherited') and iUserRole == \
    objectAccess.COORDINATOR:
      oNewItem.inheritRoles = data.pop('__rolesinherited')
      if not oNewItem.inheritRoles:
        acl = data.pop('__acl')
        if acl:
          security = {}
          for descriptor in acl:
            security[descriptor['id']] = int(descriptor['role'])
          oNewItem.security = security
    # set props
    for prop in data:
      oAttr = getattr(oNewItem, prop)
      if isinstance(oAttr, datatypes.File):
        if data[prop]['tempfile']:
          oAttr.filename = data[prop]['filename']
          sPath = self.server.temp_folder + '/' + data[prop]['tempfile']
          oAttr.loadFromFile(sPath)
          os.remove(sPath)
      elif isinstance(oAttr, datatypes.Date):
        oAttr.value = data[prop].value
      else:
        oAttr.value = data[prop]

    txn = self.server.store.getTransaction()
    oNewItem.appendTo(self.item.id, txn)
    txn.commit()

    return True

...

The “data” argument contains the form data. It is a Python dictionary containing the field names and values.

This method requires an additional field posted named “CC”. This field contains the type of the object that is going to be appended to the calling container. Each XML-RPC method should always return a value. This method simply returns “True” only if the object is created and appended to the container successfully. This way, the browser knows that the request has been succefully completed.

Also notice, that the “ContainerGeneric” servlet is a subclass of the “ItemGeneric” servlet. Besides the container specific methods defined, a container can also be updated, copied or renamed just like any other Porcupine object.

Respectively, when editing an existing recipe, we call the “update” method of the “resources.servlets.XMLRPC.ItemGeneric” XML-RPC servlet.

The recipe form also includes the “pubdir/scripts/generic.js” JavaScript? file. From this file we reuse two JavaScript? functions named “generic.selectItems” and “generic.removeSelectedItems”.

...
generic.selectItems = function(evt, w) {
  var oDialog = w.getParentByType(Dialog);
  var oTarget = w.parent.parent.getWidgetsByType(SelectList)[0];
  var sFolderURI = oTarget.attributes.SelectFrom;
  var sCC = oTarget.attributes.RelatedCC;

  generic.selectObjects(oDialog, oTarget, generic.addSelectionToList,
    sFolderURI, sCC, 'true');

}
...
generic.selectObjects =
function(win, target, select_func, startFrom, contentclass, multiple) {
  ...
}
...
generic.removeSelectedItems = function(evt, w) {
  var oSelectList = w.parent.parent.getWidgetsByType(SelectList)[0];
  oSelectList.removeSelected();
}
...

The “generic.selectItems” function displays the object select dialog by calling the “generic.selectObjects” function. The auto-generated form uses this function for “ReferenceN?” or “RelatorN?” data types. The arguments given to the “generic.selectObjects” function are:

• win: the opener
• target: the target widget (in this case, the select list included in the recipe form)
• select_func: the function to call when the user presses the “Select” button
• startFrom: The ID of the root node of the tree (in this case, the “SelectFrom” custom attribute of the select list on the recipe form)
• contentclass: The type of the Porcupine objects that we can select
• multiple: “true” if multiple selection is allowed, else “false”

Restart the server. If everything is in place, you should see the following form when choosing to create a new recipe:

5. The Recipe Manager application

Apart from the custom forms and the custom content types, we will also need a custom UI tailored to the given requirements. This is accomplished by creating a new application object. The Porcupine desktop provides generic interfaces and almost in every case, will not meet the requirements analysis.

To create a new application, login to Porcupine as an administrator and navigate to the “Administrative Tools/Applications” folder. Create a new application named “Recipe manager”. Set the dimensions of the application window to 640x480 (width and height). In the interface tab, paste the following QuiX? definition. Do not forget to replace the tree node’s ID with the ID of the “Recipes” folder given by the system.

<a:splitter width="100%%" height="100%%" orientation="h" spacing="0">
  <a:pane length="28">
    <a:toolbar width="100%%" height="100%%">
      <a:tbbutton caption="Create recipe folder" width="120">
        <a:prop name="cc" value="schemas.org.innoscript.recipemanager.RecipeContainer"/>
      </a:tbbutton>
      <a:tbbutton caption="Create recipe" width="80">
        <a:prop name="cc" value="schemas.org.innoscript.recipemanager.Recipe"/>
      </a:tbbutton>
      <a:tbsep/>
      <a:tbbutton caption="Refresh" width="60" />
    </a:toolbar>
  </a:pane>
  <a:pane length="-1" bgcolor="white">
    <a:splitter width="100%%" height="100%%" orientation="v"
      interactive="true">
      <a:pane length="200">
        <a:outlookbar width="100%%" height="100%%">
          <a:tool caption="Recipes">

            <a:foldertree id="tree" method="getSubtree" padding="4,4,4,4">
              <a:treenode id="[Put here the ID of the Recipes folder]" haschildren="true"

                img="images/folder.gif" caption="Recipes">
              </a:treenode>
            </a:foldertree>
          </a:tool>
          <a:tool caption="Search" bgcolor="gray">
            <a:label caption="Recipe title contains:" />
            <a:field id="title" left="5" top="20" width="160" />
            <a:label top="50" caption="Preparation time is less than" />
            <a:field id="preparationTime" left="5" top="70" width="30" />
            <a:label top="72" left="40" caption="min." />
            <a:label top="100" caption="The recipe's rating is greater than" />
            <a:spinbutton top="120" left="5" width="40" max="10" value="0"
              id="rating"/>
            <a:label top="150" caption="Recipe ingredients contain:" />
            <a:field id="ingredients" top="170" left="5" width="160" />
            <a:label top="190" caption="(comma separated list)"
              style="font-style:italic" />
            <a:button top="220" left="center" width="60" height="28"
              caption="Search" />
          </a:tool>
        </a:outlookbar>
      </a:pane>
      <a:pane length="-1">

        <a:listview id="list" width="100%%" height="100%%">

          <a:listheader>
            <a:column width="140" caption="Recipe title" name="displayName"
              bgcolor="#EFEFEF" sortable="true"></a:column>
            <a:column width="60" caption="Servings" type="int" name="servings"
              sortable="true"></a:column>
            <a:column width="100" caption="Preparation time" type="int"
              name="preparationTime" sortable="true"></a:column>
            <a:column width="40" caption="Rating" type="int" name="rating"
              sortable="true"></a:column>
            <a:column width="160" caption="Date modified" type="date"
              name="modified" sortable="true"></a:column>
          </a:listheader>
        </a:listview>
      </a:pane>
    </a:splitter>
  </a:pane>
</a:splitter>

Press the “Create” button to create the application object. The above interface contains no functionality. We have just created a “dummy” application.

The folder tree widget and the list view have been given an ID for them to become easily accessible from our scripts. The “method” attribute is the XML-RPC method to call whenever the user expands a tree node.

Let's start by adding some event handlers.

...
<a:toolbar width="100%%" height="100%%">
  <a:tbbutton caption="Create recipe folder" width="120"

    onclick="recipemanager.createItem">

    ...
  </a:tbbutton>
  <a:tbbutton caption="Create recipe" width="80"

    onclick="recipemanager.createItem">

    ...
  </a:tbbutton>
  <a:tbsep />
  <a:tbbutton caption="Refresh" width="60"

    onclick="recipemanager.refresh_onclick" />

</a:toolbar>
...
<a:listview id="list" multiple="true" width="100%%" height="100%%"

  onload="recipemanager.loadRecipes">

  ...

In the application's script tab insert the following code:

function recipemanager() {}

recipemanager.createItem = function(evt, w) {
  var oWin = w.getParentByType(Window);
  var oTree = oWin.getWidgetById('tree');

  var sCC = w.attributes.cc;

  var id = oTree.getSelection().id;

  document.desktop.parseFromUrl(id + '?cmd=new&cc=' + sCC,
    function(w) {
      w.attributes.refreshlist = function() {
        if (sCC=='schemas.org.innoscript.recipemanager.Recipe')
          recipemanager.refreshList(oWin);
      }
    }
  );

}

recipemanager.refresh_onclick = function(evt, w) {
  recipemanager.loadRecipes(w);
}

recipemanager.loadRecipes = function(w) {

  var appWin = w.getParentByType(Window);
  recipemanager.refreshList(appWin);
}

recipemanager.refreshList = function(appWin) {
  var oTree = appWin.getWidgetById('tree');
  var id = oTree.getSelection().id;
  var listView = appWin.getWidgetById('list');
  var sOql = "select id, displayName, servings, preparationTime, rating, " +
             "modified from '" + id + "' where contentclass = " +
             "'schemas.org.innoscript.recipemanager.Recipe' order by displayName asc";

  var xmlrpc = new XMLRPCRequest(QuiX.root);
  xmlrpc.oncomplete = recipemanager.updateList;
  xmlrpc.callback_info = listView;

  xmlrpc.callmethod('executeOqlCommand', sOql);
}

recipemanager.updateList = function(req) {

  req.callback_info.dataSet = req.response;
  req.callback_info.refresh();

}

The “recipemanager.createItem” handler displays the appropriate form based on the type of the object selected by the user. This is detected by the “cc” custom attribute assigned to the toolbar buttons using the “a:prop” nodes. The location of the new object is determined by the current tree selection. The “parseFromUrl” QuiX? widget method loads an XML UI definition from a specified URL, inside the referring widget. The second argument of this method is a function called when the interface is loaded. The first argument of this function is the root widget created. In this event, the root widget - the form dialog - will be appended to the desktop (“document.desktop” is the desktop widget).

The “recipemanager.loadrecipes” handler is called once when the list view is loaded. This handler loads the recipes from the selected container and displays them in the list view. The “onload” event handler, unlike the other events, does not accept the two common event handler arguments, the event object and the widget, but instead accepts only the widget that fires the event. The “getParentByType” QuiX? widget method returns the first parent widget of the specified type. The only argument of this method is the constructor function of the parent we are searching for. The “Window” class is defined inside the “pubdir/__xul/windows.js” QuiX? module.

The “recipemanager.refreshList” function executes the OQL query that returns the recipes contained inside the selected tree container. Inside this function we send a new XMLRPC request to the root folder. The “oncomplete” attribute of the request is the callback function to call when the query has completed. This function is always called having the request object as the first argument. The “callback_info” attribute is a placeholder for anything we would like to access inside the callback function. In this case, the “callback_info” is a reference to the list view widget.

Finally, the “recipemanager.updateList” callback function updates the “dataSet” attribute of the list view and then refreshes it. The “dataSet” attribute is an array of arbitrary objects. Such an array is directly returned from the XML-RPC call.

Afterwards, we must synchronize the tree with the list view. This means that for each new tree selection we should update the list view accordingly. This is accomplished by adding the following event handler:

...
<a:foldertree id="tree" method="getSubtree" padding="4,4,4,4"

  onselect="recipemanager.loadRecipes">

  ...
</a:foldertree>
...

Next, we implement the search functionality. We start by adding a new “onclick” event handler on the search button:

...
<a:button top="220" left="center" width="60" height="28" caption="Search"

  onclick="recipemanager.search" />

...

Add the following function to the “Script” tab of the application dialog:

recipemanager.search = function(evt, w) {
  var displayName = w.parent.getWidgetById('title').getValue();
  var preparationTime = w.parent.getWidgetById('preparationTime').getValue();
  var rating = w.parent.getWidgetById('rating').getValue
  var ingredients = w.parent.getWidgetById('ingredients').getValue();
  var sOql = "select id, displayName, servings, preparationTime, rating, " +

             "modified from deep('/Recipes')";

  var listView = w.getParentByType(Window).getWidgetById('list');
  var conditions = ["contentclass='schemas.org.innoscript.recipemanager.Recipe'"];
  if (displayName!='') {
    conditions.push("'" + displayName + "' in displayName");
  }
  if (preparationTime!='') {
    conditions.push("preparationTime < " + preparationTime);
  }
  if (rating>0) {
    conditions.push("rating > " + rating);
  }
  if (ingredients!='') {
    var arrIng = ingredients.split(',');
    for (var i=0; i<arrIng.length; i++) {
      conditions.push("'" + arrIng[i] + "' in ingredients");
    }
  }
  if (conditions.length > 0) {
    sOql += ' where ' + conditions.join(' and ');
    var xmlrpc = new XMLRPCRequest(QuiX.root);
    xmlrpc.oncomplete = recipemanager.updateList;
    xmlrpc.callback_info = listView;
    xmlrpc.callmethod('executeOqlCommand', sOql);
  }
}

The above function forms the OQL query according to the criteria set by the user on the search form. Notice that we search all the recipes, by using the “deep” operator at the select scope. Also when the user double clicks on the list view, the selected recipe dialog should open:

<a:listview multiple="true" width="100%%" height="100%%" id="list"
  onload="recipemanager.loadRecipes"

  ondblclick="recipemanager.loadItem">

The following event handler should be added to the script of the application:

recipemanager.loadItem = function(evt, w, recipe) {
  var oWin = w.getParentByType(Window);
  generic.showObjectProperties(null, null, recipe,

    function() {
      recipemanager.refreshList(oWin);
    }

  );
}

This event handler reuses the “generic.showObjectProperties” function. The function given as an argument is called when the user updates the item and the list view of the opener must be updated.

The final enhancement is the addition of a context menu. Open the application object and add the following lines to the interface definition:

<a:pane length="-1">

  <a:contextmenu onshow="recipemanager.contextmenu_onshow">
    <a:menuoption caption="Open" onclick="recipemanager.openRecipe" />
    <a:menuoption caption="Delete" onclick="recipemanager.deleteRecipe" />
  </a:contextmenu>

  <a:listview width="100%%" height="100%%" id="list"
    onload="recipemanager.loadRecipes" ondblclick="recipemanager.loadItem">
    ...
  </a:listview>
</a:pane>

Add the following handlers to the application’s script:

recipemanager.contextmenu_onshow = function(menu) {

  var oList = menu.owner.getWidgetById('list');

  menu.options[0].disabled = (oList.selection.length == 0); //open
  menu.options[1].disabled = (oList.selection.length == 0); //properties
}

recipemanager.openRecipe = function(evt, w) {
  var oList = w.parent.owner.getWidgetById('list');
  var selectedRecipe = oList.getSelection();
  recipemanager.loadItem(null, oList, selectedRecipe);
}

recipemanager.deleteRecipe = function(evt, w) {
  var oList = w.parent.owner.getWidgetById('list');
  var selectedRecipe = oList.getSelection();
  var desktop = document.desktop;
  _deleteItem = function(evt, w) {
    var oMsgBox = w.getParentByType(Dialog);
    var xmlrpc = new XMLRPCRequest(QuiX.root + selectedRecipe.id);
    xmlrpc.oncomplete = function(req) {
      oMsgBox.close();
      recipemanager.loadRecipes(oList);
    }
    xmlrpc.onerror = function(req) { oMsgBox.close(); }
    xmlrpc.callmethod('delete');
  }

  desktop.msgbox(w.caption,

    "Are you sure you want to delete this recipe?",
    [
      [desktop.attributes['YES'], 60, _deleteItem],
      [desktop.attributes['NO'], 60]
    ],
    'images/messagebox_warning.gif', 'center', 'center', 260, 112);
}

The first event handler is called whenever the context menu is displayed. The parent widget of every context menu is the desktop. Thus, there must be a way to get the menu’s enclosing widget. The enclosing widget is accessible through the “owner” menu property.

The “desktop.msgbox” is used for displaying message boxes. The arguments accepted by this method are:

1. The title of the message box.
2. The message displayed in the message box.
3. An array of the buttons. Each button is also an array of three elements. The first element is the caption of the button, the second is the width of the button, and the third is the function to call once the button is clicked. If omitted the button closes the message box.
4. The image displayed inside the message box.
5. The x-coordinate of the message box.
6. The y-coordinate of the message box.
7. The width of the message box.
8. The height of the message box.

Next, log off and log on again. Launch the recipe manager application. If you see the following window, then congratulations, you have just created your first Porcupine application!

6. Packaging your application

Using the “pakager” utility we will consolidate all of the application’s pieces into a single distributable file. This procedure requires at least one package definition file. Create a new folder named “PKG” inside the porcupine installation directory. Inside this folder create a new file named “recipemanager.ini”. Edit the contents of this file:

[package]
name=RecipeManager
version=0.0.1

The first section of the package definition file has information about the package (its name and its version). Please notice that the name of the package and the value of the name attribute of the package node in the “store.xml” configuration file must be identical.

[files]
1=schemas/org/innoscript/recipemanager.py

The second section has the relative paths of the files required by the application. Particularly, this section adds to the package the application’s content classes.

[dirs]
1=resources/servlets/recipemanager

The third section adds directories to the package. This directory is the one that contains the servlets.

[pubdir]

The fourth section contains the published directories (usually containing external JavaScript? files and images) that are required by the application. In this case, we did not create a new published directory; all of the application’s JavaScript? handlers are embedded inside the application object and we did not use any new images.

[items]
application=[Put here the ID of the Recipe Manager application]
recipes_folder=[Put here the ID of the “/Recipes” folder]
recipe_categories_folder=[Put here the ID of the “/Categories/Recipe
categories” folder]

In this section we include all the Porcupine objects to export in the package, including the application object itself. Replace the highlighted portions with the object IDs? printed on their properties dialog.

[scripts]
postinstall=PKG/postinstall.py
uninstall=PKG/uninstall.py

The “scripts” section contains Python script files included in the package. The “postinstall” executes immediately after the installation finishes. The “uninstall” script executes when the application is uninstalled.

Let’s see the contents of these scripts. Create a new Python script file inside the “PKG” directory named “postinstall.py”. Open the file and add the following lines:

# RecipeManager post installation script
from porcupine.administration import codegen
ce = codegen.DatatypeEditor('schemas.org.innoscript.properties.category_objects')

ce.relCc.append('schemas.org.innoscript.recipemanager.Recipe')

ce.commitChanges()

The “codegen” module provides an essential API for runtime manipulation of the Porcupine objects and data types. This script modifies an existing data type (the “category_objects” class). To be precise, it adds the “schemas.org.innoscript.recipemanager.Recipe” content class to the list of types that can be categorized (i.e. to the “relCc” class attribute of the data type). Similarly, inside the “PKG” folder create a new Python script named “uninstall.py”. Open the file and add the following lines:

# RecipeManager uninstallation script
from porcupine.administration import codegen
ce = codegen.DatatypeEditor('schemas.org.innoscript.properties.category_objects')

ce.relCc.remove('schemas.org.innoscript.recipemanager.Recipe')

ce.commitChanges()

Before proceeding to the creation of the package, stop the Porcupine service. Afterwards, run the “pakager” utility as follows:

 python pakager.py –c –d PKG/recipemanager.ini

The Porcupine package file (RecipeManager-0.0.1.ppf) is created inside the Porcupine installation directory. The application can be installed on another Porcupine installation using the following command:

python pakager.py –i –p RecipeManager-0.0.1.ppf