GitHub - vdhamer/Photo-Club-Hub: Viewer for fine-art photographic images. The app showcases the work of photo clubs in a consistent way. Steps: select a photo club ➤ select a club member ➤ view that member’s portfolio. An alternative order is also supported. Work in progress: the app is migrating to a hierarchy of distributed JSON files to enable clubs to manage their own data.

About the Project

The App

This iOS app showcases photographs made by members of photography clubs. It thus serves as a permanent online gallery with selected work of these photographers.

The first versions of the app only supported a single photo club in Waalre, a town in the south of the Netherlands. Starting with release 2.0, support was added for multiple photo clubs. This allows viewers to see images from multiple clubs within a single app. It aims to provide a degree of uniformity, thus sparing the user from having to find each club's website, discovering how to navigate each site and how to browse through the individual images within a site. Starting in version 2 the app's name was changed from Photo Club Waalre to Photo Club Hub to emphasize the multi-club aspect.

To achieve this, the app fetches online software-readable lists of photo clubs, their lists of members and their curated images. This ensures that photo clubs, club members and member images can be added or changed without requiring an app update. It also allows the clubs to manage their own data.

See the chapter on how to add a club's data as 3 distict data layers or Levels.

Photo Clubs

The app showcases curated images made by members of photo clubs.

Photo clubs are the distinguishing feature of this app. You either look up a photo club and then find its members (the Portfolio screen) or you look up a photographer and then find the associated photo club (the Who's Who screen). Once you have chosen a club-and-member combination or a person-and-club combination, you can view the image portfolio for that club member.

Details (click to expand)

Here is a schematic representation of the Portfolios screen that lets you first find a photo club before you get to club's members and their images:

photo clubA (hosted on siteA)
- portfolio1 of photographer1
  - images within portfolio1
- portfolio2 of photographer2
  - images within portfolio2
photo clubB (hosted on siteB)
- portfolio3 of photographer3
  - images within portfolio3
- portfolio4 of photographer4
  - images within portfolio4

An alternative navigation path is provided by the "Who's Who" screen. This view puts the photographer first, thus allowing you to find a photographer directly and then seeing which club(s) the photographer is associated with:

photographer1
- photo club A
  - images of photographer 1 in context of club A
- photo club B (optional)
  - images of photographer 1 in context of club B
photographer2
- photo club A (or B or whatever)
  - images of photographer 2 in context of club A
photographer3
- :

For comparison, traditional personal websites stress the photographer's images, without any reference to clubs:

website for photographer1 (hosted on site1)
- photo galleryA (e.g. portraits)
  - portraits in galleryA
- photo galleryB (e.g. landscapes)
  - landscapes in galleryB
website for photographer 2 (hosted on site2)
- photo galleryC (e.g. macro)
  - :

Implications

Details (click to expand)

If a photographer joined multiple photo clubs, the app can show multiple portfolios (with independent content) for that photographer - one per photo club. This could mean that the photographer is currently a member of two different clubs. But it could also mean that a photographer left one club and joined another club. Or variations of these scenarios.

In all cases, the portfolio concept groups the images both by photographer and by photo club.

The app is thus not intended as a personal website replacement, but it can have links to a photographer's personal website. Furthermore, nothing prevents you from supporting an online group of photography friends - assuming that they are interested in organizing this together.

You could even consider yourself a one-person club and put your images in a single portfolio below that club. Or you could use the club level to group a few individual photographers (by region or interest) as long as the members of this non-club are willing to align (e.g. maintain the list of portfolios=photographers who are then a member of a loosely-knit club).

(back to top)

The User Interface Screens

Usage of the various screens in the user interface:

The `Portfolios` Screen

The Portfolios screen lists all the photo clubs featured by the app. It allows you to first select a photo club and then select the portfolio of one of its members. The Search bar filters the lists of club members using the photographer's full name. Swiping left deletes an entry, but this is not normally needed and is not permanent (yet)).

The `Clubs and Museums` Screen

The Clubs and Museums screen lists all photo clubs that are known to the app. Each entry predominantly contains a map showing where the club is located and optionally your current location. A button with a lock icon toggles whether the map is can be controlled interactively (scroll, zoom, rotate, 3D). By default, the maps are not interactive. This mode helps scroll through the list of clubs rather than scrolling within a map. A purple pin on the map shows where the selected club is based (e.g., a school or municipal building). A blue pin shows the location of any other photo club that happens to be in the displayed region. The screen can also show any photo museums that happen to be in sight. These have different markers than the photo clubs. The plan is that the screen can switch between listing all photo clubs and listing all photo museums.

The `Images` Screen

The Images screen displays one portfolio (of one photographer associated with one club. It can be reached by tapping on a portfolio in either the Portfolios or the Who's Who screen. The title at the top of the screen shows the selected photographer and selected club affiliation: "Jane Doe @ Club F/8".

Images are shown in present-to-past order, based on the images's capture date. For Fotogroep Waalre, the year the image was made is shown in the caption.

You can swipe left or right to manually move backwards or forwards through the portfolio. There is also an autoplay mode for an automatic slide show. This screen is (for Fotogroep Waalre) currently based on a Javascript plug-in (Juicebox Pro) that is normally used in website creation.

The `Preferences` Screen

The Preferences screen allows you to configure which types of portfolios you want to include in the Portfolios screen. You can, for example, choose whether to include former members. The Preferences screen probably should also filter the Who's Who screen - but it doesn't yet.

The `Readme` Screen

The Readme screen contains background information on the app and info on app usage.

The `Who's Who` Screen

The Who's Who screen lists all the photographers known to the app. It allows you to first select the photographer and then select that person's club-specific portfolio. If available, club-independent information (like birthdays) for that photographer is displayed here. The Search bar filters on photographer names.

The `Prelude` Screen

The Prelude screen shows an opening animation. Clicking outside the central image brings you to the central Portfolios screen.

Details about Prelude screen (click to expand)

When the app launches, it shows a large version of the app’s icon. Tapping on the icon turns it into an interactive image illustrating how most digital cameras detect color.

This involves a Bayer color filter array that filters the light reaching each photocell or pixel. In a 24 MPixel camera, the image sensor typically consist of an array of 4000 by 6000 photocells. Each photocell on the chip itself is not color-sensitive. But by placing a miniscule red, green of blue color filter on cop, it because best at seeing one specific color range. Thus in most cameras, only one color is measured per pixel: the two missing color channels for that pixel are estimated using color information from surrounding pixels.

Tapping inside the image allows you to zoom in or out to your heart's content. Tapping outside the image brings you to the central screen of the app: the Portfolios screen.

You will see the Prelude animation after you shut down and restart the app. On wide screens (iPad, iPhone Pro Max) you can see the animation again using an extra navigation button at the top of the screen.

Why provide such a fancy opening screen? Well, it was partly a nice challenge to make (it actually runs on your device's GPU cores). But it also helps explain the app's logo: the Bayer filter array indeed consists of an array of repeated red, blue, and two green pixels.

(back to top)

Features

Multi-club Support

Version 1 of the app only supported Photo Club Waalre (known as Fotogroep Waalre in Dutch). Version 2 added support for multiple photo clubs. This means:

all clubs in the system are technically handled in the same way (although some may have provided more data)
users can find all supported clubs on the provided maps
a photographer is shown associated with multiple clubs if applicable (e.g., former club, current club)
the app is stepwise being prepared for larger amounts of data (data is distributed over sites)
the app is starting to enable that clubs can manage their own data (data "within" a club is managed by the club)

Searchable Lists

The three screens with long lists (Portfolios, Clubs and Museums, Who's Who) each have a Search Bar where you can enter what you are looking for. This reduces the list to items that match that filter criterion.

Details on the Search Bar(click to expand)

On an iPad, the search bar is always visible and at the top of the screen. On an iPhone, scroll up rapidly until you hit the top of the list.

The text you type inside the search bar is matched against key fields for the records shown in the list.

In the Portfolios screen, a search scans photographers' full names. Searching on Jan might return Jan Stege, Ariejan van Twisk and Jos Jansen. If you need to search on club names, go to the Clubs and Museums screen.
In the Clubs and Museums screen, searches try to match against the organization names and towns. Searching on Ber might match FFC Shot71 (Berlicum) and Museum für Fotografie (Berlin) and The Victoria & Albert Museum (London). Note that the town is the location specified in the root.level1.json file and not its translated version, which can be different.
In the Who's Who screen, searches try to match the photographer's full name. Searching on Jan might return Jan Stege, Ariejan van Twisk and Jos Jansen.

Design detail: Search Bar filtering is done in the app's user interface and not by the CoreData database.

Photo Museums

Details on Museums (click to expand)

A photo museum is not a photo club and is displayed on the maps using a dedicated marker. Techncially, the app doesn't allow museums to have "members" that share images with the museum.

Consider the showing of museums a bonus that may interest some users. You are welcome to add a favorite photo museum via a GitHub Pull Request. It only requires extending a JSON file. The file format is documented below under How Data is Loaded.

Swipe to Delete

Details on Deletion (click to expand)

Whenever the app is launched, it fetches up-to-date information from online servers. The use of online data ensures that the app stays up-to-date with respect to the latest lists of clubs/museums (`Level 1`), club members (`Level 2`) and member portfolios (`Level 3`).

This fresh online data is merged with an on-device (CoreData) database which contains a copy of the data as received during previous app runs. The merging updates the database. The database incidentally allows the app to display information without having to wait for the update processes to complete. The app's user interface immediately reflects any background updates to the database.

This means that deletion of local data will typically be temporary: the next time the app launches, it finds and reloads the records that are missing in the local database.

A problem (currently) occurs when an item (e.g. club, member, museum, photographer) is deleted in the online version of the information. This could happen if a club terminates itself, and the club is removed from the Level 1 list (instead of changing all members to former members). A similar problem occurs if a club's fullName or town fields change (e.g. fixing a typo); these are identifying attributes. Therefore the app no longer finds the "old" club on the online list, and finds a "new" club instead. The app has now way of knowing that one club is a replacement for the other. So the "new" club will be loaded correctly, without (in the current code) removing the "old" club in the database. This resulting in having two clubs with similar naming instead of one.

A temporary workaround is to manually delete the old/incorrect club. In the future this can be automated by detecting items that are in the local database, but are no present anymore inn the online lists.

Although swipe-to-delete can get the local database back in sync with the online data, a user may prefer a simpler brute force route: simply uninstall the app (thus deleting its local database), reinstall the app and then let it automatically load the online data.

(back to top)

Adding Photo Clubs to the App

The app is designed so that the required information about photo clubs is provided and maintained by the clubs themselves.

This is important because this allows the app to support many clubs. But is also also necessary in order to give clubs control over their own data: a club knows best what to mention regarding the club, who the current members are, who the club officers are, and - maybe most significantly - which images the members want in their portfolios.

To add a club to the app, the app distinguishes 3 hierarchical layers of information:

Level 1 consists of the club’s name and geographic location.
Level 2 lists the members per club.
Level 3 links to portfolios per club member.

We call these layers of information Levels because they need to be submitted in ascending order and, whenever the Level of a club increases, additional app features are automatically enabled for that club.

A club can take as long as needed (days, weeks, months) before proceeding to a next level. This means that an app user will see clubs with different Levels throughout the app. To the user this simply means that some clubs have shared more information than others.

Museums are added in the same way, although Level 2 and Level 3 are not applicable here.

When a club is at Level 1, it shows up as a marker on the maps (leftmost screenshot). This is because the app knows the club's name and the latitude/longitude where it is based.

When a club reaches Level 2, the app also knows the names and roles of club members. As illustrated in the center screenshot, the club and its members are now shown on the Portfolio and Who's Who screens. Clubs with zero members (as far as the app is concerned) are not shown on these two screens.

When a club reaches Level 3, the app is aware of the image portfolios of club member (rightmost screenshot), and allows app users to browse member photos. Different club members don't need to reach Level 3 at the same time. Attempting to view a portfolio of a club member without an available portfolio will display a placeholder message.

Level 1. Adding Clubs

Adding photo clubs (or museums) to get to Level 1 requires providing the item's name, location and a few optional URLs. This enables the app to list the items on the Clubs and Museums screen and display them using location markers on the maps.

Level 1 data is technically stored in a single root.level1.json file that is hosted on GitHub. Whenever the app is launched, it updates any outdated on-device data by reading this cenral online file. The user can already use the app during the update process: screens will update dynamically when necessary.

If you send us a club's Level 1 information, we are happy to add it for you to this central root.level1.json file. However, where possible, we prefer if you provide the change (and any future updates) as a GitHub pull request. This reduces the work required to handle many updates, and reduces the risk of administrative errors.

The same applies if you want to add a missing photo museum to the central root.level1.json file.

Level 1 example (click to expand)

Here is an example of the format of the root.level1.json file containing only one photo club and one photo museum.

{
    "clubs": [
        {
            "idPlus": {
                "town": "Eindhoven",
                "fullName": "Fotogroep de Gender",
                "nickName": "fgDeGender"
            },
            "coordinates": {
                "latitude": 51.42398,
                "longitude": 5.45010
            }
            "website": "https://www.fcdegender.nl",
            "level2URL": "https://www.example.com/fgDeGender.level2.json",
            "remark": [
                { "language": "NL", "value": "Opgelet: Fotogroep de Gender gebruikt als domeinnaam nog altijd fcdegender.nl (van Fotoclub)." }
            ],
            "nlSpecific": {
                "fotobondNumber": 1620
            }
        }
    ],
    "museums": [
        {
            "idPlus": {
                "town": "New York",
                "fullName": "Fotografiska New York",
                "nickName": "Fotografiska NYC"
            },
            "coordinates": {
                "latitude": 40.739278,
                "longitude": -73.986722
            }
            "website": "https://www.fotografiska.com/nyc/",
            "wikipedia": "https://en.wikipedia.org/wiki/Fotografiska_New_York",
            "remark": [
                { "language": "EN", "value": "Fotografiska New York is a branch of the Swedish Fotografiska museum." }
                { "language": "NL", "value": "Fotografiska New York is een dependance van het Fotografiska museum in Stockholm." }
            ]
        }
    ]
}

The actual root.level1.json file contains many club and museum records within their respective sections (delimited using [{},{},{}}] syntax). Note the comma's delimiting the array elements - the JSON data format is very picky about missing or extra comma's because JSON files are often generated by software rather than by hand. You can indentally check the basic syntax of JSON files using online JSON validators such as JSONLint.

Mandatory Level 1 fields (click to expand)

clubs and museums are required to distinguish photo clubs from photo museums.
- Syntactially either can be omitted, but then you wouldn't have photo clubs or museums in the app.
  - When loaded into the app's internal database, clubs and museums determine the OrganizationType (club or museum) of each Organization object. This in turn determines which marker type is shown on maps.
town can be a city (London) or smaller locality (Land's End)
- town is not directy visible in the user interface, although it may look that way. The user interface displays a language-localized name generated using the coordinates. This co-called localizedTown may contain the same string as town, or be a translation of town, or may even hold larger or smaller administrative entity. The file's town field is used to ensure that there is a unique ID for a club or museum. So Fotoclub Lucifer in Vessem would be considered unrelated to a Fotoclub Lucifer in Eersel. The town field also serves to document the record in the root.level1.json file: it is clearer to say "Victoria and Albert Museum (London)" than to say just "Victoria and Albert Museum" and leave you to determine the location using its coordinates.
  - Similarly, the user interface can display a computed localizedCountry name that is automatically generated using the provided coordinates. The Level 1 data thus does not need or include a country attribute. This is convenient because country names commonly get translated into local languages (Italia, Italy, İtalya, etc.).
town and fullName together serve to identify clubs or museums.
- It is thus possible to have two clubs with the same name in different cities. Two separate clubs or museums with an identical name in the same town would be confusing, and would be treated as a single entity by the app until the data about the original town / fullname combination is removed from the in-device database. Removal of obsolete Organization records is unfortunately not done automatically yet.
- Try to avoid changing either string. Because the app doesn't associate the new ID with the original ID, this results in the app displaying two different clubs or museums when the
nickName is a short version of fullName that is displayed in confined spaces such as on maps. It can be any string, but please keep it short.
coordinates is used to draw the club on the map and to generate localized versions of the names of towns and countries.
latitude should be in the range [-90.0, +90.0] where negative values are used for the Sounthern hemisphere (e.g., Australia).
longitude should be in the range [-180.0, +180.0] where negative values are used for the Western hemisphere (e.g., USA).

Optional Level 1 fields (click to expand)

website holds a URL to the club's general purpose website. It can be opened by the app in a separate browser window.
level2URL (for clubs only) holds the address of the Level 2 membership list. It is not used yet (April 2024).
wikipedia contains a URL to a Wikipedia page for a museum. It could be used for photo clubs - but Wikipedia pages for photo clubs probably don't/won't exist.
remark contains a brief note with something worth mentioning about the club or museum. The remark contains an array of alternative strings in multiple languages. The app chooses one of the provided languages to display based on the device's language setting.
- language is the two or three letter ISO-639 code for a language. EN is English, FI is Finnish.
  - If the device's preferred language doesn't match any of the provided languages, the app will default to EN, if available. If EN is unavailable, it will select one of the available languages.
- value is the text to display for that particular remark in that language.
nlSpecific is a container for fields that are only relevant for clubs in the Netherlands.
- fotobondNumber is an ID number assigned by the Dutch national federation of photo clubs.
- There used to be a kvkNumber as well (Chamber of Commerce) but that was removed because it wasn't worth the effort.

Level 2. Adding Members

Level 2 requires providing a list of the names of current (and optionally former) club members as a JSON file. This file can be stored anywhere - providing that it can be accessed using a web address (URL). For example, you can store it in the Media section of your club’s Wordpress web site using Wordpress' built-in uploading capability. With this Level 2 data, the club members show up in the Portfolios screen. Fotogroep Anders in the Netherlands is a good example of a Level 2 club. We are currently simplifying Level 2 support.<\p>

Each Level 2 JSON file lists the current (and potentially former) members of a single club. For each member, a URL is stored pointing to the Level 3 file (portfolio per member). Level 2 lists also includes the URL of an image used as thumbnail for that member. Level 2 lists can be stored and managed on the club's own server. The file needs to be in a JSON format so that the app can interpret the data. You can check the basic syntax of JSON files using online JSON validators such as JSONLint.

Level 2 example (click to expand)

Here is an example of the format of a Level 2 list for a photo club. This example contains only one member:

{
    "club": {
        "idPlus": {
            "town": "Eindhoven",
            "fullName": "Fotogroep de Gender",
            "nickName": "FG deGender"
        },
        "coordinates": {
            "latitude": 51.42398,
            "longitude": 5.45010
        }
        "website": "https://www.fcdegender.nl",
        "level2URL": "https://www.example.com/fgDeGender.level2.json"
    },
    "members": [
        {
            "name": {
                "givenName": "Peter",
                "infixName": "van den",
                "familyName": "Hamer"
            },
            "roles": {
                "isChairman": false,
                "isViceChairman": false,
                "isTreasurer": false,
                "isSecretary": false,
                "isAdmin": true
            },
            "stat": {
                "isDeceased": false,
                "isFormerMember": false,
                "isHonoraryMember": false,
                "isMentor": false,
                "isPropectiveMember": false
            },
            "birthday": "9999-10-18T00:00:00.000Z",
            "website": "https://glass.photo/vdhamer",
            "featuredImage": "http://www.vdhamer.com/wp-content/uploads/2023/11/PeterVanDenHamer.jpg",
            "level3URL": "https://www.example.com/fgDeGender.Peter_van_den_Hamer.level3.json"
        }
    ]
}

Mandatory Level 2 fields (click to expand)

club has the same structure as a single club record from the root.level1.json file. It serves to label the Level2 file so you can tell which club it belongs to.
- the town and fullName fields are required.
- town and fullName must exactly match the corresponding fields in the root.level1.json file.
members is a container that holds current and past members. Each member correspond to an instance of the MemberPortfolio class in the CoreData database.

Optional Level 2 fields (click to expand)

Optional fields (that are ignored)
- the level2URL field can be included, but it's value does not overrule the level2URL value in root.level1.json for safety reasons.
Optional fields (that are used)
- a club's nickName, latitude, longitude, and website overrule the corresponding root.level1.json fields if needed. This allows a club to correct centrally-provided information with club-provided information.
- givenName, infixName and familyName are used to uniquely identify the photographer.
- infixName will often be empty. It enables correctly sorting European surnames: "van Aalst" sorts like "Aalst" in the Who's Who screen.
  - An omitted "infixName" is interpreted as "infixName" = "".
- the level3URL field allows the app to find the Level 3 information with the selected images for this member.
- the roles field indicate whether a member fullfills a role as a club officer (e.g. chairman). If a given role is not mentioned, the default value is false is used. Many members have an empty or even absent roles section. Some members may have multiple roles (e.g., secretary and admin)
- the stat entries indicate a member's status in the club. If stat is missing, all values default to `false'.
- isFormerMember can be set to true if the person left the club and the club wants to keep that member's Portfolio visible. The user interface will state former member where applicable. By default (see Settings) former members are not shown. When shown, users see "Former member of ".
- isDeceased is a special variant of isFormerMember. If deceased members are not removed from the level2.json list, this allows the user interface to indicate this. By default (see Settings) former and deceased members are not shown. When shown, users see "Deceased, former member of " and the text is shown in a different color.
- isHonaryMember can be used if the person is no longer an active member, but is still treated as a member (e.g., after retiring) because of past achievements. Most clubs will not need this feature.
- isMentor is for coaches who coach or previously (isFormerMember to true) coached the club. They can have a Portfolio (e.g. with pictures of them or pictures of their own work).
- isProspectiveMember is a possible future member who is currently participating in some of the club activities, but is formally not a member yet. Most clubs will not need this feature.
- birthday can be the full date of birth but currently only the month and date are shown in the user interface. So you can provide a dummy year (like 9999) if that is preferred.
- website is a personal photography-related website. If available, the app provides a link to the website.
- featuredImage is a URL to a single image that can be shown beside the member's name in the membership list. It is visible in the Portfolios screen and the Who's Who screen.
- level3URL is URL to a file containing selected images made by this particular member in the context of a given photo club.

Note that the birthday, website, and isDeceased fields are technically special because they describe the photographer - and not the photographer as a member of a particular club. Usually this doesn't matter, but it can show up if the photographer is associated with multiple clubs, each with its own level2.json file (for example, a former photo club and the current photo club). Conceivably these multiple files may not agree on the value of birthday, website or isDeceased. The app currently will select the last answer it encountered. The problem should be very infrequent, but a workaround is to only fill in these fields in one of the level2.json files. In the future, we could implement software rules governing which answers to use if the files don't match.

Level 3. Adding Images

Level 3 requires providing links to the online images in member portfolios. Fotogroep Waalre in the Netherlands is an example of Level 3 club: you can view their portfolios via the Portfolios screen. Because a club with, for example, 20 members will have hundreds of images, we have a way to automate generate portfolios using Lightroom (instructions on how this works will be provided later).

Level 3 example (click to expand)

To do

Mandatory Level 3 fields (click to expand)

To do

Optional Level 3 fields (click to expand)

To do

(back to top)

Installation

If you simly want to install the binary version of the app, just install it from Apple's app store (link).

Built-With

Details (click to expand)

the Swift programming language
Apple's SwiftUI user interface framework
Apple's Core Data framework for persistent storage ("database")
Adobe Lightroom Classic maintaining the portfolios (so far Fotogroep Waalre only)
a low cost JuiceBox Pro JavaScript plugin for exporting from Adobe Lightroom (so far Fotogroep Waalre only)
GitHub's SwiftyJSON package for accessing JSON content via paths (dictionaries that recursively contain dictionaries)

Cloning the Repository

To install the source code locally, it is easiest to use GitHub’s Open with Xcode feature.

Details (click to expand)

Developers who are comfortable running git from the command line should manage on their own. Xcode covers the installation of the binary on a physical device or on an Xcode iPhone/iPad simulator.

Code Signing

Details (click to expand)

During the build you may be prompted to provide a developer license (personal or commercial) when you want to install the app on a physical device. This is a standard Apple iOS policy rather than something specific to this app.

Starting with iOS 16.0 you will also need to configure physical devices to allow them to run apps that have not been distributed via the Apple App Store. This configuration requires enabling Developer Mode on the device using Settings > Privacy & Security > Developer Mode. Again, this is a standard Apple iOS policy. This doesn't apply to MacOS.

Updating the App

If you update to a newer build of the app, all app data stored in the device's internal data storage will remain available.

Details (click to expand)

If you instead choose to remove and reinstall the app, the locally stored database content will be lost. This is how iOS works. Fortunately, this has no real implications for the user as the data storage doesn't presently contain any relevant user data. So essentially you can regard the database as a cache: it lets the app launch quicker without waiting for content that has alread been fetched during a previous session.

Schema Migration

Details (click to expand)

If the data structure has changed from one version to a later version, Core Data will automatically perform a so-called schema migration. If you remove and reinstall the app, the Core Data database is lost, but this isn't an issue as the database so far doesn't contain any user data. Schema migration is a standard feature of Apple's Core Data framework, although the app does its bit so that Core Data can track, for example, renamed struct types or renamed properties.

(back to top)

Contributing

Bug fixes and new features are welcome. Before investing effort in designing, coding testing, and refining features, it is best to first describe the idea or functional change within a new or existing GitHub Issue. That allows for some upfront discussion and prevents wasted effort due to overlapping initiatives.

You can submit an Issue with a tag like ”enhancement" or “bug” without commiting to make the code changes yourself. Essentially that is an idea, bug, or feature request, rather than an offer to help.

Developer contributions

Details(click to expand)

Possible contributions include adding features, code improvements, ideas on architecture and interface specifications, and possibly even a dedicated backend server.

Other contributions

Details(click to expand)

Contributions that do not involve coding include beta testing, thoughtful and detailed feature requests, translations, and icon design improvements.

(back to top)

The App Architecture

The app uses a SwiftUI-based MVVM architecture pattern.

MVVM Layers

Details (click to expand)

The use of a SwiftUI-based MVVM architecture implies that

the model's data is stored in lightweight structs rather than in classes. It also implies that any changes to the model's data automatically trigger the required updates to
the SwiftUI's struct-based Views, while
the intermediate class-based ViewModel layer translates between the Model and View layers.

Each of the layers has its own directory (found at the linked locations):

Model contains the data model. It contains the current version of the database model as well as older versions as separate files. This form of versioning is un-Git-like and is still used to support install-time schema migration.
View only contains SwiftUI views, which are at the Swift level structs that adhere to SwiftUI's View protocol.
ViewModel includes the code that populates and updates the database content ("model"). This layer is currently implemented per photo club, and stored a subdirectory per club.

Role of the Database

Details (click to expand)

The model's data is loaded and updated via the internet, and is stored in an on-device database. Internally the database is SQLite, but that is invisible because it is wrapped inside Apple's Core Data framework.

Because the data in the app's local database is available online, the app could have chosen to fetch that data over the network each time the app is launched. By using a database, however, the app launches faster: on startup, the app can already display the content of the on-device database.

This implies showing the state of the data as it was at the end of the previous session. That data might be a bit outdated, but is should be accurate enough to start off with.

To handle any data updates, asynchrous calls fetch fresher data over the network. And the MVVM architecture uses this to update the user interface Views as soon as the requested data arrives. So occasionally, maybe one or two seconds after the app launches, the user may see the Portfolios screen update. This can happen, for example if a club's online member list changed since the previous session.

To be precise, the above is the target architecture. Right now there are still a few gaps - but because it usually works well enough, a user typically won't notice:

the lists of images per portfolio are not stored in the database yet. These images are also not cached. Image caching is a roadmap item.
the image thumbnail per portfolio is stored in the database as a URL. The actual file is not stored locally or cached yet. Thumbnail caching is a roadmap item.
members who are removed from the online membership list are not automatically deleted from the database. This requires a bit more administration, because these individuals don't show up iterates through the online membership list. This is simply because those names/records are not on the online list anymore!
in the case of Fotogoep Waalre, some member data is not yet available online in a machine-readable form and is thus added programmatically instead. This is done in this file. This hardcoded data include the member's formal roles (e.g. chairman, treasurer).
Photo club data is minimal (name, town/country, GPS, website), but is currently still hardcoded.

Some of these gaps are addressed below.

The Data Model

Details (click to expand)

Here are the entities managed by the app's internal Core Data database. The entities (rounded boxes) are tables and arrows are relationships in the underlying SQLite database.

Note that the tables are fully "normalized" in the relational database sense. This means that redundancy in all stored data is minimized via referencing.

Optional properties in the database with names like PhotoClub.town_ have a corresponding computed property that is non-optional named PhotoClub.town. This allows PhotoClub.town to always return a String value such as "Unknown town" rather than an optional String? value.

Organization

Details (click to expand)

This table contains both photo clubs and musea. Many properties apply to both. The relationship to OrganizationType is used to distinguish betweene both. Currently OrganizationType (essentially an enum) has only two allowed values: club and museum. But, for example,festivals could also be added in the future.

An organization is uniquely identified by its name and a town. Including the town is necessary because two towns might have local photo clubs that happen to have the same name. This is unlikely for musea, but the same approach is used just in case.

An Organization has a rough address down to the town level and GPS coordinates. The GPS coordinates can precisely indicate where the club meets (often good enough for navigation purposes). The GPS coordinates are used to insert markers on a map. The GPS coordinates are also used to localize town and country names by asking an online mapping service to convert GPS coordinates into a textual address, using the device's current location as input.

Photographer

Details (click to expand)

Some basic information about a Photographer (name, date of birth, personal website, ...) is related to the Photographer as an individual, rather to the Photographer's membership of any specific PhotoClub. This club-independent information is stored in the individual's Photographer struct/record.

MemberPortfolio

Details (click to expand)

Every PhotoClub has (zero or more) Members who can have various roles (isChairman, isAdmin, ...) representing the tasks they perform in the photo club. A Member may have multiple roles within one PhotoClub (e.g., members is both isSecretary and isAdmin).

Members also have a status, the implicit default being isCurrent membership. Explicit status values include isFormer, isAspiring, isHonorary and isMentor.

Portfolio represents the work of one Photographer in the context of one PhotoClub. A Portfolio contains Images (the list is not stored in the database yet). An Image can show up in multiple Portfolios if the Photographer presented the same photo within multiple PhotoClubs.

Member and Portfolio can be considered synonyms from a modeling perspective: we create exactly one Portfolio for each PhotoClub that a Photographer became a Member of. And every Member of a PhotoClub has exactly one Portfolio - even if it still contains zero images - because this is needed to store information about this membership. This one-to-one relationship between Member and Portfolio allows them to be modelled using once concept (aka table) instead of two. We named that MemberPortfolio.

OrganizationType

Details (click to expand)

This is a tiny table used to hold the supported types of Organization records. It could be used someday to drive a picker in a data editing tool. For now, it ensures that each Organization belong to exactly one of the supported OrganizationTypes. And it could be used to generate statistics about how man Organizations per OrganizationType are supported.

Language

Details (click to expand)

The Language table is a tiny table to hold the languages supported by the root.level1.json file. For now, it is intended only to support the LocalizedRemark table. Initially a hardcoded equivalent is used to load localized remarks from root.level1.json.

By storing it in the database, the set of supported Languages in root.level1.json can be opened. For example, a museum in Portugal may have an English and a Portugues remark, even when the user interface is only localized to English and Dutch. This allows the app to display Portuguese text for the local museum if the device is set to Portuguese, while the user interface will be shown in English as long as Portuguese is not supported.

A side benefit of this approach is that localized remarks can be provided without having to wait until the app provides full support for a language.

LocalizedRemark

Details (click to expand)

The LocalizedRemark table holds brief remarks about an Organization in zero or more Languages. Remarks are optional, but we recommend providing them. The LocalizedRemark table is not filled yet. Instead the localized remark texts are temporarily stored in hard-coded property fields (remarkEN, remarkNL) in the Organization table.

An Organization record can be linked to 0, 1, 2 or more Languages regardless of whether the app fully supports that language. The ISO 2 or 3-letter code of the language and a readable name are stored in Language. The actual text shown in the user interface is shown in the LocalizedRemark table.

If the device is configured at the iOS level to use e.g. FR for French, the app will give priority to displaying LocalizedRemarks in French if encountered. Otherwise it defaults to English, if available. If the preferred langugages are not available, it will use a non-preferred language if available.

How Data is Loaded

Details (click to expand)

The Old Approach

Details (click to expand)

The app currently uses a software module per club. This means a club can concievably store their online list of members (MemberPortfolios) in any format. It is then up to the software module to convert it to the app's internal data representation. Similarly, a club could store their list of Images per member (MemberPortfolio) in any conceivable format as long as the software module does the conversion.

Thus, the software module per photo club loads membership and portfolio data across the network. The data will likely be stored on the club’s website somewhere, presumable in a simple file format. That data is then loaded into the in-app database, but also used to updated the database. This updating is done (on a background thread) whenever the app lauches, and thus takes care of changed membership lists as well as changed image portfolios.

For Photo Club Waalre, the membership list is read from an HTML table on a page on the club’s website. HTML is messy to parse, but also serves as a web page for the club's website.

In the case of Photo Club Waalre, the membership list is password protected in Wordpress and the app bypasses that password using a long key and the Wordpress Post Password Token plugin. The GitHub version uses a (redacted) copy of the membership list in order to show real data. Details about these details can be found above.

The image lists or portfolios use a more robust and easier to maintain approach: for Photo Club Waalre, portfolios are read from XML files generated by an Adobe Lightroom Web plug-in called JuiceBox-Pro. Thus portfolios are created and maintained within a Lightroom Classic catalog as a set of Lightroom collections. A portfolio can be uploaded or updated to the webserver using the Upload (ftp) button of Lightroom's Web module. This triggers JuiceBox-Pro to generate an XML index file for the portfolio and to upload the actual images to the server. All required settings (e.g. copyright, choice of directory) only need to be configured once per portfolio (=member).

The New Approach

Details (click to expand)

A major design goal for the near future is to provide a clean, standardized interface to retrieve data per photo club. This data is then loaded into into the in-app CoreData database. It is also needed to keep the CoreData database up to date whenever clubs, members or images are added. The old approach is essentially a plug-in design with an adaptor per photo club.

The new approach replaces this by a standardizable data interface to avoid having to modify the source code to add (or modify/remove) clubs, members or images. The basic idea here is to store the required information in a hierarchical, distributed way. This allows the app to load the information in a three step process:

Level 1: central list of photo clubs

The app loads a list of photo clubs from a fixed location (URL). Because the file is kept external to the actual app, the list can be updated without requiring an app software update. The file is in a fixed JSON syntax and contains a list of supported photo clubs.

As a bonus, the list can also contain information about photography museums. The properties of clubs and museums largely overlap, but a photo club can notably include the location (URL) of a level2.json data source while a museum cannot.

Level 2: local lists of photo club members

Each `Level 2` list defines the current (and potentially former) members of a single club. For each member, a URL is stored pointing to the final list level (portfolio per member). `Level 2` lists also include the URL of an image used as thumbnail for that member. `Level 2` lists can be stored and managed on the club's own server. The file needs to be in a JSON format to allow the app to interpret it correctly. A future editing tool (app or web-based) would help ensure syntactic and schema consistency.

Level 3: local image portfolios per club member

The list of images (per club member) is fetched only when a portfolio is selected for viewing. There is thus no need to prefetch the entire 3-level tree (Level 1 / Level 2 / Level 3). Again, this index needs to be in a fixed format, and thus will possibly require an editing tool to guard the syntax. Currently this tool already exists: index and files are exported from Lightroom using a Web plug-in. Depending on local preference, this level can be managed by a club volunteer, or distributed across the individual club members. In the latter case, a portfolio can be updated whenever a member wants. In the former (and more formal) case, the club can have some kind of approval or rating system in place.

When Data is Loaded

Details (click to expand)

Background Threads

Details (click to expand)

Membership lists are loaded into Core Data using a dedicated background thread per photo club. So if, for example, 10 clubs are loaded, there will be a main thread for SwiftUI, a few predefined lower priority threads, plus 10 temporary background threads (one per club). Each background thread reads optional data stored inside the app itself, and then reads optional online data. A club's background thread disappears as soon as the club’s membership data is fully loaded.

These threads start immediately once the app is launched (in Foto_Club_Hub_Waalre_App.swift). This means that background loading of membership data already starts while the Prelude View is displayed.

SwiftUI View Updates

Details (click to expand)

It also means that slow background threads might complete after the list of members is displayed in the Portfolio View. This may cause an update of the membership lists in the Portfolio View. This will be rarely noticed because the Portfolio View displays data from the Core Data database, and thus usually arleady contains data persisted from a preceding run. But you might see updates found within the online data or updates when the app is run for the first time.

Core Data Contexts

Details (click to expand)

Each thread is associated with a Core Data NSManagedObjectContext]. In fact, the thread is started using myContext.perform(). The trick to using Core Data in a multi-threaded app is to ensure that all database fetches/inserts/updates are performed using the Core Data NSManagedObjectContext while running the associated thread. Schematically:

create NSManagedObjectContext of type Background. A CoreData feature.
- create thread using myContext.perform(). A CoreData feature using an OS feature.
  - perform database operations from within the thread while passing this CoreData context. A CoreData feature.
  - commit data to database using myContext.save(). A CoreData feature.
  - do any other required operations ended by additional myContext.save(). A CoreData feature.
- end usage of the thread. The thread will disappear. A Swift feature.
the myContext object disappears when it is no longer used. A Swift feature.

The magic happens within myContext.save(). During the myContext.save() any changes are committed to the database so that other threads can now see those changes and the changes are persistently stored. Note that myContext.save() can throw an exception - especially if there are inconsistencies such as data merge conflicts, or violations of database constraints.

Comparison to SQL Transactions

Details (click to expand)

A Core Data NSManagedObjectContext can be seen as a counterpart to an SQL transactions.

create thread. An OS/language feature.
- start transaction. An SQL feature.
  - perform SQL operations from within a thread. This is implicitly within the transaction context. An SQL feature.
  - end transaction (commit or rollback). SQL feature.
- optionally start a next transaction (begin transaction > SQL operations > commit transaction)
end thread. An OS/language feature.

(back to top)

Administrative

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Peter van den Hamer - vdhamer@gmail.com

Project Link: https://GitHub.com/vdhamer/PhotoClubWaalre

Acknowledgments

The opening Prelude screen uses a photo of colorful building by Greetje van Son.
The interactive Roadmap screen uses the AvdLee/Roadmap package. The screen is currently disabled because the backend provider of Roadmap stopped supporting it.
The diagram with Core Data entities was generated using the Core Data Model Editor tool by Stéphane Millet.
JSON parsing uses the SwiftyJSON/SwiftyJSON package.

(back to top)

Name		Name	Last commit message	Last commit date
Latest commit History 2,116 Commits
.github		.github
Assets.xcassets		Assets.xcassets
Extensions		Extensions
Localization		Localization
Photo Club Hub.xcodeproj		Photo Club Hub.xcodeproj
Photo Club Hub		Photo Club Hub
SwiftyJSON		SwiftyJSON
nl.lproj		nl.lproj
.gitignore		.gitignore
Photo-Club-Hub-Info.plist		Photo-Club-Hub-Info.plist

vdhamer/Photo-Club-Hub

Folders and files

Latest commit

History

Repository files navigation

Table of Contents

About the Project

The App

Photo Clubs

Implications

The User Interface Screens

The Portfolios Screen

The Clubs and Museums Screen

The Images Screen

The Preferences Screen

The Readme Screen

The Who's Who Screen

The Prelude Screen

Features

Multi-club Support

Searchable Lists

Photo Museums

Swipe to Delete

Adding Photo Clubs to the App

Level 1. Adding Clubs

Level 2. Adding Members

Level 3. Adding Images

Installation

Built-With

Cloning the Repository

Code Signing

Updating the App

Schema Migration

Contributing

Developer contributions

Other contributions

The App Architecture

MVVM Layers

Role of the Database

The Data Model

Organization

Photographer

MemberPortfolio

OrganizationType

Language

LocalizedRemark

How Data is Loaded

The Old Approach

The New Approach

When Data is Loaded

Background Threads

SwiftUI View Updates

Core Data Contexts

Comparison to SQL Transactions

Administrative

License

Contact

Acknowledgments

About

Topics

Resources

Stars

Watchers

Forks

Languages

The `Portfolios` Screen

The `Clubs and Museums` Screen

The `Images` Screen

The `Preferences` Screen

The `Readme` Screen

The `Who's Who` Screen

The `Prelude` Screen