lutaml-hal 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5a918f01a4197929abfdbbdd1e061ecff5d37592ed0c880024ec11f6abe2943
-  data.tar.gz: 032f6ba78ced7adefc4b6a9ce9c2c76acc25eba6b9d3d96398f3f09d330d312b
+  metadata.gz: da904351e361ae9657c850d5faf981c6b698583970ead3320f125fdf6078fcbb
+  data.tar.gz: 677a8d713e5c2499cd9250497ca2b6f2d9474e545a2d2b2989dbcd33802b5588
 SHA512:
-  metadata.gz: '0802c9c05fbb34fc5a8d53a023cdd1cfda2291305b597387a5cc7afc665c9aa7eac542f03840cac494389c49442a030e79e7fdcf2169d992747e7a707fc4d9fa'
-  data.tar.gz: 7ecabcdc778455d9d4fee7b9708c7754891ab64e3da5edb6b88927cc687806b3c5863dde63b89aa785cdcf8174c431b58fa862e0a6443e456faad13fcced0faf
+  metadata.gz: d1d55faaa7c1f7d45b07a3d475b6908de807f7bed3bfebdfa32ce0ada2b91a1794f948046e0e0c554216f5e18219c07ee81dfb03a2ee0f5fb19e3367821e40fb
+  data.tar.gz: '07085ed8d705dfe5ff1893e1c9d2ab7bc87fe3b22e483dc14edfb1b89b2e54942e21fa38f6c1ff7910030fb57c6ecf198110fa70ef8447a49c377de2935873d8'

data/README.adoc

@@ -580,6 +580,69 @@ register.add_endpoint(
 ====
 
 
+[[defining_hal_page_models]]
+=== Defining HAL page models
+
+HAL index APIs often support pagination, which allows clients to retrieve a
+limited number of resources at a time.
+
+The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs. It is a
+subclass of `Resource`, and provides additional attributes and methods for
+handling pagination information
+
+The `Page` class by default supports the following attributes:
+
+`page`:: The current page number.
+`pages`:: The total number of pages.
+`limit`:: The number of resources per page.
+`total`:: The total number of resources.
+
+The way to use the `Page` class is through inheritance from it, where the
+class will automatically create the necessary links for typical page objects.
+
+The typical links of a page object are:
+
+`self`:: A link to the current page.
+`prev`:: A link to the previous page.
+`next`:: A link to the next page.
+`first`:: A link to the first page.
+`last`:: A link to the last page.
+
+The "realize class" of these links are the same as the inherited page
+object, ensuring consistency in the pagination model.
+
+Syntax:
+
+[source,ruby]
+----
+class ProductIndex < Lutaml::Hal::Page
+  # No attributes necessary
+end
+
+register.add_endpoint(
+  id: :product_index,
+  type: :index,
+  url: '/products',
+  model: ProductIndex
+)
+
+page_1 = register.fetch(:product_index)  # Updated to use the correct endpoint id
+page_2_link = page_1.links.next
+# => <#ProductIndexLink href: "/products/2", title: "Next Page">
+----
+
+Where,
+
+`ProductIndex`:: The class of the page that will be fetched from the API. The class
+must inherit from `Lutaml::Hal::Page`.
+`register`:: The instance of `ModelRegister`.
+`id`:: The ID of the pagination endpoint to be registered in the `ModelRegister`.
+`url`:: The URL of the pagination endpoint.
+`model`:: The class of the page that will be fetched from the API.
+
+
+
+
 == Usage: Runtime
 
 === General
@@ -668,9 +731,6 @@ them using the `fetch` method.
 The `fetch` method will automatically handle the URL resolution and fetch the
 resource index from the API.
 
-// The `Page` class is used to handle pagination and resource
-// resolution for collections.
-
 Syntax:
 
 [source,ruby]
@@ -785,51 +845,13 @@ product_2
 ----
 ====
 
-=== Pagination
-
-HAL index APIs often support pagination, which allows clients to retrieve a
-limited number of resources at a time.
-
-The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs. The
-`Page` class itself is implemented as a `Resource`, so you can use the same
-methods to access the page's attributes and links.
-
-The `Page` class by default supports the following attributes:
-
-`page`:: The current page number.
-`pages`:: The total number of pages.
-`limit`:: The number of resources per page.
-`total`:: The total number of resources.
-
-Syntax:
-
-[source,ruby]
-----
-class MyPage < Lutaml::Hal::Page
-  # These are typical links given for page objects
-  hal_link :self, key: 'self', realize_class: 'MyPage'
-  hal_link :prev, key: 'prev', realize_class: 'MyPage'
-  hal_link :next, key: 'next', realize_class: 'MyPage'
-  hal_link :first, key: 'first', realize_class: 'MyPage'
-  hal_link :last, key: 'last', realize_class: 'MyPage'
-end
-
-register.add_endpoint(
-  id: :my_pages,
-  type: :index,
-  url: '/my_pages',
-  model: MyPage
-)
-----
+=== Handling HAL pages / pagination
 
-Where,
+The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs.
 
-`MyPage`:: The class of the page that will be fetched from the API. The class
-must inherit from `Lutaml::Hal::Page`.
-`register`:: The instance of `ModelRegister`.
-`id`:: The ID of the pagination endpoint to be registered in the `ModelRegister`.
-`url`:: The URL of the pagination endpoint.
-`model`:: The class of the page that will be fetched from the API.
+As described in <<defining_hal_page_models>>, subclassing the `Page` class
+provides pagination capabilities, including the management of links to navigate
+through pages of resources.
 
 
 .Usage example of the Page class
@@ -839,19 +861,15 @@ Declaration:
 
 [source,ruby]
 ----
-class MyPage < Lutaml::Hal::Page
-  hal_link :self, key: 'self', realize_class: 'MyPage'
-  hal_link :prev, key: 'prev', realize_class: 'MyPage'
-  hal_link :next, key: 'next', realize_class: 'MyPage'
-  hal_link :first, key: 'first', realize_class: 'MyPage'
-  hal_link :last, key: 'last', realize_class: 'MyPage'
+class ResourceIndex < Lutaml::Hal::Page
+  # No attribute definition necessary
 end
 
 register.add_endpoint(
-  id: :my_pages,
+  id: :resource_index,
   type: :index,
-  url: '/my_pages',
-  model: MyPage
+  url: '/resources',
+  model: ResourceIndex
 )
 ----
 
@@ -859,32 +877,46 @@ Usage:
 
 [source,ruby]
 ----
-page_1 = register.fetch(:my_pages)
-# => client.get('/my_pages')
+page_1 = register.fetch(:resource_index)
+# => client.get('/resources')
 # => {
 #   "page": 1,
 #   "pages": 10,
 #   "limit": 10,
 #   "total": 100,
 #   "_links": {
-#     "self": { "href": "/my_pages" },
-#     "next": { "href": "/my_pages/2" },
-#     "last": { "href": "/my_pages/9" }
+#     "self": {
+#       "href": "https://api.example.com/resources?page=1&items=10"
+#     },
+#     "first": {
+#       "href": "https://api.example.com/resources?page=1&items=10"
+#     },
+#     "last": {
+#       "href": "https://api.example.com/resources?page=10&items=10"
+#     },
+#     "next": {
+#       "href": "https://api.example.com/resources?page=2&items=10"
+#     }
 #   }
 # }
+
 page_1
-# => #<MyPage page: 1, pages: 10, limit: 10, total: 100,
-#      links: #<MyPageLinks self: <MyPageLink href: "/my_pages">,
-#                     next: <MyPageLink href: "/my_pages/2">,
-#                     last: <MyPageLink href: "/my_pages/9">>>
+# => #<ResourceIndex page: 1, pages: 10, limit: 10, total: 100,
+#      links: #<ResourceIndexLinks
+#                self: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                next: #<ResourceIndexLink href: "/resources?page=2&items=10">,
+#                last: #<ResourceIndexLink href: "/resources?page=10&items=10">>>
+
 page_2 = page.links.next.realize(register)
-# => client.get('/my_pages/2')
-# => #<MyPage page: 2, pages: 10, limit: 10, total: 100,
-#      links: #<MyPageLinks self: <MyPageLink href: "/my_pages/2">,
-#                     prev: <MyPageLink href: "/my_pages/1">,
-#                     next: <MyPageLink href: "/my_pages/3">,
-#                     first: <MyPageLink href: "/my_pages/1">,
-#                     last: <MyPageLink href: "/my_pages/9">>>
+# => client.get('/resources?page=2&items=10')
+# => #<ResourceIndex page: 2, pages: 10, limit: 10, total: 100,
+#      links: #<ResourceIndexLinks
+#                self: #<ResourceIndexLink href: "/resources?page=2&items=10">,
+#                prev: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                next: #<ResourceIndexLink href: "/resources?page=3&items=10">,
+#                first: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                last: #<ResourceIndexLink href: "/resources?page=10&items=10">>>,
+#                prev: #<ResourceIndexLink href: "/resources?page=1&items=10">>>
 ----
 ====
 

data/lib/lutaml/hal/page.rb

@@ -19,6 +19,19 @@ module Lutaml
         map 'pages', to: :pages
         map 'total', to: :total
       end
+
+      def self.inherited(subclass)
+        super
+
+        page_links_symbols = %i[self next prev first last]
+        subclass_name = subclass.name
+        subclass.class_eval do
+          # Define common page links
+          page_links_symbols.each do |link_symbol|
+            hal_link link_symbol, key: link_symbol.to_s, realize_class: subclass_name
+          end
+        end
+      end
     end
   end
 end

data/lib/lutaml/hal/resource.rb

@@ -70,7 +70,7 @@ module Lutaml
         def get_links_class
           parent_klass_name = name.split('::')[0..-2].join('::')
           child_klass_name = "#{name.split('::').last}LinkSet"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
 
           raise unless Object.const_defined?(klass_name)
 
@@ -84,7 +84,7 @@ module Lutaml
         def create_link_set_class
           parent_klass_name = name.split('::')[0..-2].join('::')
           child_klass_name = "#{name.split('::').last}LinkSet"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
 
           # Check if the LinkSet class is already defined, return if so
           return Object.const_get(klass_name) if Object.const_defined?(klass_name)
@@ -92,9 +92,8 @@ module Lutaml
           # Define the LinkSet class dynamically as a normal Lutaml::Model class
           # since it is not a Resource
           klass = Class.new(Lutaml::Model::Serializable)
-          Object.const_get(parent_klass_name).tap do |parent_klass|
-            parent_klass.const_set(child_klass_name, klass)
-          end
+          parent_klass = !parent_klass_name.empty? ? Object.const_get(parent_klass_name) : Object
+          parent_klass.const_set(child_klass_name, klass)
 
           # Define the LinkSet class with mapping inside the current class
           class_eval do
@@ -113,7 +112,7 @@ module Lutaml
         def create_link_class(realize_class_name)
           parent_klass_name = name.split('::')[0..-2].join('::')
           child_klass_name = "#{name.split('::').last}Link"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
 
           return Object.const_get(klass_name) if Object.const_defined?(klass_name)
 
@@ -122,9 +121,9 @@ module Lutaml
             # Define the link class with the specified key and class
             attribute :type, :string, default: realize_class_name
           end
-          Object.const_get(parent_klass_name).tap do |parent_klass|
-            parent_klass.const_set(child_klass_name, klass)
-          end
+
+          parent_klass = !parent_klass_name.empty? ? Object.const_get(parent_klass_name) : Object
+          parent_klass.const_set(child_klass_name, klass)
 
           klass
         end

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.1.2'
+    VERSION = '0.1.3'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Ribose Inc.