Developer? Help Us Build This Page!

Developer? Help Us Build This Page!

If you would like to contribute to the project, you can help us by programming this page. Please start by reviewing the files in the Official Apoidea Repository↗. Once you find an area to contribute, you can contact us or login to Codeberg. Find the issue corresponding to the page URL and submit a comment stating your intent to finish the page and what your plan for the content is. Right now we're focused on the front-end, but the architure and database tables are ready for business logic development as well. Lets have a chat!

Once we talk about your contribution, please make a fork of the project for your edits and only submit a pull request once you are happy with it.

Note: The front-end architure works off Jinja2 templates, and this template is for the main content block appearing between the header and footer, and to the right of the sidebar.

Page Setup

• 1. Clone your forked repository in your IDE.
• 2. If they doesn't exist, create category folders in web/src/view and web/static/js corresponding to the main menu headers, snake_case please.
• 3. Copy this template into the new src folder and rename it according to the link href in web/src/view/partials/_sidebar.html.
• 4. Copy web/static/js/content_template.js into the new js folder and rename it to match your HTML document name.
• 5. Update your HTML file to point at your new Javascript module (at the bottom).
• 6. Open web/src/router.py and find the 'content_template' function. The route to your page should appear in a @decorator above the function. Use the content_template function as a template to direct flask to render your new html file with a unique function name. Move the decorator from the content_template function to your new routing function.
• 7. Start the website using 'docker compose up --build'. You may need to install docker and docker compose.
• 8. Access the website on localhost or your machine's port 80 through your local network. If everything works correctly, tailwind watch will immediately update your css file with changes to your HTML and Javascript as you develop your page. You simply need to refresh the browser.
• 9. If you need to fix the flask route, you can restart the web app with 'docker restart v01-web-1'.

Section Setup

The pages are divided into sections in a column, with tools grouped into appropriate categories in each section. The app has a Quick Access feature that allows users to configure shortcuts to specific pages and page sections from the top navbar.

• 1. Find the word 'TEMPLATE' in all caps at the top of the HTML document. Replace this with the appropriate page name.
• 2. Find the word 'INSTRUCTIONS' in all caps at the top of the HTML document. Replace this with your first section name.
• 3. Replace the element id tags, taking care to follow the established naming pattern. e.g. 'pageName-sectionName-qa-add'
• 4. Add additional sections with the same pattern. Content styling blocks are provided for copying.
• 5. Add your page and sections to the qaIcons array near the beginning of web/static/js/utils.js.
• 6. Find icons from HeroIcons for your page and headers and install them by following the pattern in web/src/view/partials/_navbar.html. Please ensure that they appear in the order the appear in the sidebar menu, with page section groups sorted by the order they appear on the page. E.g. To add the journal: Finance-Journal(page), Journal-New(section 1), Journal-History(section 2) Be sure to update the svg class to match the sizing of the other icons. You can use other free icon libraries, but be sure to credit the source in the HTML and place the license file in web/media/licenses/.
• 7. Build your content. Chart.js charts can be created with the Chart class (let thisChart = new Chart(canvas,config);), available in all modules. You can find component templates from DaisyUI.
• 8. Ensure your page is responsive on mobile. The project uses a single breakpoint at tailwind medium, or 768 pixels wide on standard settings. If your phone or tablet is on your local network you can view the site by going to port 80 at your development machine's local IP address. Find it by typing 'hostname -I' into a bash terminal on your development machine, and your IP will be the first 4-number address listed. Go to 'http://[your_local_ip]:80' on your mobile devide. Alternatively, hit F12 on your desktop browser and click the phone icon near the bottom. Please ask if you have any questions about this implementation.
• 9. If you add a Python package to requirements.txt, please run pip_licenses.sh with your project fork running. The script will extract the license data from the running web application container and generate the new table for the Python license modal. Verify the new package is now included on the Python modal on the Partners page.

Resources

• 1. W3 Schools (HTML/Javascript/Python/Chart.js)
• 2. Tailwind v4 documentation (HTML element classes for the CSS compiler)
• 3. DaisyUI Project Page (Docs and component templates)
• 4. Chart.js Documentation (Chart rendering)
• 5. Hero Icons (Solid icons preferred)
• 6. web/src/models/tables.py contains table definitions for the database, defined as SQLAlchemy classes. The classes have extensive implementation notes that may be useful when developing pages. Please ask if you have questions about what is relevant to your contribution area.

Submission

When you are satisfied with your page, submit a pull request in response to the issue and we will review it as soon as we are able.

With our sincere gratitude,

Apoidea Group