| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| documentation:rack:start [2018/05/25 19:18] – [Options] Martijn Luinstra | documentation:rack:start [2022/04/03 16:00] (current) – external edit 127.0.0.1 |
|---|
| * User authentication through the Cover API | * User authentication through the Cover API |
| |
| ===== Installation ===== | Future improvements: |
| | * [[https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)|CSRF]] protection (this is a desired feature). |
| | * Escaping values by default in templates. |
| | * Broader coverage of HTML [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_<input>_types|form input types]] |
| | * …and more! Please share your suggestions [[https://bitbucket.org/cover-webcie/rack/issues|here]]. |
| | |
| | Rather than providing a fully-featured API, Rack aims to provide just enough functionality to cover the basic needs. Projects with more complicated requirements should extend, subclass and/or override Rack code where needed to add functionality. |
| | ===== Getting Started ===== |
| | |
| | ==== Installation ==== |
| |
| Clone (or fork or download) the [[https://bitbucket.org/cover-webcie/rack/|Bitbucket repository]] into the root folder of your project and you're ready to go! | Clone (or fork or download) the [[https://bitbucket.org/cover-webcie/rack/|Bitbucket repository]] into the root folder of your project and you're ready to go! |
| |
| ===== Project structure ===== | ==== Project structure ==== |
| |
| Projects using Rack adhere to the following structure: | Projects using Rack adhere to the following structure: |
| The ''include'' folder is meant Rack's internal logic and possible application-specific extensions to it. It should not contain any views, templates or static files. | The ''include'' folder is meant Rack's internal logic and possible application-specific extensions to it. It should not contain any views, templates or static files. |
| |
| ===== Configuration ===== | ==== Configuration ==== |
| | |
| | A config file ''include/config.php'' is needed for Rack to work properly. A default configuration is provided in ''include/config.php.default'' which can be copied to initialize the ''config.php'' file. Remember that this config file is likely to contain passwords, so it should be added to the ''.gitignore'' file to prevent it from showing up in Git repositories. Do not forget to change it's file permissions to hide it from other users on the system. This can be done with the following command: ''chmod 700 include/config.php''. All available configuration options are listed [[documentation:rack:reference:config|here]]. |
| | |
| | ==== Creating views ==== |
| | |
| | Now, you're ready to create views. A view is a ''php'' file in the project's root folder. Every view should include (or require) the ''include/init.php'' file, to load the Rack functionality. An example of a view that renders the template ''templates/index.php'' is provided below: |
| | |
| | <file php index.php> |
| | <?php |
| | require_once 'include/init.php'; |
| | |
| | // Create and run home view |
| | $view = new TemplateView('index'); |
| | $view->run(); |
| | </file> |
| |
| To work, a config file ''include/config.php'' is needed. A default configuration is provided in ''include/config.php.default'' and can be copied to initialize the ''config.php'' file. Remember that this config file is likely to contain passwords, so it should be added to the ''.gitignore'' file to prevent it from showing up in Git repositories. Do not forget to change it's file permissions to hide it from other users on the system. This can be done with the following command: ''chmod 700 include/config.php''. | |
| |
| ==== Options ==== | ==== Glossary ==== |
| This table lists all configuration options implemented by Rack. If you implement any configuration options or use an external library that does, you use the ''config.php'' file for this as well. | |
| |
| ^ Name ^ Required ^ Default ^ Description ^ | * **Committee login**: The internal mnemonic ID of a committee. It can be found as the value of the ''committee parameter'' in the url of the committee page on the Cover website. For example, login for the AC/DCee is ''webcie'' as can be seen in their url https://www.svcover.nl/commissies.php?commissie=webcie. Their is no guaranteed relationship between a committee login and its account name on the server, but there is always a working email address ''committee_login@svcover.nl''. |
| | ADMIN_COMMITTEE | | <php>'webcie'</php> | The //login// of the committee that should have admin access. It's the identifier used in the url of your committee page on the Coversite. | | * **Committee name**: The real name of a committee. Like AC/DCee, IntroCee or StudCee. |
| | ADMIN_EMAIL | | | The email address of the admin committee. | | * **Cover API**: The API of the Cover website, accessible through https://www.svcover.nl/api.php |
| | COVER_APP | Y | | The name of the application, used for authentication. | | * **Cover session**: The session of a logged in user of the Cover website. |
| | COVER_API_URL | | <php>'https://www.svcover.nl/api.php'</php> | The url of the Cover API. Usually, this doesn't need to be set. | | * **Cover website**: Cover's home on the web, https://www.svcover.nl |
| | COVER_COOKIE_NAME | | <php>'cover_session_id'</php> | Name of the cookie used to identify the Cover session. Usually, this doesn't need to be set. | | |
| | COVER_LOGIN_URL | | <php>'https://www.svcover.nl/sessions.php?view=login'</php> | The Coversite login url. Usually, this doesn't need to be set. | | |
| | COVER_LOGOUT_URL | | <php>'https://www.svcover.nl/sessions.php?view=logout'</php> | The Coversite logout url. Usually, this doesn't need to be set. | | |
| | COVER_SECRET | Y | | A shared secret between your app and the Coversite. You can obtain one through the [[committee>webcie|AC/DCee]] | | |
| | ERROR_TEMPLATE | | <php>'templates/error.phtml'</php> | Te name of the template used to render errors. | | |
| | DB_DSN | Only for DB | | The connection string for your database. Looks like <php>'mysql:host=localhost;dbname=committeedbname'</php> | | |
| | DB_USER | Only for DB | | Your database username. | | |
| | DB_PASSWORD | Only for DB | | Your database password. | | |
| | SERVER_NAME | Y | | The url of the application, used for authentication. | | |
| |
| ===== API Reference ===== | ===== API Reference ===== |
| |
| The following pages contain short documentation of the available classes and functions. They are meant to provide an overview of the features and dataflows. Anybody in need of implementation specific detail is advised to inspect the source code. | {{page>documentation:rack:reference:start&noheader&nofooter}} |
| |
| * [[documentation:rack:reference:views|Views]] | ====== Versions ====== |
| * [[documentation:rack:reference:templates|Templates]] | * 1.1 (2019-05-10, Current) |
| * [[documentation:rack:reference:forms|Forms]] | * Added CSV view to ''ModelView''. |
| * [[documentation:rack:reference:models|Models]] | * Added optional Sentry support. |
| * [[documentation:rack:reference:sessions|Cover API]] | * ''Model->create()'' now returns the inserted ID. |
| * [[documentation:rack:reference:misc|Miscelaneous]] | * Various minor improvements/fixes |
| | * 1.0 (2018-05-26) |
| | * Initial version, based on various projects. |
| |