FW Apps Tutorial - Server & More

Congratulations! You have finished your in depth training about the FW Apps client side interaction. Now it is time to put it all together!

Introduce It!

You have read a lot of documentation about the various aspects of an FW App from a variety of sources, including Ember and Informatics Documentation. Now there is one final unit for you to do. This unit will have even less guided practice as it is expected that you have learned a lot over the next five units. The final piece of the puzzle is understanding the database and the serverside. While this may seem like a lot, I think you are up for the challenge.

Learn It!

Since our serverside is very custom to us, there is not a lot of other material that explains the Informatics FW Serverside exactly. For further learning go back through the Conceptual Introduction - Server and Conceptual Introduction - Database When you go through it, make sure to read the links in the tutorials that you desire more information on. After this, I think you are ready for your challenge. If you would like more detailed information than the Conceptual Introduction provides, the FW Main Docs, go quite in depth into the server, so that would be the next place to look to see more. This is not required reading, but just for reference. You should reference for more depth:

Note: As this is the last unit of your development training, these issues will build upon all that you have learned previously. If you don’t remember how to do something feel free to look back at previous units. Also, there are some advanced features about Informatics development that are covered in this unit’s bring it home. Because it is a “challenge” unit, each issue that asks you to do something you did not learn about clientside or serverside, will also give links of documentation you can read in order to learn how to fix the issue. The issues are also more vague than in previous units, and look more like an issue you might hear from Matt or Ann.

Good luck, and please, if you have any questions do not hesitate to ask the developer admin at all.

Quick Tip for Debugging in PHP: An indispensable aspect of PHP development is the command die() and var_dump(), and these are often used together.

  • die() kills the code at that specific line and returns to the Network Request you are working on whatever string you put inside (for information on how to view this see here). Using die without var_dump() will be used only occasionally to test if the code reaches a certain point. More information on PHP die command can be found here.
  • var_dump() dumps information about a variable including type and also value as a string, so that it can be used with die. I have never used var_dump() by itself. More information on this command can be found here.
  • die(var_dump()) then is your best friend to return any kind of variable to make sure it is what you think it is. Unfortunately, it will not allow you to resume the execution of the script afterwards, like Javascript debugger, but it is the single best debugging tool available for serverside development.

Bring It Home!

Good luck with your final challenge! This probably has slightly less guidance than previous units (especially for client side) because it assumes that you know what you are doing with client side. If you need help, don’t hesitate to refer back to previous units to remind yourself about how to do a certain thing with Ember. Informatics and Ember documentation should be a tool for you to use wisely!

  1. Issue #1: Make your own model, “fine”. In this stage you will need to make a new database table (make sure to follow Database Naming Conventions), a Serverside Model, a Serverside Controller, a Serverside Route, and a Clientside model. Feel free to use the other models in the training app as reference for how to do certain things. This model should have an ID which is automatically incrementing, an amount, the employee who checked it out, the department the fine was assigned in, the checkout record the fine was assigned to, whether this fine freezes the patron account, and when the fine was paid (if it has been).
  • Writing Database Migrations. For the purposes of this tutorial, you should act as if this is the same release as the release which initially created Migration 1.
  • Note: This is only the "backend" side of things, so you will not be able to test your changes until you complete the clientside aspect in Issue 2.

  1. Issue #2: Make an Admin dropdown on the menu bar. Underneath it should be the Books page, and also a new page. Make sure the admin pages have the Admin tools panel as is custom in the apps. This new page should be called Fines. You should be able to see a table of the unpaid fines, add a new fine (you should only be able to add a fine to a checkout record that is overdue), record a fine as paid, and filter through the paid fines (filter means doing a javascript only search, not making a browse request to the database).

  2. Issue #3: There should be an email sent out to a patron whenever a fine is added to their checkout, or whenever it is paid. This uses a serverside addon called Mail Core. Checkout the following links for some extra help:

  3. Issue #4: Since in our app, we mainly focus upon the date something happens and not the time, to save room in the database, we should change all the datetime fields to only save the date and not the time. The only exception to this is the checkout date should also keep the time…

  • Note: Ordinarily, this would be on the same database migration file because it is the same release, but just for practice for this app (so that you can have practice both making a new migration and editing an existing one), let's pretend that you made a release since your last database migration change in Issue 1. Therefore, this change, and future changes should be in Database Migration Two. If you need help, see the Writing Database Migrations linked under Issue 1.

  1. Issue #5: There are a couple of tweaks that need to be made with the permissions in the app. Each of these should be done in order to make the app better for everyone:

    • First of all there is a bug with Checkouts in which base users are not allowed to checkout, renew or return a checkout. But a base user should be able to do everything to a Checkout record that an admin can.
    • Secondly, some of our developers have figured out how to use the direct API call to view the fine information for patrons. This is private information. Base should not be able to view Fine models through network requests. (this may have already been done depending upon how you coded Issue #1)
    • Finally, we want to add a supervisor role to this app. We want to be able to give permission to someone to do all the things regarding fines and see the Fine page, but not have access to all admin functionality on the book page. Therefore, make a "supervisor" role that has access to all the functionality of fines, and anything the base role can do, without having access to the Book page.
    • Hint: look at serverside BREAD requests for the Fine and Checkout model. This documentation on authenticating requests should help you a little bit.
    • For testing: create a new supervisor user to test the things a supervisor should be able to do with Fines, and use a base user to make sure they can test out, and can't do anything with fines.

  2. Issue #6: So because the fines depend on checkout records now, “Returning” a book should not actually delete the checkout record. For historical purposes, it should just set the return date. Now, you should only see CURRENTLY checked out books on the check out page, and only CURRENTLY checked out records should be able to have a fine added, but fines should not be deleted once the book has been returned (and you should still be able to see all the checkout information as well on the fine).

  3. Issue #7: Many times when you are developing, you will need to make an update on the basis of things that the lead developer has done to our @bennerinformatics packages. So this issue is a simulation of one such update that you might need to do. If you have helped already with a apps-wide update while you are training, check with the dev admin to see if you can skip this issue or not. Here is an example update:

    • Make sure all your @bennerinformatics packages are up to date (this requires you checking the highest version in bitbucket, and it is entirely possible that these changes will not be fully reflected in the answer key, as time has passed since it was coded, and there may have been future updates).
    • Back in Spring 2024, we did an update in which we updated our Font Awesome Package from Fontawesome 5 to Fontawesome 6. This required the change of all the class names for the icons we used throughout the apps. Among other things, these were the main things that changed:
    • In general the prefix fas changed to fa-solid, far changed to fa-regular, and fab changed to fa-brands
    • Additionally, some icons changed class name entirely (ie far fa-save changed to fa-regular fa-floppy-disk)
    • Thus, your task is to update all of the icons within this app to reflect the new Font Awesome 6 syntax (rather than Font Awesome 5). To aid in your task, you may find the Fontawesome Stylesheet Reference Service in Service Stats to help you (it has for each icon both the old FA5 class name and the new FA6 class name).
    • Note: From time to time there will be periodic updates to our ember packages, and you will have to do certain things to your code. Usually, the lead developer or whoever made the change will send you a list of things to do, like what you see above.

  4. Issue #8: The add/edit book modal looks really ugly. The admin want to be able to see the save and close buttons on the screen without scrolling. To do this, the body of the panel will need to be able to scroll rather than using the big scrollbar on the side of the screen.

  5. Issue #9: If there is a serverside error, right now, our promise buttons just show a red x. Any time there is a red x, it should display the error from the server using fw-notifications. So go through the app, and any network request, catch the error (if there is one) and display the notification to the proper notification outlet. Secondly, there is no Server Side error thrown when trying to pay a fine, but the client should error and not allow it to save from pay-fine modal if there is no paidAt date.

    • Hint: Docs for FW Notifications system can be found here.

  6. Issue #10: An employee should be able to check out multiple books at the same time to the same patron. There are multiple ways to do this, but I would like the current dropdown to just be able to select multiple books, and then the save will save each of the checkout records that are made for each of the different books.

  7. Issue #11: The Add/Edit Book Modal should really have validations with it, not just a notification of the serverside error that is thrown. That way, the end user can see exactly which inputs are missing data and they need to fill out.

    • Note: ordinarily we would also have validations for the checkout modal, but a modal that saves multiple records does not work with our FW Validations system. The modal must only save one model in order to be a candidate for this system.
    • Hint: here is the documentation for FW Validations.

  8. Issue #12: I want a button to send a reminder email if a book is overdue. This button should pop up a modal with a place to type an additional note. The only action the button should do is call a serverside function to send an email. This button and corresponding action should only be able to be done by someone with the admin or the supervisor role (not the base role).

    • Hint: Read this document for a general overview of how to do this and checkout the Ajax and Config Service documentation for function specific help.
    • Note: While most of our apps don’t do this, an email request should probably be a post request to keep sensitive information (such as email addresses) out of query parameters.
    • The email should read something to the effect of:
{Patron Name},
Your Book, {Book Title}, was not returned on time. This is a friendly reminder for you to return it at your earliest convenience.

"This is an extra note, which is type in by the employee."
--{Employee Name}

  1. Issue #13: In this unit, we have made several updates to the actions which specific roles have access to. Thus, in the interest of keeping the Permissions Page up to date, please update it with all of the changes that have been done throughout the app in this unit. If you need help with this, you can look at other apps to see what kinds of actions are included in the permissions page, and what is not. This should be kept up to date (for every release you make, you should consider if anything on this page needs to be updated).

  2. Issue #14: Our new policy for multiselects is that they should not close when an item is selected, but rather they should close when you click outside of them. This way they can stay open for multiple different selections. There is a way to do this very easily in PowerSelect, see if you can find it in the Ember PowerSelect docs, which are here (note: the api-reference is very helpful for determining all the available options in PowerSelect). You can also check how other apps do it if you would prefer.

Check It!

As you are now well aware, please check your answers with the answer fork. Please let one of the developer admin know and they will give you access to the training-developer-serverside-fork. Please compare your code and anywhere your code differs more substantially than a variable name, note the differences and understand why that code was written in that way by the lead developer. While yours may not necessarily be “wrong” there may be a better or more “Informatics” way of doing it. Feel free to ask whatever questions you desire about this to any of the Informatics Admin.

Note: the answer to Serverside Issue #3 does not have the proper file change to the server/config/app.php as directed in the Mail Core installation guide. This is because the Mail Core Installation guide had not been written when the answer key was coded. While this step is not crucial to the running of Mail Core, it is better if it is set up as instructed in the guide. So please excuse the imperfections of the answer key and realize that YOUR issue #3 should have the changes to that configuration file!

After you have sufficiently checked your code, you may move on to the final unit. Make sure to use the answer-key code for training-developer-serverside-fork, not your own code, for the next unit, as this will be where you make your changes live on the testing website! You are almost done with the training, the biggest part is behind you, just one more step to complete before you are a full fledged developer for Informatics!