archesproject / arches-dev-training Goto Github PK

KO Components (widgets, card components, report templates) as front-end objects. Design
considerations and code development

Setup and style a master slide template

Develop a card component which shows the coordinates of an address datatype in a simple mapbox map.

This module should provide a general introduction to Django (models, views, settings, url routing, etc.) so that students have enough knowledge to follow arches training lessons. Lesson time: 90min

Customizing the content and presentation of resource model data in a summary report
for an instance.

Data validation, transformation and formatting. Implementing configuration options
for a data type. Registering a new data type with Arches.

This module should cover the basics of KnockoutJS such as view models, data binding, and conditional logic/iterating within html. Most importantly, this module should explain what components are as these will be the focus of the training course. Lesson: 90 minutes.

Developing a custom card component. Manipulating data with card components.
Aggregating node groups and managing tiles.

Arches design goals, core technologies, system architecture, and coding conventions.
Organization of Arches code base, Git repository and submitting pull requests.
Developer code of conduct.

Introduction to graphs, datatypes, widgets, tiles, card components, report templates,
packages. Overview/summary of how Arches implements data models, modular design
of data types, relationship between data types and widgets. Role and use of card
components in Arches data editor UI. Implementing custom logic via functions. Using
Packages to create Arches applications

Develop an address widget to support data entry for the address datatype.

Arches’ methodology for processing geospatial models for presentation, search.
Customizing the display of geospatial data. Displaying subsets of model instances as
overlays.

Packaging your custom data types, widgets, cards, and templates for distribution as
an Arches application. Customizing the default Arches landing page user interface (UI)
and other default UI pages.

Overall Comments

We have a lot of information in the official Arches documentation regarding many of the topics and content covered here, but these slides make no reference to it. I think an effort to link to existing documentation where possible should be undertaken. CLI command reference, etc.

Generally, I think the course flows well overall, and I really like the in-depth examples and lab contents. However, after working through it, I think that consideration should be given to the following restructure (modules would be renamed of course):

• Module 1: The Arches Platform
• Pre-course A: Deployment Considerations
• Pre-course C: Django
• Module 2: Introduction to Datatypes
• Pre-course B: KnockoutJS
• Module 3: Building a Custom Datatype
• etc. (the rest unchanged)

A couple reasons for this suggestion

• The knockoutjs primer would fresh in peoples' minds right before we begin working with components. Otherwise, it's a little isolated with it's location early on the first day.
• The discussion of deployment considerations and architecture will make more sense after some basics of Arches' about Arches components have been discussed.

I think it would be good to clearly describe the end state of the project at the end of each module. What should be registered? What should be working correctly? etc.

Module-specific Comments

Note that all bold numbers correspond to the urls generated by the service on github pages. These are based on the state of the repo at commit 51ce70a (Oct. 12).

Pre-course A: Deployment Considerations

General Comments

• Add architecural diagrams... For me a basic diagram that Alexei drew was one of the most important takeaways from Shendish in 2014.
• 6 mentions distributed architecture, but this is before the various Arches components have been introduced. So, people may not know what that means. Would it make sense to reorganize that?
• 7 mention linux flavors? windows "Difficult to set up, must use IIS" seems a little confusing. Are you saying that IIS is difficult to set up, or windows is? Also, every OS needs a webserver, so why mention IIS here?
• 9 says that different cloud services have positives and negatives, but doesn't actually present positives and negatives of each...
• 10 Offer back up strategies? (cronjob pg_dump, db replication, RDS snapshots, etc.) Offer examples of how e-mail can be set up? What is the best service to use? I definitely appreciate the Let's Encrypt suggestion.
• 11 Projects/Packages content is duplicated from 10
• It would be nice to actually learn about the Lincoln Arcade (btw, ARCADE?) architecture (how distributed is it? what e-mail server does it use? what SSL cert? what size are the server instances?) and what led to these decisions.

Proofreading

• 4 fix "Is there sufficient in-house resources..."
• 5 In-House not In House
• 5 "upfront" not "up front"
• 5 and 6 "Scalable" is such a hot word nowadays... could be used here
• 7 dependencies not dependancies
• 13 in-house not In House
• 14 bad formatting

Pre-course B: KnockoutJS

General Comments

• Consider putting documentation and tutorial links fully typed as well, e.g.

  Docs found here: https://docs.example.com

  instead of

  Docs found here

  in case this text ends up in a non-hyperlink format (copy/paste, etc.)

• 26 consider changing first line to "Composed of a template (HTML file) and view model (JS files)" or something like that.

Proofreading

• 16 make list capitalization consistent with headers used in later slides

Pre-course C: Django

General Comments

• In the models and views slides, you say "Models (models.py)" and "Views (views.py)". I think it may be nice to have mention that in Arches these are actually many files ("models/resources.py", "views/search.py") etc. I know this is a general django section, but Arches doesn't actually have a "views.py" file, so I think it would be nice to acknowledge this here.
• 39 It may not be actually consistent with Arches, but something like {{datatype.name}} instead of {{datatype.datatype}} may be more clear. Also, in python terms what is "datatype" in this example? (dictionary), so this is a list of dictionaries? It may be helpful to say this explicitly.
• 41 suggest changing the DATABASES example to show postgres credentials. add note here about settings_local.py?
• 43 put in admin page link localhost:8000/admin for mucho clarity

Proofreading

• 32 missing period in first paragraph, also fix "...but it takeS longer..." in second paragraph
• 38 change localhost:8080 to 8000

Module 1: The Arches Platform

General Comments

• 49 this is the content that could be integrated with a diagram, or the relevant "Distributed Architecture" discussion in Pre-course A. Also, I'm not sure the best way to say it but Postgres is your actual database, and Elasticsearch is an index that can be rebuilt anytime from your database (i.e. in reality there is no novel data in elasticsearch, it's just an extra layer (though, of course, necessary)).

• 50 add link to docs repo

• 51 add link to code of conduct (on archesproject.org)

• 54 second line should mention the term "graph", too, right?

• 59 this second comment about template file paths could work really well way back in the intro to knockoutjs section.

• 60 Arches uses requirements_dev.txt, not requirements-dev.txt. You could mention that sphinx, etc. is already in requirements_dev.txt

• 62 Specifically, "you are expected to have Arches installed in a virtual envrionment. You will use this virtual environment for all work in the rest of the class." I think something like that would be very helpful, and would make unnecessary any further mention of "with the virtual environment where you installed arches activated" in the rest of the slide content.

• 63 This slide is super important. I think a recommended installation directory structure would be helpful, something like

    /swindon
        /env
        /arches-dev-training-project
  

  Also I recommend adding cd arches-dev-training-project to make it clear from which directory these commands must be run.

  Also, you should mention settings_local.py here, as this must be configured before running. Windows users need to set GDAL path, anyone using external pg or es will need to configure that stuff. for what it's worth, I can make an ES instance open to anyone who wants to use it.

  I don't think it's wise to ever have settings_local.py in version control. At any rate, it's an a-typical and not really a good precedent to set. An alternative would be to put a settings_local.py file elsewhere for download, like the one I have provided here: http://ftp.legiongis.com/swindon_materials/settings_local.py.

Proofreading

• 52 and 53 compose not comprise
• 55 consistent "Elasticsearch" capitalization (pretty sure Elasticsearch is what they use). This could be applied to the whole document.
• 60 second line, "your" not "you're", and add apostrophe to "projects"

Module 2: Introduction to Datatypes

General Comments

• 71+ These codes examples should include file paths to where these files would be in a project.

Module 3: Building a Custom Datatype

General Comments

• 77 I think it would be helpful to have people run

    python manage.py packages -o function list
  

  before and after running the command to register the function.

• 83 Similar to above comment, I think it would be good to take a minute to make sure people have seen that there is nothing in the search page (0 results) and nothing in the Arches designer (no resource models) before having then import these things.

Module 4: Introduction to Components

General Comments

• 91 Arches uses .htm instead of .html (I think the discrepancy between the real files and the slide could be a little distracting to some).
• 92 Config files can go anywhere, but where should they go? I could see this type of flexibility being more confusing than useful. Is there a preferred location for these files? Where are the config files for default components?
• 98 This is generally really helpful information, and perhaps could be mentioned much earlier on? Just a thought.

Proofreading

• 101 Suggest changing "As components widgets consist of front-end code only" to "As widgets are just a type of component, they consist of front-end code only" just for clarity (if that's indeed the intended meaning of the sentence)
• 112 & 115 Use code syntax for file path
• 121 suggest removing $(env), or perhaps adding this to all other command examples. Without $(env) is nice because you can more easily copy and paste, with it is the clear indication that a virtual env is in use. Personally I think without is better.

Module 5: Widget Development

(no notes)

Module 6: Card Component Development

General Comments

• 133+ add path to file

Module 7: Report Template Development

(no notes)

Module 8: Projects and Packages

General Comments

• 155 Mention that images for the front slide show are stored in projects (could just be added to the existing list that mentioned html).
• 156 Why not reference the RTD docs content on settings inheritance here? At any rate, a fully explanation in this slide of how settings.py (all of the permutations of that file) interact with the UI-defined Arches settings.
• 159 Use of the word "components" in the second item may be confusing here.

Module 9: Arches Geospatial

General Comments

• Mention that Arches can also consume WMS, as well as vector tiles.
• Why not reference all of the examples in https://github.com/legiongis/arches4-geo-examples? This repo could be cloned by attendees and the examples loaded directly into their project.
• 180 What, specifically, are the issues with tilestache?

Proofreading

• 165 "archesproject" add space

Module 10: Creating a Package

(no notes)

Develop an address datatype with an address and coordinates derived from a geocoding service.

Identifies important deployment considerations and presents deployment strategies, including S3 file hosting, based on the business requirements of an Arches application.

Technical summary of datatypes. Read/write/update/delete and data indexing
patterns for datatypes. When does it make sense to add a data type to Arches?
Design considerations and code development.

Create an empty package that will be used to collect the business data, graphs, and components necessary support the training curriculum. Push the package to this repo: https://github.com/archesproject/arches-dev-training-pkg

Role of widgets in providing a UI to manage a tile value based on its datatype.

Diagram the architecture of the distributed deployment