| 1 | .. _documents: |
|---|
| 2 | |
|---|
| 3 | Documents Section |
|---|
| 4 | ***************** |
|---|
| 5 | |
|---|
| 6 | The documents section of Kofa is a tiny built-in content management |
|---|
| 7 | system (CMS), which has been developed mainly for publishing |
|---|
| 8 | announcements, adverts, instructions or general information provided |
|---|
| 9 | by the university to inform prospective students about application |
|---|
| 10 | and registration procedures. |
|---|
| 11 | |
|---|
| 12 | Technically 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 | |
|---|
| 22 | The first can be used to provide pdf files for download. The second |
|---|
| 23 | and third can be used to create multi-lingual static html pages on |
|---|
| 24 | the portal. HTML documents expect html coded text as input, REST |
|---|
| 25 | documents expect `reStructuredText <http://docutils.sf.net/rst.html>`_ |
|---|
| 26 | which is transformed into html. |
|---|
| 27 | |
|---|
| 28 | Interfaces |
|---|
| 29 | ========== |
|---|
| 30 | |
|---|
| 31 | The base for all three document interfaces is `IPublicDocument` |
|---|
| 32 | which inherits from `IDocument`. All attributes are read-only |
|---|
| 33 | properties, i.e. attributes with a getter method only. These |
|---|
| 34 | properties 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 |
|---|
| 36 | imported. |
|---|
| 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 | |
|---|
| 44 | A PDF Document further specifies which pdf files are connected to |
|---|
| 45 | the object. Usually, only one filename is in the `filenames` tuple. |
|---|
| 46 | |
|---|
| 47 | .. literalinclude:: ../../../src/waeup/kofa/documents/interfaces.py |
|---|
| 48 | :pyobject: IPDFDocument |
|---|
| 49 | |
|---|
| 50 | HTML and REST documents have a schema field for multi-lingual |
|---|
| 51 | content in HTML or in REST format respectively, see :ref:`note |
|---|
| 52 | <multilingual>`. The hidden `html_dict` attributes contain the same |
|---|
| 53 | information after saving the form, but the sequence of language |
|---|
| 54 | translations has been split up and copied into a dictionary for |
|---|
| 55 | faster 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 | |
|---|
| 64 | Workflow |
|---|
| 65 | ======== |
|---|
| 66 | |
|---|
| 67 | Public documents have a publication workflow with two states: |
|---|
| 68 | created and published. Only the content or attached files of |
|---|
| 69 | published documents can be seen by anonymous users:: |
|---|
| 70 | |
|---|
| 71 | a |
|---|
| 72 | created ----------- published |
|---|
| 73 | |
|---|
| 74 | a: publish |
|---|
| 75 | -a: retract |
|---|
| 76 | |
|---|
| 77 | History & Logging |
|---|
| 78 | ================= |
|---|
| 79 | |
|---|
| 80 | All transitions are automatically logged in ``main.log`` and the |
|---|
| 81 | document'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 | |
|---|
| 87 | The 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 | |
|---|
| 98 | Quick Guide |
|---|
| 99 | =========== |
|---|
| 100 | |
|---|
| 101 | How to add and reference an HTML document |
|---|
| 102 | ----------------------------------------- |
|---|
| 103 | |
|---|
| 104 | 1. Click *Documents > Manage > Add document*. |
|---|
| 105 | 2. Select *HTML Document*, fill fields and press *Add document*. |
|---|
| 106 | 3. Enter multi-lingual content in HTML format and press *Save*. |
|---|
| 107 | 4. Click *View > Transition*. |
|---|
| 108 | 5. Select *Publish document* and press *Save*. |
|---|
| 109 | |
|---|
| 110 | The document is now published and available to anonymous users. |
|---|
| 111 | |
|---|
| 112 | 6. Mark and copy the HTML Element provided on the page: |
|---|
| 113 | ``<a href= ... /a>``. |
|---|
| 114 | 7. Open another HTML document or a page with multi-lingual content |
|---|
| 115 | and paste the element where needed. |
|---|
| 116 | |
|---|
| 117 | |
|---|
| 118 | How to add and reference a PDF document |
|---|
| 119 | --------------------------------------- |
|---|
| 120 | |
|---|
| 121 | 1. Click *Documents > Manage > Add document*. |
|---|
| 122 | 2. Select *PDF Document*, fill fields and press *Add document*. |
|---|
| 123 | 3. Select *Files* and upload a pdf file from your computer. |
|---|
| 124 | 4. Click *View > Transition*. |
|---|
| 125 | 5. Select *Publish document* and press *Save*. |
|---|
| 126 | |
|---|
| 127 | The document and the connected pdf file are now published and |
|---|
| 128 | available to anonymous users. |
|---|
| 129 | |
|---|
| 130 | 6. Open the HTML source with your browser, search for the ``a`` |
|---|
| 131 | element |
|---|
| 132 | 7. Mark and copy the HTML element found: |
|---|
| 133 | ``<a target="image" href= ... /a>``. |
|---|
| 134 | 8. Open another HTML document or a page with multi-lingual content |
|---|
| 135 | and paste the element where needed. |
|---|
