1 How to use the ConE Content plugin

     2 ==================================

     3 

     4 Introduction

     5 '''''''''''''

     6 The basic concept of Content plugin is to transfer file resources from

     7 one place to another. So one may have for example; an audio file stored in the

     8 configuration project and needs to define the audio file location in the

     9 device. With ConE Content plugin you can basically define a copy operation. 

    10 You just create <somename>.content (or general *.implml file) type file to the configuration project implml folder 

    11 and set the rules or filters in there.    

    12 

    13 

    14 content elements

    15 ----------------

    16 The content model is drawn out as a uml model in below picture.

    17 

    18   .. image:: content2.jpg

    19 

    20 content

    21 ^^^^^^^

    22 The root element of the content file is always content, which defines the xml namespace (xmlns) 

    23 to http://www.s60.com/xml/content/2 in the current version. 

    24 

    25 **content example**::

    26 

    27   <content xmlns="http://www.s60.com/xml/content/2"/>

    28 

    29 tag

    30 ^^^^

    31 

    32 Implementation tag elements can be defined under the root element. See the page on `tags <tags.html>`_ for more info.

    33 

    34 output

    35 ^^^^^^

    36 The output element can define a output folder where content is copied from :ref:`content-input` elements that 

    37 are children of this particular output. There can be several output elements inside a single content 

    38 file or block.

    39 

    40 **output example**::

    41 

    42   <output dir="foobar"/>

    43 

    44 The above statement defines that content is copied under foobar folder in the cone output folder.

    45 

    46 

    47 .. _content-input:

    48 

    49 input

    50 ^^^^^^

    51 The user can define input under the output element. The input element can define a source directory and two file filters for 

    52 that directory (include and exclude filters). The input element will always search files under the content directories of the 

    53 configuration project. But the content of the search directory is a layered content of all configuration project content directories 

    54 (See content layering in Configuration project specification (TODO: add link here)).

    55 

    56 **input example**::

    57 

    58   <input dir="foobar"/>

    59 

    60 the above statement would include all files found under foobar directory.::

    61 

    62   <input file="foobar/file1.txt"/>

    63 

    64 the above statement would include file1.txt from folder foobar to the copy operation.

    65 

    66 include

    67 ^^^^^^^^

    68 The include filter can be used inside input statement to filter files for the copy operation.

    69 

    70 The include filter can have following attributes.

    71 

    72 +------------------+-------------------------------------------+

    73 | Attribute name   | description                               |

    74 +==================+===========================================+

    75 | files            | comma separated list of inpu files.       |

    76 +------------------+-------------------------------------------+

    77 | pattern          | regexp pattern to filter input files that |

    78 |                  | are found in the input folder.            |

    79 +------------------+-------------------------------------------+

    80 | flatten          | "true"|"false" to define if the directory |

    81 |                  | struture is flattened at output.          |

    82 +------------------+-------------------------------------------+

    83 

    84 **input include example**

    85 

    86 This would copy files foobar/test/override.txt and foobar/test/s60.txt to output if they are found.::

    87 

    88   <input dir="foobar">

    89     <include files="test/override.txt, test/s60.txt"/>

    90   <input>

    91 

    92 The below statement would copy all files ending with ".jpg" from userdata and copy them 

    93 directly to the output root folder.::

    94 

    95   <input dir="userdata">

    96     <include pattern="\.jpg$" flatten="true"/>

    97   <input>

    98 

    99 exclude

   100 ^^^^^^^^

   101 The exclude filter can be used similarly as the include filter, but in a negative meaning. 

   102 For example to ensure that files beginning with a dot are never copied.

   103 

   104 The exclude filter can have following attributes.

   105 

   106 +------------------+-------------------------------------------+

   107 | Attribute name   | description                               |

   108 +==================+===========================================+

   109 | pattern          | regexp pattern to filter input files that |

   110 |                  | are found in the input folder.            |

   111 +------------------+-------------------------------------------+

   112 

   113 **input exclude example**

   114 

   115 This would exclude all files that have .svn as part of the file path::

   116 

   117   <input dir="foobar">

   118     <exclude pattern="\.svn"/>

   119   <input>

   120 

   121 

   122 How to create a content file

   123 ----------------------------

   124 

   125 * Create a new file in the content folder name for ex. mycontentfile.content

   126 * Set the file encoding to UTF-8

   127 * Set the definition tag first *<?xml version="1.0" encoding="UTF-8"?>*

   128 * Set the content tag *<content xmlns="http://www.s60.com/xml/content/1">*

   129 * Set the description tag *<desc>Copy only prod</desc>*

   130 * Set a content configuration tag for ex. *<include pattern="prod"/>*

   131 * Set another content configuration tag for ex. *<output dir="content"/>*

   132 * Close the content tag *</content>*

   133 

   134 Now you have content file which copies the prod files to the content directory in the device configuration 

   135 

   136 **example of a entire content file**

   137 

   138 The example defines here two copy operations to two different outputs. First one to content with selected 

   139 files as input and the other to include, where it tries to copy all \*.hrh files to the root of the include 

   140 directory.

   141 

   142 .. literalinclude:: example.content

   143 

   144 

   145 Logic and rules

   146 ---------------

   147 

   148 What may you define with content file logic. Here are some explanations.

   149 

   150 * *<include pattern="prod"/>* include the files in the prod folder

   151 * *<exclude pattern="prod"/>* exclude the files in the prod folder

   152 * *<input dir="${content.inputdir}"/>* input files are setted in the value of the content/inputdir reference link in confml

   153 * *<output dir="${content.outputdir}"/>* output files are setted in the value of the content/outputdir reference link in confml

   154 

   155 So you may include and exclude folder and files. Content file definition supports regex patterns

   156 You may give the location of the content as a confml reference link, *note: use the dots instead of slashes*  

   157  

   158  

   159 XSD

   160 ---

   161 

   162 .. literalinclude:: ../../xsd/contentml2.xsd

   163    :linenos:

   164 

   165  

   166 FAQ

   167 ---

   168 This will be updated based on the questions.