ArmLayout current/near future activity

[jco...@cironline.org]

Hello mailing list. This email jumps right in to an existing conversation carried out on Github (via code, commit messages and PR conversation) and in-person at a meeting the other week with the Texas Tribune. The topic is test refactoring and iteration to ArmLayout.

PR #6[1] is the starting point for the discussion and that code deals with refactoring tests. Now to continue the conversation…I’m sorry if it looked like I was churning the tests just ‘cause. There was a larger goal. I didn’t know the best approach, so I did “one thing at a time” instead of “piles of everything at once”. Tests were the baseline because they honestly needed cleaning up. Perhaps pulling out those “_utils.py” methods needed more discussion. I did that to bring the code closer to where it is used, they weren’t shared across multiple files and one method wasn’t even used at all. I started the tests refactor in early 2012; it didn’t go anywhere. In June 2013, I wanted to resume efforts on Layouts and realized again that those tests needed work.

PR #12[2] is the next step, which is actually a further refactoring of tests that conceptually deals with different things than #6. The largest change is testing the template tags themselves, rather than the Node classes. The template tags are the purpose, they are what the end users use, and we need to make sure they work. Django itself tests template tags using the template tags not nodes. Also, the nodes are implementation details; the actual tags shouldn’t care. Additionally this new PR increases code coverage on the `layout_helpers.py` from 78% to 100% and tests for filtering (i.e. `render_list listvar|slice:“:3” “template”`).

That’s a lot, but I don’t believe it’s churn for churn’s sake. I believe they are honest improvements resulting in easier to grasp and maintain code. Still not the end goal though. With tests refactored, I can independently change features.

Simple_tags are an easy, boilerplate-free way to create new template tags. They didn’t exist when ArmLayouts started and there have been notable improvements since. I want to refactor render_list, render_iter, render_next and render_remainder to be simple tags -> easier to understand code. With tests refactored to not care about their implementation, this change is simple to make and naturally easy to test to confirm nothing broke.

`render_model with` has been talked about for a while[3]. As the tag is essentially `include`[4], mirroring include’s functionality makes sense. CIR has been using this internally in production for a while. The new feature of course requires new tests and I wanted that refactored test baseline.

The final new feature I've been thinking about is model-provided template lookup[5]. Since ArmLayouts renders a model object using a template, it makes sense for the model to be able to specify how it finds that template. Currently it searches for the template file based on model inheritance. v1.1.0 brought backends to `render_model` and that allows implementing this new idea as a new backend without breaking backward compatibility.

That’s the current pipeline. Look for activity on Github.

[1]: https://github.com/armstrong/armstrong.core.arm_layout/pull/6
[2]: https://github.com/armstrong/armstrong.core.arm_layout/pull/12
[3]: https://github.com/armstrong/armstrong/issues/52
[4]: https://docs.djangoproject.com/en/1.5/ref/templates/builtins/#include
[5]: https://github.com/armstrong/armstrong.core.arm_layout/pull/8

-Jon Cotton | Senior Software Engineer | Center for Investigative Reporting

[jco...@cironline.org]

PR #12[1] has been merged into the v1.3.0 prep branch, which opens the doors for the next step(s). Three new PRs are up for review.

simple tags: https://github.com/armstrong/armstrong.core.arm_layout/pull/13
fix random test fail: https://github.com/armstrong/armstrong.core.arm_layout/pull/14
render_model with: https://github.com/armstrong/armstrong.core.arm_layout/pull/15

Hopefully discussion can be quick and complete by middle of next week. When those three merge in, I'll move on to the model-provided template lookup[2] feature.
 
[1]: https://github.com/armstrong/armstrong.core.arm_layout/pull/12
[2]: https://github.com/armstrong/armstrong.core.arm_layout/pull/8

[Jon Cotton]

Hi mailing list. ArmLayout 1.3.0 was released today. Find it on tagged on Github and on PyPi.

I'll keep this message brief because, without my Bay Citizen or CIR email address, I fully expect this to get delayed in moderation and deleted like my last message. There is a new CHANGES.rst file where you may find the new version details.

-Jon Cotton