source: main/waeup.kofa/trunk/docs/source/userdocs/documents.rst @ 15128

Last change on this file since 15128 was 13178, checked in by Henrik Bettermann, 9 years ago

Restructure index page and modify README.txt again.

File size: 4.9 KB
Line 
1.. _documents:
2
3Documents Section
4*****************
5
6The documents section of Kofa is a tiny built-in content management
7system (CMS), which has been developed mainly for publishing
8announcements, adverts, instructions or general information provided
9by the university to inform prospective students about application
10and registration procedures.
11
12Technically speaking, the documents section is a container of type `DocumentsContainer` with id ``documents``, which is located in the `IUniversity` instance and which contains public documents. There are three types of public documents::
13
14  Documents Section (DocumentsContainer)
15  |
16  +---> PDFDocument
17  |
18  +---> HTMLDocument
19  |
20  +---> RESTDocument
21
22The first can be used to provide pdf files for download. The second
23and third can be used to create multi-lingual static html pages on
24the portal. HTML documents expect html coded text as input, REST
25documents expect `reStructuredText <http://docutils.sf.net/rst.html>`_
26which is transformed into html.
27
28Interfaces
29==========
30
31The base for all three document interfaces is `IPublicDocument`
32which inherits from `IDocument`. All attributes are read-only
33properties, i.e. attributes with a getter method only. These
34properties are computed dynamically and can't be set. Only the
35`document_id` and the `title` can be entered on form pages or can be
36imported.
37
38.. literalinclude:: ../../../src/waeup/kofa/documents/interfaces.py
39   :pyobject: IDocument
40
41.. literalinclude:: ../../../src/waeup/kofa/documents/interfaces.py
42   :pyobject: IPublicDocument
43
44A PDF Document further specifies which pdf files are connected to
45the object. Usually, only one filename is in the `filenames` tuple.
46
47.. literalinclude:: ../../../src/waeup/kofa/documents/interfaces.py
48   :pyobject: IPDFDocument
49
50HTML and REST documents have a schema field for multi-lingual
51content in HTML or in REST format respectively, see :ref:`note
52<multilingual>`. The hidden `html_dict` attributes contain the same
53information after saving the form, but the sequence of language
54translations has been split up and copied into a dictionary for
55faster processing.
56
57.. literalinclude:: ../../../src/waeup/kofa/documents/interfaces.py
58   :pyobject: IHTMLDocument
59
60.. literalinclude:: ../../../src/waeup/kofa/documents/interfaces.py
61   :pyobject: IRESTDocument
62
63
64Workflow
65========
66
67Public documents have a publication workflow with two states:
68created and published. Only the content or attached files of
69published documents can be seen by anonymous users::
70
71                 a
72    created ----------- published
73
74    a: publish
75   -a: retract
76
77History & Logging
78=================
79
80All transitions are automatically logged in ``main.log`` and the
81document's history. This is a sample history of public document::
82
83  2015-07-05 07:31:32 UTC - Document created by Admin
84  2015-07-05 07:31:53 UTC - Document published by Admin
85  2015-07-05 07:31:57 UTC - Document retracted by Admin
86
87The corresponding logfile excerpt is as follows::
88
89  2015-07-05 09:31:32,848 - INFO - admin - demodoc - Document created
90  2015-07-05 09:31:32,850 - INFO - admin - documents.browser.DocumentAddFormPage - added: HTML Document demodoc
91  2015-07-05 09:31:39,025 - INFO - admin - documents.browser.HTMLDocumentManageFormPage - demodoc - saved: html_multilingual
92  2015-07-05 09:31:43,279 - INFO - admin - documents.browser.HTMLDocumentManageFormPage - added: benny|waeup.local.DocumentManager
93  2015-07-05 09:31:53,152 - INFO - admin - demodoc - Document published
94  2015-07-05 09:31:57,216 - INFO - admin - demodoc - Document retracted
95  2015-07-05 09:32:46,679 - INFO - admin - documents.browser.DocumentsContainerManageFormPage - removed: demodoc
96
97
98Quick Guide
99===========
100
101How to add and reference an HTML document
102-----------------------------------------
103
1041. Click *Documents > Manage > Add document*.
1052. Select *HTML Document*, fill fields and press *Add document*.
1063. Enter multi-lingual content in HTML format and press *Save*.
1074. Click *View > Transition*.
1085. Select *Publish document* and press *Save*.
109
110The document is now published and available to anonymous users.
111
1126. Mark and copy the HTML Element provided on the page:
113   ``<a href= ... /a>``.
1147. Open another HTML document or a page with multi-lingual content
115   and paste the element where needed.
116
117
118How to add and reference a PDF document
119---------------------------------------
120
1211. Click *Documents > Manage > Add document*.
1222. Select *PDF Document*, fill fields and press *Add document*.
1233. Select *Files* and upload a pdf file from your computer.
1244. Click *View > Transition*.
1255. Select *Publish document* and press *Save*.
126
127The document and the connected pdf file are now published and
128available to anonymous users.
129
1306. Open the HTML source with your browser, search for the ``a``
131   element
1327. Mark and copy the HTML element found:
133   ``<a target="image" href= ... /a>``.
1348. Open another HTML document or a page with multi-lingual content
135   and paste the element where needed.
Note: See TracBrowser for help on using the repository browser.