diff -r 000000000000 -r 2e8eeb919028 configurationengine/doc/plugins/contentml-plugin/content.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/configurationengine/doc/plugins/contentml-plugin/content.rst Thu Mar 11 17:04:37 2010 +0200 @@ -0,0 +1,168 @@ +How to use the ConE Content plugin +================================== + +Introduction +''''''''''''' +The basic concept of Content plugin is to transfer file resources from +one place to another. So one may have for example; an audio file stored in the +configuration project and needs to define the audio file location in the +device. With ConE Content plugin you can basically define a copy operation. +You just create .content (or general *.implml file) type file to the configuration project implml folder +and set the rules or filters in there. + + +content elements +---------------- +The content model is drawn out as a uml model in below picture. + + .. image:: content2.jpg + +content +^^^^^^^ +The root element of the content file is always content, which defines the xml namespace (xmlns) +to http://www.s60.com/xml/content/2 in the current version. + +**content example**:: + + + +tag +^^^^ + +Implementation tag elements can be defined under the root element. See the page on `tags `_ for more info. + +output +^^^^^^ +The output element can define a output folder where content is copied from :ref:`content-input` elements that +are children of this particular output. There can be several output elements inside a single content +file or block. + +**output example**:: + + + +The above statement defines that content is copied under foobar folder in the cone output folder. + + +.. _content-input: + +input +^^^^^^ +The user can define input under the output element. The input element can define a source directory and two file filters for +that directory (include and exclude filters). The input element will always search files under the content directories of the +configuration project. But the content of the search directory is a layered content of all configuration project content directories +(See content layering in Configuration project specification (TODO: add link here)). + +**input example**:: + + + +the above statement would include all files found under foobar directory.:: + + + +the above statement would include file1.txt from folder foobar to the copy operation. + +include +^^^^^^^^ +The include filter can be used inside input statement to filter files for the copy operation. + +The include filter can have following attributes. + ++------------------+-------------------------------------------+ +| Attribute name | description | ++==================+===========================================+ +| files | comma separated list of inpu files. | ++------------------+-------------------------------------------+ +| pattern | regexp pattern to filter input files that | +| | are found in the input folder. | ++------------------+-------------------------------------------+ +| flatten | "true"|"false" to define if the directory | +| | struture is flattened at output. | ++------------------+-------------------------------------------+ + +**input include example** + +This would copy files foobar/test/override.txt and foobar/test/s60.txt to output if they are found.:: + + + + + +The below statement would copy all files ending with ".jpg" from userdata and copy them +directly to the output root folder.:: + + + + + +exclude +^^^^^^^^ +The exclude filter can be used similarly as the include filter, but in a negative meaning. +For example to ensure that files beginning with a dot are never copied. + +The exclude filter can have following attributes. + ++------------------+-------------------------------------------+ +| Attribute name | description | ++==================+===========================================+ +| pattern | regexp pattern to filter input files that | +| | are found in the input folder. | ++------------------+-------------------------------------------+ + +**input exclude example** + +This would exclude all files that have .svn as part of the file path:: + + + + + + +How to create a content file +---------------------------- + +* Create a new file in the content folder name for ex. mycontentfile.content +* Set the file encoding to UTF-8 +* Set the definition tag first ** +* Set the content tag ** +* Set the description tag *Copy only prod* +* Set a content configuration tag for ex. ** +* Set another content configuration tag for ex. ** +* Close the content tag ** + +Now you have content file which copies the prod files to the content directory in the device configuration + +**example of a entire content file** + +The example defines here two copy operations to two different outputs. First one to content with selected +files as input and the other to include, where it tries to copy all \*.hrh files to the root of the include +directory. + +.. literalinclude:: example.content + + +Logic and rules +--------------- + +What may you define with content file logic. Here are some explanations. + +* ** include the files in the prod folder +* ** exclude the files in the prod folder +* ** input files are setted in the value of the content/inputdir reference link in confml +* ** output files are setted in the value of the content/outputdir reference link in confml + +So you may include and exclude folder and files. Content file definition supports regex patterns +You may give the location of the content as a confml reference link, *note: use the dots instead of slashes* + + +XSD +--- + +.. literalinclude:: ../../xsd/contentml2.xsd + :linenos: + + +FAQ +--- +This will be updated based on the questions.