A new admin interface for OFN

Tech Wishlist
1

Hi folks :wave:

I’ve been lurking around OFN for a few months after meeting Danni here in Melbourne, and I’ve also had a number of video chats with Pau. I’ve been pondering what I can contribute and have finally come up with a proposal about that, please have a read :slight_smile:

My impression is that the existing admin user interface is rather complicated and cluttered, making it hard for users to understand unless they are intimately familiar with the software. This is likely to put off potential new users of OFN, as well as increase the burden of support queries. (I’d be happy to detail specific complaints but that may not be necessary if this perspective is not contentious.)

There are various open source admin frameworks available which provide well-designed, reusable components which can be used to build user interfaces. Using one would save time writing and maintaining CSS, allowing us to focus on the more bespoke aspects of OFN.

I recently began to explore what it would take to incrementally replace the existing admin views with ones based on Tabler.

I very quickly realised that it would not make sense to only put “a lick of paint” on the current admin interface. I am not convinced that every feature in the current interface is necessary, useful, or the most appropriate solution. So to avoid wasted effort, I think it would make sense to reconsider these solutions as part of the process of overhauling the interface, starting from research and consideration about what user needs they are actually trying to solve.

(A basic example: the current users list interface allows the columns of the table to be sorted. Is this solving a user need? Is time well spent maintaining this as part of an interface overhaul?)

So rather than considering this as only a view-layer change, I see this as a project to build a new admin interface alongside the existing one, and then eventually replace the existing one with the new one. (With plenty of iteration and user testing along the way.)

I did a very basic “spike” in a branch here, to explore the technical implementation details: https://github.com/openfoodfoundation/openfoodnetwork/compare/master...jonleighton:ui-overhaul-spike

1600×1054 136 KB

(Note that most of the links in this screenshot don’t do anything! It’s nowhere near feature complete.)

The code is implemented as a Rails engine. This means that none of the existing code needs to change for now. The engine is mounted at /admin/next to allow for early-stage testing. When it is more feature complete, we could allow users to switch between the legacy interface and the new one. This would allow for more comprehensive testing before removing the legacy version.

So here’s what I’m proposing:

  • To embark on a project to rebuild the OFN admin interface with a focus on user needs and usability.

  • To build it in a Rails engine, allowing the new code to coexist alongside the legacy code, so that the new code can be merged frequently and tested by users as we go along, rather than maintaining a long-running branch.

  • I think that the new interface should default to using ordinary server-side rendering and Rails views as much as possible. This will keep the complexity down, making it faster to build and easier to maintain. Where more interactivity is required, this should be driven by analysis of actual user needs. I would favour lightweight approaches to adding JS behaviour, such as Stimulus, but if there’s a strong case for something more heavy-duty, then individual parts of the interface could be built using React or similar without needing to build everything in React.

  • I’m aware that there is an ongoing effort to break up the code into “domains” (implemented as Rails engines). I feel it is premature to try to achieve this as part of an admin rebuild, as the rebuild might significantly change what we’re working with. I’m not sure where that would leave the “domains” project; I think it would be better to reconsider it once the rebuild is complete.

This project would have some implications on technical debt once the legacy interface is eventually removed:

  • AngularJS would be removed from the admin part of the code base (it would still be present in the front end).
  • By building our own controllers for the new interface as required, the dependency on Spree admin controllers and the associated monkey-patching would be removed.

I’m making this proposal tentatively to see how people feel about the idea. I’m also still trying to work out whether I actually want to dive into it myself. If I do, I’m willing to work on it on a voluntary basis for now, and could potentially dedicate quite a bit of time, though I can’t guarantee that I won’t run out of steam and/or need to prioritise paid work.

There are several conditions I feel would need to be satisfied beforehand:

  • General agreement in the community about the value of the project and the technical approach.
  • At least one person who is experienced within the community who can work with me to identify the user needs, conduct user research, validate solutions, etc. It’s worth stating that this is likely to be a drain on that person’s time for other OFN work.
  • At least one person in the dev team who is willing to review/merge my code in a relatively timely manner. Again, this is likely to take up some of that person’s OFN time.

This is a big project. It will take a lot of time and work to see it to full completion, but I envisage it proceeding in stages, something like this:

  1. Implement enough that the most common type of user (producer, hub, etc) is able to do all their day-to-day management (orders, products, reports…) via the new interface. Start inviting existing users to opt-in to the new interface and provide feedback.
  2. Fill in the gaps to allow other types of users to do all their day-to-day management via the new interface. Invite these users to opt-in to the new interface.
  3. Implement the shop configuration features needed to allow new users to do the initial setup via the new interface. Perhaps start new users on the new interface by default. (But still providing a way to switch to the legacy interface to perform uncommon tasks.)
  4. Implement all the remaining features, or make explicit decisions to drop certain features based on analysis of development effort and user needs.
  5. Default all users to the new interface, but still allow them to switch back to the legacy interface if needed.
  6. Schedule a date for removal of the legacy interface and communicate this to users.

Note that it’s possible/likely that some users will object to the changes, especially those who are intimately familiar with the existing interface. We need to listen to their complaints and try to meet their needs, but also have a keen awareness to not increase interface/code complexity without a clear justification.

4 Likes
2

Hey Jon, thanks heaps for taking time to analyse all this and experiment. Rebuilding the whole admin interface sounds huge to me at this point, and to a degree not worth it. We have a lot of cool and useful code that would be a lot of work to replace (scattered in a lot of crappy legacy code as well). But I can also see a lot of opportunities here. I’m excited about the possibility to finally tackle the complexity we got from extending the Spree admin interface for enterprises and then limiting it with permissions. It’s currently a chunk of software that does many things and only a few things well.

We have many different clients and we support many different business models. That makes our current interface complicated. But it can also make a rebuild easier. The simplest form of enterprise is a profile, it doesn’t have products and it doesn’t sell anything. It only needs to update contacts and descriptions. It would be a great start to write a custom user interface just for that. And I believe that it would already be an improvement to direct profile-only accounts to that new interface. Everybody manages to set up a Facebook page. It should be as easy to set up an OFN profile.

The challenge we would have is that one user can have permissions to several enterprises. Maybe we can rethink the workflow in a way that you choose an enterprise and then everything is about that enterprise. It could make everything easier and faster. And if we can integrate this new interface with the current one, making switching between them easy, then we can have a nice iterative migration. Keeping that enterprise specific approach, could also allow for better separation and more efficient work flows. Maybe the product edit screen of a producer should look differently to a shop?

In the end, we are left with the super-admin features which should be in a separate interface as well. It needs the current Settings page, basic user and permission admin and the ability to switch to every enterprise (or log in as user). I’m imagining that to be a lot simpler than what we have at the moment.

A few more thoughts:

Thinking about that first profile interface again, I’m not sure if we even need the Tabler gem here. I’m not familiar enough to judge it’s overall usefulness for the kind of very specific interfaces we are trying to build.

Stimulus, React, latest Angular? I don’t know, the simpler the better, I guess. But also the more similar it is to current technologies, the easier it will be for everybody to deal with all aspects of the code. We don’t want three different JS frameworks in one project.

The new interface should consider the work the Data Food Consortium has done to use similar terms and logic. It could be an opportunity to implement some of the Network 2.0 features without affecting the old interface.

3

Yes! That’s basically my number one wish for OFN at the moment. It’s been discussed before but wasn’t considered a higher priority than the other things in our current roadmap. It would be great to use a framework to make building beautiful UI elements easier. I was thinking last of week about doing a spike on this.

We’ve had general agreement that an admin interface update, moving away from Angular, decoupling from Spree etc would be great, but they would require a lot of work. We currently have a full pipe and limited capacity, and we have processes for prioritising work and new features…

That being said, I’m very excited!

4

We have a lot of functionality and logic tied up in Angular code at the moment, which is probably the main thing that makes this a large job instead of a relatively small one. I’m wondering if there’s a way to split this into smaller phases instead of tackling everything at once? Like keeping some of the Angular in certain pages whilst moving to the new interface?

5

I may be wrong here - but I wonder if there is an opportunity to tie this to existing priorities. For example, there has been discussion about the first feature from Network 2.0 that we want to do - allowing creation of own copy of a product/variant. I think that we talked about this being a new version of the products and/or inventory page which started with this new logic . . does that ring bells @Rachel @luisramos0 etc? If so, this could be a candidate for two birds with one stone? i.e. we could progress the work on designing that, with a view to setting ux style for new backend, and @jonleighton could potentially work on the prototype as first project in this new system?

6

Yeah, it’s great to see your commitment @jonleighton :tada:

Yes, we wish we had a new admin UI, this item here represents the same problem, with a different solution: Backend/Admin layout overhaul
In this other post, we try to do what both spree and solidus did, revamp the existing UI in some way without having to re-write all pages.
The main problem with it, and this post here, is that, although highly desirable, this is not close to the top of our priorities right now.

This proposal here is a multi-year project and, as you correctly mention, this would require a huge amount of effort from the community in terms of Product (defining how this new app would work is a lot of work), Dev (code review and coding it in case you dont complete it), Testing and, most importantly imho, Code Maintenance (more code means more time/money goes into maintenance.

I think the main factor that makes me say “let’s not do this please” is our main constraint: lack of time, particularly dev time. Also, I think this would need to go through the normal voting process where instance managers vote in this against the other priorities.

So I try to offer alternatives:
1 - what do you think about supporting Backend/Admin layout overhaul?
2 - following up from your great idea of replacing the UI for certain user profiles: instead of replacing/improving existing functionality, what if we build extra functionality, for example, creating a new page specifically for supporting the packing process for farmers, that works on mobiles so it can be taken to the warehouse? this is just one example. (@Kirsten I follow you here but I dont think network is a good candidate because it’s a core part of the app. I think it would be very challenging to built something so core to the business model in parallel…)
3 - what if we rebuild the frontoffice and get the Mobile epic done in this manner? I’d support this mainly because it’s a task around 10 times smaller than rebuilding the admin UI.

In summary: I think starting a new huge project to rebuild the admin UI is not close enough to top priority and would be a step too big for our legs.
I think this last option “do it but in the frontoffice” can get some traction from the community mainly because it’s already a priority and I think it would make sense in terms of tech strategy: 1. to separate frontoffice from the API and 2. validate a more modern frontend tech stack (replace outdated angularJS).

I hope this helps. It’s great to have you around!

2 Likes
7

Thank you @jonleighton for this proposal :heart_eyes:

I believe Luis has sum up most of my thoughts so far :+1:

@Kirsten yes for the network feature we have talked that it was a good opportunity to do a new version of our product page and making it reading for mobile. But what we also said - and I think this applies also here - is that we need to do some UX work beforehand. This is such a massive work that we also agree that this would be paid work in order to keep momentum and to include as many user feedback/interviews as possible (given we don’t have analytics in the backend). That’s why I’ve met with Yuko: in order to get a quote. But we didn’t move it forward despite our meeting in Barcelona, other priorities came through…

8

I’m not going to add much. I hear everyone’s opinions and I bet we all mostly agree.

Personally, I see this as an exciting step forward that touches on a very deep topic

This is likely to put off potential new users of OFN, as well as increase the burden of support queries.

but it feels daunting at the same time. To me, it’s like we struggle a lot to change the product beyond the surface, although we’re improving. And this inevitably brings fear and conservativism.

So, I say: let’s keep discussing and perhaps start from @luisramos0 points, hear the high-level ideas and goals of your proposal @jonleighton and split it into parts to see how we can make things fit together.

9

I understand and agree with all the above. I also had a conversation today with a potential user who was really values-aligned and really really wanted to use us, that ultimately went with something else (Square) because we can’t really deliver the supply transparency which is the thing he really believes in.

Is there a reason we can’t move forward on the UX for the new product page? and then potentially build / run in parallel? and do it in a way that makes creating and managing products from mobile happy and awesome? and run it in parallel until we retire the old one? I really thnk that cracking this network thing is critical, and we actually have a good plan … and if we could start to progress it with some added muscle for a while it would jump us forward a whole lot . .

10

Funds? But I can ask Yuko when the quote will be ready so we can have an idea of the budget needed.

1 Like
11

I’d like to share that I got really excited about this project after Maikel’s saying it would be ok if we manage to integrate it with the existing UI.
If we can find a way where the pages of new UI can replace the existing UI, instead of having 2 apps and having to migrate users over a very long period of time, we would be able to release the new UI within the old UI. This is called the strangler pattern.
Conditions for this:
A - the new UI cant be totally disruptive compared to the old one, we need to keep it blueish for example, so that users dont feel they are jumping between 2 apps (although actually they are).
B - we need to find a tech way to integrate the two UIs.

Regarding B:
I have done this twice in the past, once (a reports distribution solution in a bank) we used an iframe for the transition, the old code would render an iframe with the new pages from the new app. Eventually we removed the iframe as all pages were replaced. The other case (an email delivery solution in a digital marketing company) was a simple html div where the old code was calling the new code to render a specific div in the page (this required some tweaking to make the html of both apps compatible).

I think this is feasible in OFN, we need to find a tech solution for it and we would need to decide if we 1. render the old app inside the new app or 2. render the new app inside the old app. For option 1 we would start by rebuilding the menus.

This is probably the way to go about the future of the admin UI, even if not now. I dont think we will ever upgrade angularjs 1.5

12

I would really like us to be moving this even if we can’t get in dev pipe yet, because it really is so critical to our value proposition

13

I’m sorry but I can’t keep getting back in my head to the discussion regarding things some instances or users would love to put money on.

We agreed our pipe was the only way to get things done. I really wonder if it is not the same case here.

So don’t get me wrong: I’m not saying I don’t want network or admin UX to happen. What I’m saying that I think it needs to be prioritized in the pipe.

Even if we don’t touch the UX part, there will be product, testing and code review to do.

So I don’t see the difference between a scenario where a new developer volunteer his time, or someone finding a new dev to work on something unprioritize by the community and paying for it… I feel like we end up with the same problems we want to avoid: maintenance, unfinished work, even slower pipe…more frustration.

I know it would feel good to say we start to work on those things. But it won’t mean we will finish it. Being able to finish things should be more important than to start them… And in order to finish work we need to set priorities or to set specific people on it.

2 Likes
14

If it’s critical to our value proposition then it should be prioritised in the pipe. I think we need to have that conversation about where it fits alongside of the other things we’ve prioritised.

Which means discussing it with the global hangout group and having people vote on it vs the other things to determine exactly how critical the crowd believe it is compared to the other things already there.

So, we bring to the crowd on Tuesday the idea of having a POC done to answer the questions of a) how could we improve the order management page, and b) can this new UI be integrated into the existing (as raised by @luisramos0 above), have this voted on in terms of priority and then get to it if it’s considered important.

@Kirsten and @Rachel this means that we’ll be following the process, but we’ll also see its criticality for the broader group by seeing where it’s voted in.

Ping @jonleighton - we’ll be bringing this idea to the global hangout tomorrow night Melb time for discussion, would be lovely to see you there :slight_smile:

15

I’ve been mulling over the idea (from @luisramos0) about how to build out a new interface inside the existing one. I do broadly think it could work and would be a better plan than building an entirely new interface alongside the existing.

Basically the idea, as I understand it, is to have the new and old pages share the same layout shell (header, nav, footer…), but they would diverge in terms of look and feel within the body of the page. This would enable us to incrementally replace legacy pages with redesigned ones, until the legacy ones are eventually completely removed.

I think it would be sensible to redesign the “layout shell” using the new CSS framework as the first step in this, and then host the legacy pages within the new shell. The advantages I see in doing this are:

  • Avoid constraining redesigned pages with legacy styling
  • A chance to rethink the main navigation, which feels rather cluttered and unstructured to me
  • Allow the new pages to be fluid-width to make better use of screen space for information dense pages

To feel sure that it would work, I’d need to do a code spike, but I can’t see any fundamental problems with the idea. (Albeit that there may be some pain around getting the legacy CSS to play nice with the new CSS on the legacy pages.)

All that being said, my feeling after our chat about this whole thing in the product curation meeting last week was that it’s probably best not to pursue this given the spectrum of opinions on it and the lack of resources in OFN generally. I’m also looking at my priorities for the new year and feeling unsure how much time and energy I’ll be able to dedicate it. But, if there is definite enthusiasm for redesigning a single page/section as a first step (such as the orders page) per the above strategy then I’m not ruling it out, so I’m happy to continue the conversation.

2 Likes
16

excellent Jon, thanks for your analysis!
What I like about this approach is that is feels like the way to go anyway, now or later.
It would be great to have your contribution towards this project!

17

I am definitely excited about redesigning a single page / section (i.e. potentially orders) as per above strategy. I am a little unsure about how complex redesigning the layout shell would be before we could do this . .

are we basically just talking about this bit?

image
image1372×220 23.2 KB

18

Yep, the stuff that doesn’t change across different pages.

19

I think we must take this step forward as part of the network feature. Most likely we will need to build a completely new and complex page (product finder) or maybe two (a replacement for products list/inventory page).

By “this step” I mean, we need to use this as an opportunity to define and start implementing our UI tech strategy for the future.

I just add another close look at tabler. @jonleighton I wonder what are the pros and cons of relying on tabler. Would this be a dependency we would keep upgrading and adapting to? I see you have put it in vendors in your branch, I wonder if this would not be upgraded and we would be tweaking these templates as we go. That would mean the pros would be:

  • freedom from it as a dependency
  • a good head start compared to building something from bootstrap only

I cant see any con, I wonder what are the alternatives to tabler apart from basic bootstrap.

We currently use foundation which I think is the main alternative to bootstrap in the market.
We are on foundation 5.5.2.1 from May 2015, we could simply use latest foundation 6.5.3.0 to build the new UI.

This is tightly related to the UI framework we will be using (I see tabler has projects in react, angular and also vuejs). I also posted in the UI framework upgrade thread just now.

1 Like
20

I wonder what are the pros and cons of relying on tabler. Would this be a dependency we would keep upgrading and adapting to? I see you have put it in vendors in your branch, I wonder if this would not be upgraded and we would be tweaking these templates as we go.

IIRC I vendored it because I couldn’t find an easy way to pull it in as a dependency.

It would be worth considering alternatives to tabler. I had a look around at the time and felt like it was a good starting point but I’m sure there are other options.

I think something like tabler is a good approach to get a good-looking UI thrown together pretty quickly. But you’re likely to hit up against its constraints and need to implement customisations in places. Which would probably make upgrading a risky business anyway, so perhaps vendoring and ‘owning’ the dependency is the best approach anyway. (It’s not like you’re going to need to perform security upgrades in this case.)

Using something a bit more basic (e.g. Bootstrap, Tailwind, …) would likely result in a leaner and perhaps more easily maintainable end product, but would require more input from a designer (to get something that works well) and more up-front dev time. So there’s a trade off there.

1 Like