source: publico/SDE/trunk/README.txt @ 5327

Última Alteração nesse arquivo desde 5327 foi 802, incluída por ciciliati, 15 anos atrás

Importação inicial do SDE (Structured Document Editor), versão 0.0.2, distribuída com o SAPL 2.0.2 .

File size: 14.8 KB
Linha 
1Zope SDE - Structured Document Editor
2
3    SDE is a Zope-based editor for documents which present well defined structure, composed by sets of elements.
4
5    SDE is XML oriented: the objects responsible for defining the structure of a document can be exported as a XML-Schema file (.xsd), and the document itself can be exported as a XML file, in raw format or rendered through XSLT files.
6
7    SDE can be seen as a **tool for creating and editing XML documents based on a given XML-Schema definition**. The editor guides the user who is creating a document to produce a *valid* and *well-formed* XML document.
8
9    How to Install? What are the Requirements?
10
11        SDE is built upon the Zope OFS.OrderedFolder class, which is available since **Zope 2.7**.
12
13        Unpack the SDE_x_x_x.tgz in the Products folder of your Zope instance, and restart it.
14
15        Since all XSLT processing is made on the client-side (web browser!), use browser versions so up to date as possible. The best results are achieved on Mozilla, version 1.6 or newer.
16
17    How to Use?
18
19        In the ZMI (Zope Management Interface), you will be able to use two main types of objects, **SDE-Template** - to define a document type - and **SDE-Document** - to hold the document itself.
20
21        "SDE-Document" objects can be seen as instances of "SDE-Template" objects.
22
23        Obviously you can create several "SDE-Document" objects derived from the same "SDE-Template" object.
24
25        This is the description for these two types of objects and its sub-objects:
26
27__________
28
29        - **SDE-Template**
30
31            This is the object used to define documents templates. It is a folderish object (is able to contain other objects), and can hold "SDE-Template-Element" objects and "SDE-Template-Link" objects. The order (position) of these sub-objects contained in a SDE-Template IS relevant, and you can set it by checking the object(s) you want to move and clicking on "Up" or "Down" buttons in the ZMI.
32
33            **Properties:**
34
35            - Title
36
37                String - This is the standard "Title" property existing in many Zope Objects.
38
39            - xmlns_prefix
40
41                String - Defines the prefix used for the XML namespace when generating the XML-Schema. All XML documents created by SDE use XML namespaces. Here you define the prefix that will be present in every XML tag of your document, with the format <xx:yyyyy>, where xx is the xmlns_prefix, and yyyyy is the name of the element.
42
43            - xml_tag
44
45                String - Defines the name for the root tag of a XML document based on this template.
46
47            - default_xslt_for_html
48
49                String - Address (URL or relative path) for a XSLT file that will be used as default XSLT for transforming XML documents based on this template into HTML. Is used by the invocation of the document's method **renderXML** with a parameter "xsl=__default__".
50
51            - default_xslt_for_editor
52
53                String - Address (URL or relative path) for a XSLT file that will be used as default XSLT for editing  XML documents based on this template. Is used by the invocation of the document's method **renderXMLforEditing** with a parameter "xslt=__default__".
54
55            **Methods:**
56
57            - *renderXSD*
58
59                Returns a XML-Schema file representing the structure defined in the template.
60
61                Example of usage:: "http://your_server/your_template/renderXSD"
62
63            **Sub-objects:**
64
65            - **SDE-Template-Element**
66
67                This object is used to define an element in a document template. It's also a folderish object, and can contain others "SDE-Template-Element" objects, as well as "SDE-Templete-Link" and "SDE-Template-Attribute" objects.
68
69                A SDE-Template-Element is also able to hold some specific Python Scripts, that can be used as event-handlers (see below, at the "Events" section).
70
71                Properties:
72
73                    - *initial_text:* (text)
74
75                        Default content for new instance of this element in a document. If left blank, the instance element will be created without any initial value;
76
77                    - *optional:* (boolean)
78
79                        Defines if the presence of an instance of this element in a document is or not optional. In the XSD rendered after its template, it produces the attribute "minOccurs='1'" when true, or "minOccurs='0'" when false;
80
81                    - *multiple:* (boolean)
82
83                        Defines if is possible to have more than one instance of this element in a document. It appears in the corresponding XSD as "maxOccurs='unbounded'" when true, or "maxOccurs='0'" when false;
84
85                    - *has_own_value:* (boolean)
86
87                        Indicates if the instance element can have a text value associated to it, or if it is only a grouping element that will hold other elements;
88
89                    - *exclusivity_group* (int)
90
91                        The value of this attribute is meaningful when compared to the value of exclusivity_group of other elements at the same hierarchy level in the template. When two or more elements have the same value for exclusivity_group, it means that only one type of these elements can appear in the instance document. During the edition, after creating one instance of an element that has in its definition a given value for exclusivity_group, the editor will suppress the possibility for creating instances of elements that have in their definition the same value for exclusivity_group.
92
93                        The default value for this attribute is -1, what "turns off" this feature.
94
95                        In the corresponding XSD, a group of elements with the same value for exclusivity_group will be rendered inside a <xs:choice> </xs:choice> structure;
96
97                    - *xml_tag* (string)
98
99                        Defines a XML tag name for instance elements that are instance of this definition. If not specified, the XML tag will be the same as the Zope id (converted to lowercase) for this definition object.
100
101                    - *element_name* (string)
102
103                        This is a label that can be presented by the Editor instead of the element's Zope id, what occurs if left blank.
104
105                Methods:
106
107                    - This object has no public methods.
108
109                Events:
110
111                    A SDE-Template-Element object can hold "Python Script" objects that can respond as event handlers to some situations during the document edition. These scripts, to be called automatically be the SDE, must have as "Zope id" one of the following names: "SDE_BeforeDelete", "SDE_AfterInsert" and "SDE_AfterMove".
112
113                    - *SDE_BeforeDelete* (element)
114
115                        This Python Script must have in its parameter list the parameter "element". "element" is the SDE-Document-Element object instance that is going to be deleted.
116
117                        It's invoked before the deletion, in a SDE-Document, of a SDE-Document-Element object corresponding to this SDE-Template-Element object.
118
119                    - *SDE_AfterInsert* (element)
120
121                        This Python Script must have in its parameter list the parameter "element". "element" is the SDE-Document-Element object instance that was created.
122
123                        It's invoked after the creation, in a SDE-Document, of a SDE-Document-Element object corresponding to this SDE-Template-Element object.
124
125                    - *SDE_AfterMove* (element, direction)
126
127                        This Python Script must have in its parameter list the parameters "element" and "direction". "element" is the SDE-Document-Element object instance that was moved, and direction is a string containing "UP" or "DOWN", indicating in which direction "element" was moved to.
128
129                        It's invoked after changing the position, in a SDE-Document, of a SDE-Document-Element object corresponding to this SDE-Template-Element object.
130
131                **Sub-objects:**
132
133                - **SDE-Template-Attribute**
134
135                    This object defines an attribute for a SDE-Template-Element. It's rendered in a XSD as a <xs:attribute> tag, and appears as an element attribute when the document instance is rendered in XML.
136
137                    Properties:
138
139                        - *xsd_type* (list)
140
141                            Defines the attribute's datatype.
142
143                        - *attribute_name*
144
145                            This is a label that can be presented by the Editor instead of the attribute's Zope id, what occurs if left blank.
146
147            - **SDE-Template-Link**
148
149                This object is used to create a link to a SDE-Template-Element. This is used in a template definition to avoid repeating the definition of elements that are necessary in more than one place in the template structure.
150
151                Properties:
152
153                    - *link_to* (string)
154
155                        Contains a relative path to a SDE-Template-Element object. As in a filesystem path notation, it's possible to use ".." to indicate "parent", and "/" to separate object ids.
156
157                    - *optional:* (boolean)
158
159                        Look at SDE-Template-Element -> Properties -> optional
160
161                    - *multiple:* (boolean)
162
163                        Look at SDE-Template-Element -> Properties -> multiple
164
165                    - *exclusivity_group:* (boolean)
166
167                        Look at SDE-Template-Element -> Properties -> exclusivity_group
168
169                Methods:
170
171                    - This object has no public methods.
172
173__________
174
175        - **SDE-Document**
176
177            This is the object used to contain a document. A document is ALWAYS based on a template (SDE-Template). Is the information contained in a template that allows the Editor to guide the user when editing a document.
178
179            It is also a folderish object, and can hold only document elements ("SDE-Document-Element" objects). The order (position) of these elements IS relevant, and you can set it by checking the object(s) you want to move and clicking on "Up" or "Down" buttons in the ZMI.
180
181            Properties:
182
183                - *template_path:* (string)
184
185                    It is the absolute Zope path (starting with "/" to represent Zope's root) for the Zope folder that contains the SDE-Template object used as template for this document instance;
186
187                - *type:* (string)
188
189                    This is the Zope "id" of the SDE-Template object used as template for this document instance;
190
191                - *nextElemId:* (string)
192
193                    This is an internal property, used by the Editor to sequentially create Zope ids for the elements contained in this document instance. The elements are created with ids SDE1, SDE2, SDE3, ...
194
195            Methods:
196
197                - *renderXML* (xsl)
198
199                    If no value is given for the 'xsl' parameter, renders the document in raw XML format. If the 'xsl' parameter is informed, the document is rendered using the XSLT file whose path and name is indicated in this parameter; If you call 'renderXML' with 'xsl=__default__' , the document will be rendered using the XSLT file indicated in the 'default_xslt_for_html' parameter defined in the template object.
200
201                    URLs Examples:
202
203                         'http://your_server/your_document/renderXML' -- renders the document in raw XML format.
204
205                         'http://your_server/your_document/renderXML?xsl=__default__' -- renders the document using the XSLT file defined as default in its template.
206
207                         'http://your_server/your_document/renderXML?xsl=/XSLT/Editor/pl.xsl' -- renders the document using the XSLT file located at /XSLT/Editor/pl.xsl
208
209                    .
210
211                - *renderXMLforEditing* (action, p_id, p_path, p_type, p_pos, xslt)
212
213                    The main inteface for editing documents with SDE is also built using XML and XSLT. The document is rendered by this method in a specific XML structure for edition, and there is a default XSLT file, SD_GenericEditor.xslt, which is used to render this XML and create the editor envinronment in HTML. So, you can fully customize the editor look&feel by creating your own XSLT file or by changing this default one.
214
215                    This method, when called without parameters, renders the document in this specific XML format designed for the editor. Calling it with a parameter 'xslt=__default__' makes it return this XML linked to the XSLT file indicated in the 'default_xslt_for_editor' parameter defined in the template object (usually 'SD_GenericEditor.xslt').
216
217                    This is also the method invoked to make changes in the document. The table below presents possible "Actions" and the necessary parameters for each action type. Please notice that "action" is also a parameter that has to be passed to this method with one of the possible values (in uppercase) presented below.
218
219                    |-------------------------------------------------------------------------------------------------------------------|
220                    |action   |parameters             | description                                                                     |
221                    |===================================================================================================================|
222                    |EDIT     | p_id                  | Renders the element whose id=p_id with the attribute "editing='yes'"            |
223                    |         |                       | Using the XSLT SD_GenericEditor as interface, this element will appear as an    |
224                    |         |                       | HTML textarea object, and the "save" option for it will be visible.             |
225                    |-------------------------------------------------------------------------------------------------------------------|
226                    |MOVE_UP  | p_path, p_id          | Move one position up the element identified by p_id located at p_path           |
227                    |-------------------------------------------------------------------------------------------------------------------|
228                    |MOVE_DOWN| p_path, p_id          | Move one position down the element identified by p_id located at p_path         |
229                    |-------------------------------------------------------------------------------------------------------------------|
230                    |CREATE   | p_path, p_type, p_pos | Creates, under the element p_path, a child of type p_type at the p_pos position |
231                    |-------------------------------------------------------------------------------------------------------------------|
232                    |DELETE   | p_path, p_id          | Removes the element identified by p_id located at p_path                        |
233                    |-------------------------------------------------------------------------------------------------------------------|
234                    |SAVE     | p_path, p_id, REQUEST | Saves the changes to the element p_id located at p_path                         |
235                    |         |                       |                                                                                 |
236                    |         |                       | In the REQUEST object there shall be a form called 'form_edit' containing       |
237                    |         |                       | a object (textarea) called 'txa_text' and several objects (text) named          |
238                    |         |                       | tat_??????, where ?????? is an attribute name (sde_attr)                        |
239                    |-------------------------------------------------------------------------------------------------------------------|
240
241                    URLs Examples:
242
243                         'http://your_server/your_document/renderXMLforEditing' -- renders the document in a specific XML format for edition.
244
245                         'http://your_server/your_document/renderXML?xslt=__default__' -- renders the document using the Editor XSLT file defined as default in its template.
246
247                    .
248
249                - *Validacao*
250
251                    Nao me lembro cumé qui é.
Note: Veja TracBrowser para ajuda no uso do navegador do trac.
 

The contents and data of this website are published under license:
Creative Commons 4.0 Brasil - Atribuir Fonte - Compartilhar Igual.