FW Apps Tutorial - Components

Components take a while to figure out, but they make our lives so much easier as developers. Don't be surprised if this unit takes you longer than either of the others, this unit usually takes developers significantly longer than the previous two units, but components are important to figure out!

Introduce It!

Ember Components are used to reuse blocks of code for abstraction purposes. We use a lot of components in the FW Apps, so understanding how they function is very important. They can either be custom defined by the app itself (in the components folder), by one of our fw packages (in which case the component will have an fw- prefix), or another ember package.

Please refresh yourself on the brief overview on components given above at this time. It can be found at Conceptual Introduction - Client - Components .

Learn It!

Components are the most diverse aspect of ember development. As the overview said, each individual component usually has documentation. Since each component is customized, attributes doing the same thing in one component may be called two slightly different things. This is why finding documentation on the component you are using is important.

Alternatively, looking at an example in one of our apps can also help you to understand certain attributes and how they can be used in context. The one downside with this is that you do not get the full capability of said component, just the parts of the component that are used in that specific context.

To get an overview of components and how they function as a whole, please read the Ember Guides on Components and the Ember API docs on Components.

Note: because of how diverse components are, a vast majority of the Bring It Home section this unit will be showing you different components that we use regularly throughout the Informatics Apps. You will have the opportunity to make your own custom components of specific types as well.

It is important to note that because of the vast nature of components, that we are not able to touch on everything that the Ember Guides talk about. However, I would say that you should keep the Component Lifecycle in mind in your development. You might want to bookmark the link because there are times during Component development that this becomes an invaluable piece of information. In fact, I think I have looked at the Component Lifecycle page of the Ember Guides more than any other single page of the guides over my four years of developing at Informatics. There are many times that knowing which of the hooks for the component lifecycle to use can be invaluable to your development.

Another aspect of successful use of components is understanding addons and dependencies. First of all, an addon is a group of code that is bundled together with the purpose of accomplishing a specific feature, and apps essentially download this code and use it with themselves.

These addons are published as packages through npmjs.com and are available for public use. Dependencies are these addons that are in use in your app. Many times helpful components are introduced through these dependencies and it lessens the work you have to do when creating an app.

Additionally, shared components help the apps to appear much more uniform and consistent from one app to another. Read the Informatics Guides on Updating Dependencies to learn more about dependency upkeep. The dependency blacklist in this guide is always helpful to check after you have updated all your dependencies

Finally, within the components folder, we often make use of two subfolders: “modals” and “cells”. Modals are the popups that appear throughout the informatics apps that are often used to add a model to the database or something similar. It is an extension of the FwFullscreenModal component created by an Ember Framework addon. Then cells is the folder which holds the special components intended to add custom components to a specific cell in a table (using FwTableSortable). This is accomplished by using the cellComponent attribute in the columns array. More on each of these later, but it is helpful to keep these two special components in mind.

I know that this was a lot more information than previous units, but components are a very complex topic. Take it slow, and please reread if you are not understanding something or ask one of the Informatics Developer Admins. Feel free to check back at all the above documentation as you move through the assignments to help bring home what you learned about each of the items.

Bring It Home!

Well, now that you have read a lot of documentation about what a component is and how it functions generally, you will get practice using components! The brightside is that you will be learning to use components. The downside is that you might still need to read some component specific documentation if necessary to understand how components work.

Do not feel that you need to read all of the documentation linked in the “hints” for each of the issues. Just reference the documentation as needed to be able to use these components in your app! You will have some freedom with the icons you use. Please refer to Font Awesome Informatics Reference Sheet (you must be in Informatics department to see this sheet in service stats) and Font Awesome Available Icons to make your decisions about which icons to use for buttons. For now you must use the FA 5 icons (in a later unit you will update to FA 6 like the rest of our apps).

  1. Issue #1: The modal for adding a book is less than ideal, you can’t even input all the information. Please put in inputs for me to add every piece of information to the database necessary (as it is defined in the model). I should be able to save a full book with that modal (and every field of the database should be editable in this modal as well). Please also make sure that the input type matches the data type of the variable.

    • Remember, computed properties should not be set with a textbox.
    • Hint: here are some helpful components that you might use for this kind of data entry (determine which of these you should use given the data type. You may or may not use all of them).

  2. Issue #2: Now that we have a way to add the books to the database nicely, please use a sortable table to display the books that have been added in this department. This should be on the books page. I want the table to display all of the information from the books model, but most of it should be hidden. On jumbo, I want to be able to see: Title, Author, Pub Date, Genre, and Location without expanding a row. On a tablet or desktop, I want to be able to see: Title, author, pub date, and genre without expanding the row. On a mobile, I want to see: title and author without expanding a row. I also want an edit and delete action (just with the typical icons) to be able to edit or delete a book that I have added.

    • In order to do this, you will need to add the package @bennerinformatics/ember-fw-table to your package.json. Please refer to the setup information for it in the Ember FW Table Documentation.
    • Hint 1: These books are already fetched for you since you haven’t learned routing yet. The variable "model" contains all of the books for the current department.
    • Hint 2: You may want to look at this documentation to know how to build a sortable table: FwTableSortable. You may also need to use the FwDeleteModal at some point as well.

  3. Issue #3: The Training App needs to have a help menu. All apps have it, but it hasn’t been added yet. To start with, the Help menu should be a dropdown of four links (we will add to it later): Icons Key (which links to library website), Known Issues, Report an Issue, and Version History (all three of which link to Issue Tracker). Look at any of the other apps for help for how to do this (note: we are skipping Permission Page, Documentation, and FAQ for now).

  4. Issue #4: I need to have a modal to check out a book. On the main page in the first panel, I would like to have a dropdown, which has options of the available books to be checked out. Then there should be a "Checkout Book" button underneath this dropdown, which opens up a modal. The button should only be clickable if a book is selected for checkout in the dropdown. Then the modal should open up to fill out the other checkout information (patron information and due date).

    • Hint: Checkout this documentation if you need help. The components linked in Issue #1 may be helpful for you in determining which input types to use for this issue as well.
    • Hint 2: Make sure the client side name on the model and the server side name of the alias match.

  5. Issue #5: The panel displaying all books is not really the purpose of this app. Please replace this panel with a table, which displays all of the books that are currently checked out. The actions for this table should include a renew, return, and edit. The edit should bring up the modify-checkout modal. The return should just be a verification modal, then remove the checkout record. The renew should pop up a modal where you select a new due date, then it saves and marks as renewed. Please choose the most relevant fields to display, and put the others in the expanded row. Also consider what might look good on a mobile version of the app.

    • Hint: you have already received hints on all that you need for this section, figure out which components that you already learned would be helpful to fix this issue.

  6. Issue #6: The pages of this app are missing the loading spinner. Each template should have a loading page, so I can tell something happens when I am transitioning between pages.

  7. Issue #7: Please put an i button next to the label for the dropdown to select available books. I want it to let people know that only the non checked out books are options.

  8. Challenge (Remember only do this if you have completed all the other parts of this unit and have extra time): Create a way to format the cells in such a way that if a book is overdue, that row sticks out quite a bit. You can be creative with this section, but it should be obvious that a particular row is overdue or not.

Check It!

Now that you have learned about and practiced with Components, please let one of the developer admin know. They will fork the training-developer-component-fork, so you can see the answers for this unit. 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.

After you have sufficiently checked your code, make sure you have pushed all your changes to bitbucket (on the old repository), and then please delete your trad folder, and complete the Install App For Development for the new repository with the answer code. After you have sufficiently downloaded and installed this app, you are ready to continue to the next Unit when you get the go ahead from the developer admin.