search

RefugeRestrooms / refugerestrooms

REFUGE restrooms indexes and maps safe restroom locations for trans, intersex, and gender nonconforming individuals.
http://www.refugerestrooms.org
GNU Affero General Public License v3.0
884 stars 263 forks source link

Serve PDF restroom sign files in multiple languages #563

Open DeeDeeG opened 5 years ago

DeeDeeG commented 5 years ago

Scope / difficulty

Not too difficult.

Should just have to either:

1) Add some ruby code to serve the language of file the user is viewing, OR 2) Put restroom sign PDFs of all languages on the page, regardless of viewing language.

Also need to make .png preview images to go with the new PDF signs.

Also also, we possibly want to generate new QR codes to correspond to the new signs' URLs.

Impact

Allows the PDF restroom signs to be downloaded and used for a French-speaking audience, in addition to the existing English-language signs. Establishes a workflow for adding PDFs in additional languages down the line.

Proposal

Option 1: Add some Ruby code to logically "branch" which PDF is served based on the site language being served overall.

Pseudocode:

# This if statement should act as a list of the PDFs we actually have,
# other than English which acts as the fallback if we don't have a PDF specific to that locale.
IF locale = (fr OR [some-other-locale-we-actually-have-PDF-signs-for] OR [another-locale-we-have-etc.] ); THEN {
  = [$locale]_restroom_sign
}
ELSE {
  = EN_restroom_sign
}
ENDIF

Option 2: Add all PDF signs we have to the PDF signs page, so they may all be viewed by any viewer of the site, regardless of language.

This is just adding additional image <img> tags inside of link <a> tags (with Rails image/link helpers...) leading to the FR PDF files. No branching logic required in this case.

Addendum for either plan: We should make some .png preview images for the new PDF signs. We can generate QR codes for the new signs' URLS as well.

How to actually do this:

(e.g. one of our current QR codes: https://zxing.org/w/decode?u=https%3A%2F%2Frefugerestrooms.org%2Fassets%2Fqrcode-sign-with-handi-130dbfcb039cd8374e68fc3834cae54624b2a291a3a096021aef0850beec58f1.png has the "URI" data type, and actually leads to "http://refugerestrooms.com/rr-sign-with-handi.pdf". Maybe we should update the old ones to use HTTPS and go to our .org URL, rather than the .com one?

sophiabonsu commented 4 years ago

Hi @DeeDeeG ! I'm interested in working on this!

DeeDeeG commented 4 years ago

Hi @sophiabonsu, sorry I did not notice your comment! My email inbox is overflowing!!

I will take a look at this, if you are still interested, and I will try to give some direction on how to proceed.

(Please do leave another comment here if you are still interested.)

sophiabonsu commented 4 years ago

Hello @DeeDeeG !!! I’m still very interested in working on the issue ! I’m having trouble with the installing the development environment. I installed the docker and my laptop has been much slower since. It’s an older MacBook(2009), so I suppose that the problem. Any additional guidance would be greatly appreciated.

DeeDeeG commented 4 years ago

Hi again, @sophiabonsu.

First thing, I think it would be good to ensure you have a workable development environment, so that is what I will comment about first.

Either using Docker or working outside of Docker is fine, whichever you prefer.

Regarding technically fixing this issue (#563):

This should be the only file we need to edit to make PDF signs available in multiple languages: https://github.com/RefugeRestrooms/refugerestrooms/blob/develop/app/views/pages/signs.html.haml

It is written in Haml, which is a language designed to make HTML more concise, and the syntax is more like a programming language than HTML. But it is mostly just HTML written in a different coding style. (It gets interpreted and turned into HTML before it is sent to the site visitor's browser). It allows you to embed Ruby code (with the equals sign = ) as well. The ruby code runs, and produces HTML code that is placed in the part of the page where the equals sign = was.

We can dynamically choose which language of restroom sign PDF to put in the page based on the visitor's locale setting (en for English, fr for French, es for Spanish, etc.) Or we can just include the English signs like we already have, and add links to the signs/PDFs in other languages (Right now we just have English and French),

I would suggest looking at the page's haml code and the Restroom signs page at refugerestrooms.org (https://refugerestrooms.org/signs) to compare, and try to see where the parts of the haml page show up in the final HTML document.

The haml code includes some Rails framework helpers, especially for embedding images files and hyperlinks. They looked tricky to me at first, but they made sense to me eventually. I hope you will also find it makes enough sense to work with it.

Strategies for implementing this:

There are two ways to go about it:

  1. Link to PDF signs in all languages we have (currently English and French) all the time, without dynamically changing the page based on the user's locale

(this would be simplest)

Just insert a hyperlink into the haml markup, linking to the French PDF signs under the existing links (to the English signs). Eventually it might be nice to make a preview PNG image of the French signs like we have for the English signs.

  1. Link to the French PDF if the user is browsing the French page, otherwise use the English PDFs.

For this approach, it makes sense to me to program the page to get the user's locale (reading the Rails Internationalization API by reading the value of I18n.locale) and based on that, link to the appropriate language of PDF signs.

Lastly a note: I myself am not an expert programmer (I'm self-taught) but I think the level of programming will not be extremely difficult for this task. If you need info about Haml or Ruby, I am happy to link to documentation or give my own explanation of certain concepts, so if you need any help with the programming part, or if the structure/tech of this project/repo is unclear, I am happy to answer any questions. I enjoy teaching, and time permitting I will be glad to answer questions about anything that comes up.

DeeDeeG commented 4 years ago

That's a pretty sweeping overview, but if you have anything more specific you want answered, I can do that. Hope it's helpful (and not overwhelming).

Best Regards,

- DeeDeeG

DeeDeeG commented 4 years ago

For more help with Haml (I think this would be the trickiest part for someone not familiar with it) here are some resources:

Here's our Haml source for the restroom signs PDF page... turned into HTML with embedded Ruby code. (Click this text to expand/give this text keyboard focus and press "Enter" to expand.) ```erb

<%= t('.title') %>

<%= t('.intro') %>

<%= t(".head-accessible") %>

<%= image_tag('rr-sign-with-handi.png', :style => "padding:15px;border:1px solid #444;") %>

<%= t(".download") %>

<%= image_tag('qrcode-sign-with-handi.png', :width => "200") %>

<%= t(".head-non-accessible") %>

<%= image_tag('rr-sign-no-handi.png', :style => "padding:15px;border:1px solid #444;") %>

<%= t(".download") %>

<%= image_tag('qrcode-sign-no-handi.png', :width => "200") %>

```

Should be easier to read, to understand how the Haml turns into HTML.

Ruby code explanations:

DeeDeeG commented 4 years ago

Hmm, I have to correct my earlier comments about setting up the development environment outside of Docker. I mis-remembered how far I was able to get testing outside of Docker. My apologies for not testing the steps in my comment.

The webapp does not seem to work at all outside of Docker if PostgreSQL is not running locally. Also, NodeJS must be installed, or Rails will not run.

Here is a proper explanation posted by another contributor to Refuge Restrooms some time ago: https://github.com/RefugeRestrooms/refugerestrooms/pull/413#issuecomment-356756503 (Since this was posted, we have added NodeJS to our web app, so you must also install NodeJS. It can be downloaded and installed from here: https://nodejs.org/en/download/ We use NodeJS (LTS) v12, but v13 should also work -- the version you download should not matter.)

DeeDeeG commented 4 years ago

I got an email notification of an issue you had run into.

I can look into it, but I'm not familiar with that particular error message. Hopefully it has gone away by now/been resolved?

WebPacker is a sort of low-level, automated thing. I don't think this project has changed the configuration/setup of WebPacker in a bit, so it should be working. In order to make sure the docker image built correctly, I would suggest to try rebuilding the docker image with something like docker-compose build...

(If it finishes rebuilding very quickly, then it is using a cached version of a previous docker-compose build run. In that case, here are some good-to-know commands for cleaning up docker builds...)

Essential docker cleanup commands:

More-advanced stuff: